diff --git a/Kconfig b/Kconfig index e4c1a89b16..ad049f5dbf 100644 --- a/Kconfig +++ b/Kconfig @@ -46,11 +46,11 @@ mainmenu "Espressif IoT Development Framework Configuration" The executable name/path that is used to run python. On some systems Python 2.x may need to be invoked as python2. - (Note: This option is used with the GNU Make build system only, not idf.py - or CMake-based builds.) + (Note: This option is used with the legacy GNU Make build system only.) config SDK_MAKE_WARN_UNDEFINED_VARIABLES bool "'make' warns on undefined variables" + depends on !IDF_CMAKE default "y" help Adds --warn-undefined-variables to MAKEFLAGS. This causes make to @@ -60,6 +60,8 @@ mainmenu "Espressif IoT Development Framework Configuration" or otherwise missing, but it can be unwanted if you have Makefiles which depend on undefined variables expanding to an empty string. + (Note: this option is used with the legacy GNU Make build system only.) + endmenu # SDK tool configuration source "$COMPONENT_KCONFIGS_PROJBUILD" diff --git a/README.md b/README.md index bbb8d3a54b..19c9980dd2 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,17 @@ To start your own project based on an example, copy the example project director 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 Getting Started guide for a full list of required steps with details.) + +* Install host build dependencies mentioned in Getting Started guide. +* Add `tools/` directory to the PATH +* Run `python -m pip install requirements.txt` to install Python dependencies + ## Configuring the Project -`make menuconfig` +`idf.py menuconfig` * Opens a text-based configuration menu for the project. * Use up & down arrow keys to navigate the menu. @@ -49,76 +57,48 @@ Once done configuring, press Escape multiple times to exit and say "Yes" to save ## Compiling the Project -`make -j4 all` +`idf.py build` ... will compile app, bootloader and generate a partition table based on the config. -NOTE: The `-j4` option causes `make` to run 4 parallel jobs. This is much faster than the default single job. The recommended number to pass to this option is `-j(number of CPUs + 1)`. - ## Flashing the Project When the build finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this automatically by running: -`make -j4 flash` +`idf.py -p PORT flash` -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 `make menuconfig`. +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. -You don't need to run `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it. +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 `make monitor` target uses the [idf_monitor tool](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html). +The `idf.py monitor` target uses the [idf_monitor tool](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html). Exit the monitor by typing Ctrl-]. To build, flash and monitor output in one pass, you can run: -`make -j4 flash monitor` +`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: -* `make app` - build just the app. -* `make app-flash` - flash just the app. +* `idf.py app` - build just the app. +* `idf.py app-flash` - flash just the app. -`make app-flash` will automatically rebuild the app if any source files have changed. +`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.) -## Parallel Builds - -ESP-IDF supports compiling multiple files in parallel, so all of the above commands can be run as `make -jN` where `N` is the number of parallel make processes to run (generally N should be equal to the number of CPU cores in your system, plus one.) - -Multiple make functions can be combined into one. For example: to build the app & bootloader using 5 jobs in parallel, then flash everything, and then display serial output from the ESP32 run: - -``` -make -j5 flash monitor -``` - - -## The Partition Table - -Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader. - -A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x8000 in the flash. - -Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded. - -The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables: - -* "Single factory app, no OTA" -* "Factory app, two OTA definitions" - -In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table. - -For more details about partition tables and how to create custom variations, view the [`docs/en/api-guides/partition-tables.rst`](docs/en/api-guides/partition-tables.rst) file. - ## Erasing Flash -The `make 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 `make erase_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 `make erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table. +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 diff --git a/components/esptool_py/Kconfig.projbuild b/components/esptool_py/Kconfig.projbuild index 95919bd007..e11f9c7d50 100644 --- a/components/esptool_py/Kconfig.projbuild +++ b/components/esptool_py/Kconfig.projbuild @@ -135,8 +135,9 @@ menu "Serial flasher config" bool "Detect flash size when flashing bootloader" default y help - If this option is set, 'make flash' targets will automatically detect - the flash size and update the bootloader image when flashing. + If this option is set, flashing the project will automatically detect + the flash size of the target chip and update the bootloader image + before it is flashed. choice ESPTOOLPY_BEFORE prompt "Before flashing" @@ -181,11 +182,11 @@ menu "Serial flasher config" default "no_reset" if ESPTOOLPY_AFTER_NORESET choice ESPTOOLPY_MONITOR_BAUD - prompt "'make monitor' baud rate" + prompt "'idf.py monitor' baud rate" default ESPTOOLPY_MONITOR_BAUD_115200B help - Baud rate to use when running 'make monitor' to view serial output - from a running chip. + Baud rate to use when running 'idf.py monitor' or 'make monitor' + to view serial output from a running chip. Can override by setting the MONITORBAUD environment variable. diff --git a/components/nvs_flash/README.rst b/components/nvs_flash/README.rst index f8c2f4a1f6..4638b644bc 100644 --- a/components/nvs_flash/README.rst +++ b/components/nvs_flash/README.rst @@ -14,7 +14,7 @@ Currently, NVS uses a portion of main flash memory through ``spi_flash_{read|wri Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc. -.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``make erase_flash`` target to erase all contents of the flash chip. +.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``idf.py erase_flash`` target to erase all contents of the flash chip. .. note:: NVS works best for storing many small values, rather than a few large values of the type 'string' and 'blob'. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library. diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index 782dfbba96..f9c7ecaa09 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -73,7 +73,7 @@ SPI Flash Size The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000. -By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. +By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in project configuration. If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``esp_flash_*`` functions (in both software & ROM) to check the bounds. diff --git a/components/spi_flash/README_legacy.rst b/components/spi_flash/README_legacy.rst index a8e5da15a6..a9a2c69135 100644 --- a/components/spi_flash/README_legacy.rst +++ b/components/spi_flash/README_legacy.rst @@ -29,7 +29,7 @@ SPI Flash Size The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000. -By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. +By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in project configuration. If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``spi_flash_*`` functions (in both software & ROM) to check the bounds. diff --git a/docs/TEMPLATE_EXAMPLE_README.md b/docs/TEMPLATE_EXAMPLE_README.md index 81bf6b3421..c641f8d64d 100644 --- a/docs/TEMPLATE_EXAMPLE_README.md +++ b/docs/TEMPLATE_EXAMPLE_README.md @@ -23,21 +23,21 @@ _If any other items (server, BLE device, app, second chip, whatever) are needed, ### Configure the project ``` -make menuconfig +idf.py menuconfig ``` -* Set serial port under Serial Flasher Options. - -* _If there is any menuconfig configuration that the user user must set for this example, mention this here._ +* _If there is any project configuration that the user must set for this example, mention this here._ ### Build and Flash Build the project and flash it to the board, then run monitor tool to view serial output: ``` -make -j4 flash monitor +idf.py -p PORT flash monitor ``` +(Replace PORT with the name of the serial port to use.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. diff --git a/docs/en/api-guides/console.rst b/docs/en/api-guides/console.rst index 5119d3ae2f..3f10279db8 100644 --- a/docs/en/api-guides/console.rst +++ b/docs/en/api-guides/console.rst @@ -16,7 +16,7 @@ Line editing Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key. -.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``make monitor`` from project directory). +.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory). Here is an overview of functions provided by `linenoise`_ library. diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 536d999efb..c590efeea7 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -16,7 +16,7 @@ ESP-IDF provides special script `espcoredump.py` to help users to retrieve and a Configuration ------------- -There are a number of core dump related configuration options which user can choose in configuration menu of the application (`make menuconfig`). +There are a number of core dump related configuration options which user can choose in project configuration menu (`idf.py menuconfig`). 1. Core dump data destination (`Components -> ESP32-specific config -> Core dump -> Data destination`): @@ -93,7 +93,7 @@ Generic command syntax: * --gdb,-g GDB. Path to gdb to use for data retrieval. * --core,-c CORE. Path to core dump file to use (if skipped core dump will be read from flash). * --core-format,-t CORE_FORMAT. Specifies that file passed with "-c" is an ELF ("elf"), dumped raw binary ("raw") or base64-encoded ("b64") format. - * --off,-o OFF. Offset of coredump partition in flash (type `make partition_table` to see it). + * --off,-o OFF. Offset of coredump partition in flash (type `idf.py partition_table` to see it). * --save-core,-s SAVE_CORE. Save core to file. Othwerwise temporary core file will be deleted. Ignored with "-c". * --rom-elf,-r ROM_ELF. Path to ROM ELF file to use (if skipped "esp32_rom.elf" is used). * --print-mem,-m Print memory dump. Used only with "info_corefile". diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index ac3a49ec84..558f43ecde 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -74,8 +74,9 @@ used to free memory pointed to by TLSP. Call Callbacks. :ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be -configured using ``make meunconfig`` such as running ESP-IDF in Unicore Mode, -or configuring the number of Thread Local Storage Pointers each task will have. +set in the project configuration (``idf.py menuconfig``) such as running ESP-IDF in +Unicore (single core) Mode, or configuring the number of Thread Local Storage Pointers +each task will have. .. _backported-features: @@ -478,10 +479,10 @@ For more details see :doc:`FreeRTOS API reference<../api-reference/system/freert Configuring ESP-IDF FreeRTOS ---------------------------- -The ESP-IDF FreeRTOS can be configured using ``make menuconfig`` under -``Component_Config/FreeRTOS``. The following section highlights some of the -ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF -FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` +The ESP-IDF FreeRTOS can be configured in the project configuration menu +(``idf.py menuconfig``) under ``Component Config/FreeRTOS``. The following section +highlights some of the ESP-IDF FreeRTOS configuration options. For a full list of +ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only on **PRO_CPU**. Note that this is **not equivalent to running vanilla diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index ecf2367925..91fe17e0e3 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -11,12 +11,12 @@ Partition table length is 0xC00 bytes (maximum 95 partition table entries). An M Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded. -The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables: +The simplest way to use the partition table is to open the project configuration menu (``idf.py menuconfig``) and choose one of the simple predefined partition tables under :ref:`CONFIG_PARTITION_TABLE_TYPE`: * "Single factory app, no OTA" * "Factory app, two OTA definitions" -In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table. +In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition_table` then it will print a summary of the partition table. Built-in Partition Tables ------------------------- @@ -100,7 +100,7 @@ The 8-bit subtype field is specific to a given partition type. esp-idf currently - phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware. - In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space. - - To load PHY data from this partition, run ``make menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. + - To load PHY data from this partition, open the project configuration menu (``idf.py menuconfig``) and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. - nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`. - NVS is used to store per-device PHY calibration data (different to initialisation data). @@ -138,7 +138,7 @@ Generating Binary Partition Table The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats. -If you configure the partition table CSV name in ``make menuconfig`` and then ``make partition_table``, this conversion is done as part of the build process. +If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process. To convert CSV to Binary manually:: @@ -148,7 +148,7 @@ To convert binary format back to CSV manually:: python gen_esp32part.py binary_partitions.bin input_partitions.csv -To display the contents of a binary partition table on stdout (this is how the summaries displayed when running `make partition_table` are generated:: +To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition_table`` are generated:: python gen_esp32part.py binary_partitions.bin @@ -162,12 +162,12 @@ The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option o Flashing the partition table ---------------------------- -* ``make partition_table-flash``: will flash the partition table with esptool.py. -* ``make flash``: Will flash everything including the partition table. +* ``idf.py partition_table-flash``: will flash the partition table with esptool.py. +* ``idf.py flash``: Will flash everything including the partition table. -A manual flashing command is also printed as part of ``make partition_table``. +A manual flashing command is also printed as part of ``idf.py partition_table`` output. -Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``make erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents. +Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents. Partition Tool (parttool.py) ---------------------------- diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index 88e89d8f22..cf5bd285ff 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -6,11 +6,9 @@ IDF Monitor The IDF monitor tool is mainly a serial terminal program which relays serial data to and from the target device's serial port. It also provides some IDF-specific features. -This tool can be launched by invoking in IDF the following target: - -- **For make**: ``make monitor`` -- **For cmake**: ``idf.py monitor`` +This tool can be launched from an IDF project by running ``idf.py monitor``. +(For the legacy GNU Make system, run ``make monitor``.) Keyboard Shortcuts ================== @@ -32,7 +30,7 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | - Ctrl+R | Reset target board via RTS | Resets the target board and re-starts the application via the RTS line (if connected). | +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the ``make flash`` (``idf.py flash``) target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. | +| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. | +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | - Ctrl+A (or A) | Build and flash the app only | Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. | +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -103,7 +101,7 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware. -To enable GDBStub, run ``make menuconfig`` (for make) or ``idf.py menuconfig`` (for cmake) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. +To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button. @@ -115,7 +113,7 @@ In the background, IDF Monitor runs the following command:: Output Filtering ~~~~~~~~~~~~~~~~ -IDF monitor can be invoked as ``make monitor PRINT_FILTER=""`` (for make) or ``idf.py monitor --print-filter=""`` (for cmake), where ``PRINT_FILTER`` is the parameter for output filtering. The default value is an empty string, which means that everything is printed. +IDF monitor can be invoked as ``idf.py monitor --print-filter="xyz"``, where ``--print-filter`` is the parameter for output filtering. The default value is an empty string, which means that everything is printed. Restrictions on what to print can be specified as a series of ``:`` items where ```` is the tag string and ```` is a character from the set ``{N, E, W, I, D, V, *}`` referring to a level for :doc:`logging <../../api-reference/system/log>`. @@ -188,18 +186,6 @@ The captured output for the filtering options ``PRINT_FILTER="wifi esp_image:E l D (309) light_driver: [light_init, 74]:status: 1, mode: 2 -Simple Monitor -============== - -The earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program. - -.. note:: This target only works in a build system based on GNU Make and cannot work in a CMake-based system. - -This program can still be run with the command ``make simple_monitor``. - -IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts. - - Known Issues with IDF Monitor ============================= diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index e59c3cc751..8eee8cffd9 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -50,7 +50,7 @@ To compile ULP code as part of a component, the following steps must be taken: include $(IDF_PATH)/components/ulp/component_ulp_common.mk Includes common definitions of ULP build steps. Defines build targets for ULP object files, ELF file, binary file, etc. -3. Build the application as usual (e.g. `make app`) +3. Build the application as usual (e.g. ``idf.py build`` or ``idf.py app``) Inside, the build system will take the following steps to build ULP program: diff --git a/docs/en/api-reference/kconfig.rst b/docs/en/api-reference/kconfig.rst index a98de1e605..4fc49900b4 100644 --- a/docs/en/api-reference/kconfig.rst +++ b/docs/en/api-reference/kconfig.rst @@ -1,19 +1,28 @@ -Configuration Options +Project Configuration ********************* Introduction ============ -ESP-IDF uses Kconfig_ system to provide a compile-time configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc. +ESP-IDF uses Kconfig_ system to provide a compile-time project configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc. -Applications developers can use ``make menuconfig`` build target to edit components' configuration. This configuration is saved inside ``sdkconfig`` file in the project root directory. Based on ``sdkconfig``, application build targets will generate ``sdkconfig.h`` file in the build directory, and will make sdkconfig options available to component makefiles. +.. _project-configuration-menu: + +Project Configuration Menu +========================== + +Application developers can open a terminal-based project configuration menu with the ``idf.py menuconfig`` build target. + +After being updated, this configuration is saved inside ``sdkconfig`` file in the project root directory. Based on ``sdkconfig``, application build targets will generate ``sdkconfig.h`` file in the build directory, and will make sdkconfig options available to the project build system and source files. + +(For the legacy GNU Make build system, the project configuration menu is opened with ``make menuconfig``.) Using sdkconfig.defaults ======================== When updating ESP-IDF version, it is not uncommon to find that new Kconfig options are introduced. When this happens, application build targets will offer an interactive prompt to select values for the new options. New values are then written into ``sdkconfig`` file. To supress interactive prompts, applications can either define ``BATCH_BUILD`` environment variable, which will cause all prompts to be suppressed. This is the same effect as that of ``V`` or ``VERBOSE`` variables. Alternatively, ``defconfig`` build target can be used to update configuration for all new variables to the default values. -In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the ``sdkconfig`` file. Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for git). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that when ``make defconfig`` is used, settings in sdkconfig will be overriden by the ones in ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`. +In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the ``sdkconfig`` file. Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for git). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that when ``idf.py defconfig`` is used, settings in sdkconfig will be overriden by the ones in ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`. Kconfig Formatting Rules ======================== diff --git a/docs/en/api-reference/protocols/mqtt.rst b/docs/en/api-reference/protocols/mqtt.rst index 053159eba0..cb956755a6 100644 --- a/docs/en/api-reference/protocols/mqtt.rst +++ b/docs/en/api-reference/protocols/mqtt.rst @@ -94,12 +94,12 @@ SSL For more options on ``esp_mqtt_client_config_t``, please refer to API reference below -Change settings in ``menuconfig`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Change settings in Project Configuration Menu +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - make menuconfig - -> Component config -> ESP-MQTT Configuration + idf.py menuconfig + -> Component config -> ESP-MQTT Configuration - :ref:`CONFIG_MQTT_PROTOCOL_311`: Enables 3.1.1 version of MQTT protocol diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index dd8c6bd993..87a9e1624d 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -31,8 +31,8 @@ The component has API functions for reading and writing fields. Access to the fi CSV files: -* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command 'make efuse_common_table' or `idf.py efuse_common_table`). Note that changes in this file can lead to incorrect operation. -* custom - (optional and can be enabled by :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file (run command 'make efuse_custom_table' or `idf.py efuse_custom_table`). +* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command ``idf.py efuse_common_table``). Note that changes in this file can lead to incorrect operation. +* custom - (optional and can be enabled by :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running ``idf.py efuse_custom_table``. Description CSV file @@ -84,7 +84,7 @@ efuse_table_gen.py tool The tool is designed to generate C-source files from CSV file and validate fields. First of all, the check is carried out on the uniqueness of the names and overlaps of the field bits. If an additional `custom` file is used, it will be checked with the existing `common` file (esp_efuse_table.csv). In case of errors, a message will be displayed and the string that caused the error. C-source files contain structures of type `esp_efuse_desc_t`. -To generate a `common` files, use the following command 'make efuse_common_table' or `idf.py efuse_common_table` or: +To generate a `common` files, use the following command ``idf.py efuse_common_table`` or: :: @@ -96,7 +96,7 @@ After generation in the folder `esp32` create: * `esp_efuse_table.c` file. * In `include` folder `esp_efuse_table.c` file. -To generate a `custom` files, use the following command 'make efuse_custom_table' or `idf.py efuse_custom_table` or: +To generate a `custom` files, use the following command ``idf.py efuse_custom_table`` or: :: @@ -170,7 +170,7 @@ For frequently used fields, special functions are made, like this :cpp:func:`esp How add a new field ------------------- -1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``make show_efuse_table`` or ``idf.py show_efuse_table`` or the next command: +1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``idf.py show_efuse_table`` or the next command: :: diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index 337bf3bb26..24c9cb25ea 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -420,7 +420,7 @@ Interrupt respectively. Vanilla FreeRTOS hooks are referred to as **Legacy Hooks** in ESP-IDF FreeRTOS. To enable legacy hooks, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS` should be enabled -in ``make menuconfig``. +in :doc:`project configuration menu `. Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook()`` and ``vApplicationTickHook()`` can only be defined once. However, the ESP32 is dual core diff --git a/docs/en/api-reference/system/heap_debug.rst b/docs/en/api-reference/system/heap_debug.rst index 2f03907060..51caff1ba3 100644 --- a/docs/en/api-reference/system/heap_debug.rst +++ b/docs/en/api-reference/system/heap_debug.rst @@ -38,7 +38,7 @@ Heap corruption detection allows you to detect various types of heap memory erro Assertions ^^^^^^^^^^ -The heap implementation (``multi_heap.c``, etc.) includes a lot of assertions which will fail if the heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in ``make menuconfig`` under ``Compiler options``. +The heap implementation (``multi_heap.c``, etc.) includes a lot of assertions which will fail if the heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in the project configuration menu under ``Compiler options`` -> :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL`. If a heap integrity assertion fails, a line will be printed like ``CORRUPT HEAP: multi_heap.c:225 detected at 0x3ffbb71c``. The memory address which is printed is the address of the heap structure which has corrupt content. @@ -62,7 +62,7 @@ Configuration Temporarily increasing the heap corruption detection level can give more detailed information about heap corruption errors. -In ``make menuconfig``, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :ref:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels: +In the project configuration menu, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :ref:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels: Basic (no poisoning) ++++++++++++++++++++ @@ -143,7 +143,7 @@ Standalone Mode Once you've identified the code which you think is leaking: -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Standalone`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`). +- In the project configuration menu, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Standalone`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`). - Call the function :cpp:func:`heap_trace_init_standalone` early in the program, to register a buffer which can be used to record the memory trace. - Call the function :cpp:func:`heap_trace_start` to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory. - Call the function :cpp:func:`heap_trace_stop` to stop the trace once the suspect piece of code has finished executing. @@ -205,7 +205,7 @@ In ``HEAP_TRACE_LEAKS`` mode, for each traced memory allocation which has not al - ``caller 0x...`` gives the call stack of the call to malloc()/free(), as a list of PC addresses. These can be decoded to source files and line numbers, as shown above. -The depth of the call stack recorded for each trace entry can be configured in ``make menuconfig``, under ``Heap Memory Debugging`` -> ``Enable heap tracing`` -> ``Heap tracing stack depth``. Up to 10 stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory usage of each ``heap_trace_record_t`` record by eight bytes. +The depth of the call stack recorded for each trace entry can be configured in the project configuration menu, under ``Heap Memory Debugging`` -> ``Enable heap tracing`` -> ``Heap tracing stack depth``. Up to 10 stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory usage of each ``heap_trace_record_t`` record by eight bytes. Finally, the total number of 'leaked' bytes (bytes allocated but not freed while trace was running) is printed, and the total number of allocations this represents. @@ -217,9 +217,9 @@ Host-Based Mode Once you've identified the code which you think is leaking: -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Host-Based`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`). -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``Data Destination`` and select ``Trace memory``. -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``FreeRTOS SystemView Tracing`` and check ``SystemView Tracing Enable``. +- In the project configuration menu, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> :ref:`CONFIG_HEAP_TRACING_DEST` and select ``Host-Based``. +- In the project configuration menu, navigate to ``Component settings`` -> ``Application Level Tracing`` -> :ref:`CONFIG_ESP32_APPTRACE_DESTINATION` and select ``Trace memory``. +- In the project configuration menu, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``FreeRTOS SystemView Tracing`` and enable :ref:`CONFIG_SYSVIEW_ENABLE`. - Call the function :cpp:func:`heap_trace_init_tohost` early in the program, to initialize JTAG heap tracing module. - Call the function :cpp:func:`heap_trace_start` to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory. In host-based mode argument to this function is ignored and heap tracing module behaves like ``HEAP_TRACE_ALL`` was passed: all allocations and deallocations are sent to the host. diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 7114225405..cf6eb5020d 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -41,7 +41,7 @@ DRAM At startup, the DRAM heap contains all data memory which is not statically allocated by the app. Reducing statically allocated buffers will increase the amount of available free heap. -To find the amount of statically allocated memory, use the :ref:`make size ` or :ref:`idf.py size ` (for CMake) command. +To find the amount of statically allocated memory, use the :ref:`idf.py size ` command. .. note:: Due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap. @@ -52,7 +52,7 @@ IRAM At startup, the IRAM heap contains all instruction memory which is not used by the app executable code. -The :ref:`make size ` and :ref:`idf.py size ` commands can be used to find the amount of IRAM used by the app. +The :ref:`idf.py size ` command can be used to find the amount of IRAM used by the app. D/IRAM ^^^^^^ diff --git a/docs/en/api-reference/system/system.rst b/docs/en/api-reference/system/system.rst index 184e38c68c..4d72c587fe 100644 --- a/docs/en/api-reference/system/system.rst +++ b/docs/en/api-reference/system/system.rst @@ -129,12 +129,13 @@ App version Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars. -To set version in your project manually you need to set ``PROJECT_VER`` variable in your project Makefile/CMakeLists.txt: +To set version in your project manually you need to set ``PROJECT_VER`` variable in your project CMakeLists.txt/Makefile: -* For Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including project.mk -* For Cmake build system: in application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including project.cmake. +* In application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including ``project.cmake``. -If ``PROJECT_VER`` variable is not set in project Makefile/CMakeLists.txt then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. +(For legacy GNU Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including ``project.mk``.) + +If ``PROJECT_VER`` variable is not set in the project then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. API Reference ------------- diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index 6f2f5cc4ec..5ba5b2fd1a 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -6,7 +6,7 @@ Overview The ESP-IDF has support for two types of watchdogs: The Interrupt Watchdog Timer and the Task Watchdog Timer (TWDT). The Interrupt Watchdog Timer and the TWDT -can both be enabled using ``make menuconfig``, however the TWDT can also be +can both be enabled using :ref:`project-configuration-menu`, however the TWDT can also be enabled during runtime. The Interrupt Watchdog is responsible for detecting instances where FreeRTOS task switching is blocked for a prolonged period of time. The TWDT is responsible for detecting instances of tasks running without @@ -63,7 +63,7 @@ longer call :cpp:func:`esp_task_wdt_reset`. Once all tasks have unsubscribed form the TWDT, the TWDT can be deinitialized by calling :cpp:func:`esp_task_wdt_deinit()`. -By default :ref:`CONFIG_ESP_TASK_WDT` in ``make menuconfig`` will be enabled causing +By default :ref:`CONFIG_ESP_TASK_WDT` in :ref:`project-configuration-menu` be enabled causing the TWDT to be initialized automatically during startup. Likewise :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 17db90e27d..f13a27aa10 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -72,7 +72,7 @@ The flash encryption operation is controlled by various eFuses available on ESP3 encrypt flash at boot time Odd number of bits set (1, 3, 5, 7): do not encrypt flash at boot time - + Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about ESP32 eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`. @@ -116,9 +116,9 @@ As mentioned above :ref:`flash_enc_development_mode` allows user to download as - Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value. -- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”. +- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". -- Select “Enable flash encryption on boot”. +- Select :ref:`Enable flash encryption on boot `. - By default the mode is set for **Development**. @@ -132,7 +132,7 @@ Build and flash the complete image including: bootloader, partition table and ap :: - make -j4 flash monitor + idf.py flash monitor Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when ESP32 boots after flash encryption is enabled for the first time. @@ -281,7 +281,7 @@ At this stage if user wants to update modified plaintext application image to fl :: - make -j4 encrypted-app-flash monitor + idf.py encrypted-app-flash monitor .. _encrypt_partitions: @@ -292,7 +292,7 @@ If all partitions needs to be updated in encrypted format, it can be done as :: - make -j4 encrypted-flash monitor + idf.py encrypted-flash monitor .. _pregenerated-flash-encryption-key: @@ -310,9 +310,9 @@ It is possible to pregenerate the flash encryption key on the host computer and espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin -- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”. +- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". -- Select “Enable flash encryption on boot”. +- Select :ref:`Enable flash encryption on boot `. - By default the mode is set for **Development**. @@ -327,7 +327,7 @@ Build and flash the complete image including: bootloader, partition table and ap :: - make -j4 flash monitor + idf.py flash monitor On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. @@ -335,7 +335,7 @@ At this stage if user wants to update new plaintext application image to flash t :: - make -j4 encrypted-app-flash monitor + idf.py encrypted-app-flash monitor For reprogramming all partitions in encrypted format follow :ref:`encrypt_partitions`. @@ -348,10 +348,10 @@ Release Mode In Release mode UART bootloader can not perform flash encryption operations and new plaintext images can be downloaded ONLY using OTA scheme which will encrypt the plaintext image before writing to flash. - Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. - -- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”. -- Select “Enable flash encryption on boot”. +- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". + +- Select :ref:`Enable flash encryption on boot `. - Select **Release Mode**, by default the mode is set for **Development**. Please note **once the Release mode is selected the ``download_dis_encrypt`` and ``download_dis_decrypt`` eFuse bits will be programmed to disable UART bootloader access to flash contents**. @@ -365,7 +365,7 @@ Build and flash the complete image including: bootloader, partition table and ap :: - make -j4 flash monitor + idf.py flash monitor On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application should execute correctly. @@ -549,12 +549,11 @@ If you've accidentally enabled flash encryption for some reason, the next flash You can disable flash encryption again by writing ``FLASH_CRYPT_CNT`` eFuse (only in Development mode): -- First, run ``make menuconfig`` and uncheck "Enable flash encryption boot" under "Security Features". +- First, open :ref:`project-configuration-menu` and disable :ref:`Enable flash encryption boot ` under "Security Features". - Exit menuconfig and save the new configuration. -- Run ``make menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*. -- Run ``make flash`` to build and flash a new bootloader and app, without flash encryption enabled. +- Run ``idf.py menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*. +- Run ``idf.py flash`` to build and flash a new bootloader and app, without flash encryption enabled. - Run ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the FLASH_CRYPT_CNT:: - espefuse.py burn_efuse FLASH_CRYPT_CNT Reset the ESP32 and flash encryption should be disabled, the bootloader will boot as normal. @@ -584,7 +583,7 @@ Flash Encryption and Secure Boot It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device: - :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key). -- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot ` docs.). In this configuration, ``make bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. +- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot ` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. - :ref:`Reflashing via Pregenerated Flash Encryption Key ` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable ` option to be enabled in the Secure Boot config. .. _flash-encryption-without-secure-boot: diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index 9a6f8a933a..3cd24d8036 100644 --- a/docs/en/security/secure-boot.rst +++ b/docs/en/security/secure-boot.rst @@ -25,7 +25,7 @@ Secure Boot Process Overview This is a high level overview of the secure boot process. Step by step instructions are supplied under :ref:`secure-boot-howto`. Further in-depth details are supplied under :ref:`secure-boot-technical-details`: -1. The options to enable secure boot are provided in the ``make menuconfig`` hierarchy, under "Secure Boot Configuration". +1. The options to enable secure boot are provided in the :ref:`project-configuration-menu`, under "Secure Boot Configuration". 2. Secure Boot defaults to signing images and partition table data during the build process. The "Secure boot private signing key" config item is a file path to a ECDSA public/private key pair in a PEM format file. @@ -76,7 +76,7 @@ Options to work around this are: How To Enable Secure Boot ------------------------- -1. Run ``make menuconfig``, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.) +1. Open the :ref:`project-configuration-menu`, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.) 2. Select a name for the secure boot signing key. This option will appear after secure boot is enabled. The file can be anywhere on your system. A relative path will be evaluated from the project directory. The file does not need to exist yet. @@ -90,15 +90,15 @@ How To Enable Secure Boot .. important:: For production environments, we recommend generating the keypair using openssl or another industry standard encryption program. See :ref:`secure-boot-generate-key` for more details. -5. Run ``make bootloader`` to build a secure boot enabled bootloader. The output of ``make`` will include a prompt for a flashing command, using ``esptool.py write_flash``. +5. Run ``idf.py bootloader`` to build a secure boot enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``. .. _secure-boot-resume-normal-flashing: 6. When you're ready to flash the bootloader, run the specified command (you have to enter it yourself, this step is not performed by make) and then wait for flashing to complete. **Remember this is a one time flash, you can't change the bootloader after this!**. -7. Run ``make flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4. +7. Run ``idf.py flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4. -.. note:: ``make flash`` doesn't flash the bootloader if secure boot is enabled. +.. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled. 8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration. @@ -123,13 +123,13 @@ In the esp-idf build process, this 256-bit key file is derived from the app sign To enable a reflashable bootloader: -1. In the ``make menuconfig`` step, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable. +1. In the :ref:`project-configuration-menu`, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable. 2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool.py`` connects to the chip, or in the ``espefuse.py summary`` output. 2. Follow the steps shown above to choose a signing key file, and generate the key file. -3. Run ``make bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process). +3. Run ``idf.py bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process). 4. Resume from :ref:`Step 6 of the one-time flashing process `, to flash the bootloader and enable secure boot. Watch the console log output closely to ensure there were no errors in the secure boot configuration. @@ -244,7 +244,7 @@ Deterministic ECDSA as specified by `RFC 6979 Security features -> Enable "Require signed app images" +1. Open :ref:`project-configuration-menu` -> Security features -> Enable :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT` 2. "Bootloader verifies app signatures" can be enabled, which verifies app on boot. diff --git a/docs/zh_CN/api-guides/console.rst b/docs/zh_CN/api-guides/console.rst index c7a6408acd..45872445f5 100644 --- a/docs/zh_CN/api-guides/console.rst +++ b/docs/zh_CN/api-guides/console.rst @@ -16,7 +16,7 @@ ESP-IDF 提供了 ``console`` 组件，它包含了开发基于串口的交互 行编辑功能允许用户通过按键输入来编辑命令，使用退格键删除符号，使用左/右键在命令中移动光标，使用上/下键导航到之前输入的命令，使用制表键（“Tab”）来自动补全命令。 -.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[esp32]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``make monitor`` 来调用）。 +.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[esp32]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``idf.py monitor`` 来调用）。 前往这里可以查看 `linenoise `_ 库提供的所有函数的描述。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index fe04714c81..2588c8aa16 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -57,7 +57,7 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设 * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 默认没有使能。在所有任务堆栈的末尾设置观察点，从 1 号开始索引。这是调试任务堆栈溢出的最准确的方式。 -更多有关设置编译时的选项的信息，请参阅 :ref:`make menuconfig `。 +更多有关设置编译时的选项的信息，请参阅 :ref:`idf.py menuconfig `。 .. _jtag-debugging-tip-freertos-support: diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index deff7c14c8..c4b84a6185 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -11,12 +11,12 @@ 分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。 -在使用分区表时，最简单的方法就是用 `make menuconfig` 选择一张预定义的分区表： +在使用分区表时，最简单的方法就是用 `idf.py menuconfig` 选择一张预定义的分区表： - "Single factory app, no OTA" - "Factory app, two OTA definitions" -在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `make partition_table` ，即可以打印当前使用分区表的信息摘要。 +在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `idf.py partition_table` ，即可以打印当前使用分区表的信息摘要。 内置分区表 ------------ @@ -102,7 +102,7 @@ SubType 字段长度为 8 bit，内容与具体 Type 有关。目前，esp-idf - phy (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。 - 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。 - - 如果需要从此分区加载 phy 初始化数据，请运行 ``make menuconfig``，并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。 + - 如果需要从此分区加载 phy 初始化数据，请运行 ``idf.py menuconfig``，并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。 - nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。 - 用于存储每台设备的 PHY 校准数据（注意，并不是 PHY 初始化数据）。 @@ -142,7 +142,7 @@ Flags 字段 烧写到 ESP32 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。 -如果您在 ``make menuconfig`` 指定了分区表 CSV 文件的名称，然后执行 ``make partition_table``。这时，转换将在编译过程中自动完成。 +如果您在 ``idf.py menuconfig`` 指定了分区表 CSV 文件的名称，然后执行 ``idf.py partition_table``。这时，转换将在编译过程中自动完成。 手动将 CSV 文件转换为二进制文件: @@ -152,7 +152,7 @@ Flags 字段 python gen_esp32part.py binary_partitions.bin input_partitions.csv -在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``make partition_table`` 时，我们正是这样打印上文展示的信息摘要的）: +在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``idf.py partition_table`` 时，我们正是这样打印上文展示的信息摘要的）: python gen_esp32part.py binary_partitions.bin @@ -166,13 +166,13 @@ MD5 校验和 烧写分区表 ---------- -- ``make partition_table-flash`` ：使用 esptool.py 工具烧写分区表。 -- ``make flash`` ：会烧写所有内容，包括分区表。 +- ``idf.py partition_table-flash`` ：使用 esptool.py 工具烧写分区表。 +- ``idf.py flash`` ：会烧写所有内容，包括分区表。 -在执行 ``make partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。 +在执行 ``idf.py partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。 .. note:: - 分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``make erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 + 分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 .. _secure boot: security/secure-boot.rst diff --git a/docs/zh_CN/api-guides/tools/idf-monitor.rst b/docs/zh_CN/api-guides/tools/idf-monitor.rst index d756422da4..72651108f2 100644 --- a/docs/zh_CN/api-guides/tools/idf-monitor.rst +++ b/docs/zh_CN/api-guides/tools/idf-monitor.rst @@ -8,8 +8,9 @@ IDF 监视器是一个串行终端程序，用于收发目标设备串口的串 在 IDF 中调用以下目标函数可以启用此监视器： -- **若使用 Make 编译系统，请调用**：``make monitor`` - **若使用 CMake 编译系统，则请调用**：``idf.py monitor`` +- **若使用传统 GNU Make 编译系统，请调用**：``make monitor`` + 操作快捷键 @@ -26,7 +27,7 @@ Ctrl+T 菜单退出键 - Ctrl+] 将 exit 字符发送至远程 - Ctrl+P 重置目标设备，进入 Bootloader，通过 RTS 线暂停应用程序 重置目标设备，通过 RTS 线（如已连接）进入 Bootloader，此时开发板不运行任何程序。等待其他设备启动时可以使用此操作。 - Ctrl+R 通过 RTS 线重置目标设备 重置设备，并通过 RTS 线（如已连接）重新启动应用程序。 -- Ctrl+F 编译并烧录此项目 暂停 idf_monitor，运行 ``make flash`` (``idf.py flash``) 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。 +- Ctrl+F 编译并烧录此项目 暂停 idf_monitor，运行 ``idf.py flash`` 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。 - Ctrl+A (A) 仅编译及烧录应用程序 暂停 idf_monitor，运行 ``app-flash`` 目标，然后恢复 idf_monitor。 这与 ``flash`` 类似，但只有主应用程序被编译并被重新烧录。 - Ctrl+Y 停止/恢复日志输出在屏幕上打印 激活时，会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。 - Ctrl+L 停止/恢复向文件写入日志输出 在工程目录下创建一个文件，用于写入日志输出。可使用快捷键停止/恢复该功能（退出 IDF 监视器也会终止该功能） @@ -91,7 +92,7 @@ IDF 监视器在后台运行以下命令，解码各地址:: 或者选择配置 panic 处理器以运行 GDBStub，GDBStub 工具可以与 GDB_ 项目调试器进行通信，允许读取内存、检查调用堆栈帧和变量等。GDBStub 虽然没有 JTAG 通用，但不需要使用特殊硬件。 -如需启用 GDBStub，请运行 ``make menuconfig`` （适用于 Make 编译系统）或 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 +如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 在这种情况下，如果 panic 处理器被触发，只要 IDF 监视器监控到 GDBStub 已经加载，panic 处理器就会自动暂停串行监控并使用必要的参数运行 GDB。GDB 退出后，通过 RTS 串口线复位开发板。如果未连接 RTS 串口线，请按复位键，手动复位开发板。 @@ -103,7 +104,7 @@ IDF 监控器在后台运行如下命令:: 输出筛选 ~~~~~~~~~~~~~~~~ -IDF 监视器有两种启用方式：运行 ``make monitor PRINT_FILTER=""`` （适用于 Make）或者 ``idf.py monitor --print-filter=""`` （适用于 CMake），其中，``PRINT_FILTER`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。 +IDF 监视器有两种启用方式：运行 ``idf.py monitor PRINT_FILTER=""`` （适用于 CMake） 或者 ``make monitor PRINT_FILTER=""`` （适用于传统 GNU Make），其中，``--print-filter`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。 若需对打印内容设置限制，可指定 ``:`` 等选项，其中 ```` 是标签字符串，```` 是 ``{N, E, W, I, D, V, *}`` 集合中的一个字母，指的是 :doc:`日志 <../../api-reference/system/log>` 级别。 @@ -159,18 +160,6 @@ IDF 监视器有两种启用方式：运行 ``make monitor PRINT_FILTER=""`` （ D (309) light_driver: [light_init, 74]:status: 1, mode: 2 -简单监视器 -============== - -较早版本的 ESP-IDF 使用 pySerial_ 命令行工具 miniterm_ 作为串行控制台程序。 - -.. note:: 仅适用于 Make 编译系统，不适用于 CMake 编译系统。 - -此程序仍然可以通过 ``make simple_monitor`` 运行。 - -IDF 监视器基于 miniterm，可使用相同的快捷键。 - - IDF 监视器已知问题 ============================= diff --git a/examples/README.md b/examples/README.md index af04945bfd..e5b4a0c4fc 100644 --- a/examples/README.md +++ b/examples/README.md @@ -25,9 +25,9 @@ Building an example is the same as building any other project: * Follow the Getting Started instructions which include building the "Hello World" example. * Change into the directory of the new example you'd like to build. -* `make menuconfig` to configure the example. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use). +* Run `idf.py menuconfig` to open the project configuration menu. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use). * `make` to build the example. -* Follow the printed instructions to flash, or run `make flash`. +* Follow the printed instructions to flash, or run `idf.py flash`. # Copying Examples diff --git a/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md b/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md index df698cf904..04b09711b1 100644 --- a/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md +++ b/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md @@ -21,10 +21,10 @@ Which demo will be run depends on the menuconfig, developers can set it in `iBea The default mode is iBeacon Sender. ### Menuconfig -Before compiling the demo，developers also need to configure the menuconfig: +Before compiling the demo，developers also need to configure the project: ```c -make menuconfig +idf.py menuconfig ``` And then enter `Component config->Bluetooth->Bluedroid Enable` @@ -49,7 +49,7 @@ switch (scan_result->scan_rst.search_evt) { Build each project and flash it to the board, then run monitor tool to view serial output: ``` -make -j4 flash monitor +idp.py -p PORT flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) @@ -110,4 +110,4 @@ I (329203) IBEACON_DEMO: ----------iBeacon Found---------- I (329203) IBEACON_DEMO: Device address:: 30 ae a4 00 42 82 I (329203) IBEACON_DEMO: Proximity UUID:: fd a5 06 93 a4 e2 4f b1 af cf c6 eb 07 64 78 25 ``` - \ No newline at end of file + diff --git a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md index 48b6b475ba..d38c4ca5ed 100644 --- a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md +++ b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md @@ -4,10 +4,10 @@ ESP-IDF BLE throughput GATT CLIENT demo This is the demo used to test the BLE throughput, this demo should used with throughput server demo together. The throughput of BLE can up to 720-767 Kbps between to ESP32 board. Note: -1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (make menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log. +1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (idf.py menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log. 2. We can only test notify or write throughput at the same time, this demo default to test the notify throughput, if want to test the write throughput, -please set: make menuconfig --> Component config --> Example 'GATT CLIENT THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option +please set: idf.py menuconfig --> Component config --> Example 'GATT CLIENT THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option 3. This demo only test unidirectional throughput, if you want to test the bidirectional throughput please change the demo by yourself. -4. Should change the CPU frequency to 160MHZ or 240MHz in the make menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (240 MHz or 160 MHz). -5. Should change the bluetooth controller and Bluedroid run in different Core in the make menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)). +4. Should change the CPU frequency to 160MHZ or 240MHz in the idf.py menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (240 MHz or 160 MHz). +5. Should change the bluetooth controller and Bluedroid run in different Core in the idf.py menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)). 6. In order to maximize throughput, please test in a clean environment without many BLE devices working and both test devices are ESP32. diff --git a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md index 47c86410d9..1dc21211c8 100644 --- a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md +++ b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md @@ -4,11 +4,11 @@ ESP-IDF BLE throughput GATT SERVER demo This is the demo used to test the BLE throughput, this demo should used with throughput client demo together. The throughput of BLE can up to 720-767 Kbps between to ESP32 board. Note: -1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (make menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log; +1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (idf.py menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log; 2. We can only test notify or write throughput at the same time, this demo default to test the notify throughput, if want to test the write throughput, -please set: make menuconfig --> Component config --> Example 'GATT SERVER THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option +please set: idf.py menuconfig --> Component config --> Example 'GATT SERVER THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option 3. This demo only test unidirectional throughput, if you want to test the bidirectional throughput please change the demo by yourself. -4. Should change the CPU frequency to 160MHz or 240MHz in the make menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (160MHz or 240 MHz) -5. Should change the bluetooth controller and Bluedroid run in different Core in the make menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)) +4. Should change the CPU frequency to 160MHz or 240MHz in the idf.py menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (160MHz or 240 MHz) +5. Should change the bluetooth controller and Bluedroid run in different Core in the idf.py menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)) 6. In order to maximize throughput, please test in a clean environment without many BLE devices working and both test devices are ESP32. diff --git a/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md b/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md index 9a3c5d611b..7d0889eccc 100644 --- a/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md +++ b/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md @@ -28,11 +28,9 @@ If the internal DAC is selected, analog audio will be available on GPIO25 and GP ### Configure the project ``` -make menuconfig +idf.py menuconfig ``` -* Set serial port under Serial Flasher Options. - * Set the use of external I2S codec or internal DAC for audio output, and configure the output PINs under A2DP Example Configuration * Enable Classic Bluetooth and A2DP under Component config --> Bluetooth --> Bluedroid Enable @@ -42,7 +40,7 @@ make menuconfig Build the project and flash it to the board, then run monitor tool to view serial output. ``` -make -j4 flash monitor +idf.py flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) @@ -72,4 +70,4 @@ Also, the sound will be heard if a loudspeaker is connected and possible externa ## Troubleshooting * For current stage, the supported audio codec in ESP32 A2DP is SBC. SBC data stream is transmitted to A2DP sink and then decoded into PCM samples as output. The PCM data format is normally of 44.1kHz sampling rate, two-channel 16-bit sample stream. Other decoder configurations in ESP32 A2DP sink is supported but need additional modifications of protocol stack settings. -* As a usage limitation, ESP32 A2DP sink can support at most one connection with remote A2DP source devices. Also, A2DP sink cannot be used together with A2DP source at the same time, but can be used with other profiles such as SPP and HFP. \ No newline at end of file +* As a usage limitation, ESP32 A2DP sink can support at most one connection with remote A2DP source devices. Also, A2DP sink cannot be used together with A2DP source at the same time, but can be used with other profiles such as SPP and HFP. diff --git a/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md b/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md index 4e9586ce98..05e0594dbc 100644 --- a/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md +++ b/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md @@ -14,11 +14,9 @@ This example is able to run on any commonly available ESP32 development board. A ### Configure the project ``` -make menuconfig +idf.py menuconfig ``` -* Set serial port under Serial Flasher Options. - * Enable Classic Bluetooth and A2DP under Component config --> Bluetooth --> Bluedroid Enable ### Build and Flash @@ -26,7 +24,7 @@ make menuconfig Build the project and flash it to the board, then run monitor tool to view serial output. ``` -make -j4 flash monitor +idf.py -p PORT flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst index 29db5e73c1..d5c857344c 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst @@ -6,7 +6,7 @@ Demo of Classic Bluetooth Device and Service Discovery This is the demo for user to use ESP_APIs to perform inquiry to search for a target device and then performs service search via SDP. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and do not choose "Release DRAM from Classic BT controller" 4. choose your options. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst index b0a865e41d..d33e353672 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst @@ -6,11 +6,11 @@ Demo of SPP acceptor role This is the demo for user to use ESP_APIs to create a SPP acceptor. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. Then set SPP_SHOW_MODE as SPP_SHOW_DATA or SPP_SHOW_SPEED in code(should be same with bt_spp_initator). -After the program started, bt_spp_initator will connect it and send data. \ No newline at end of file +After the program started, bt_spp_initator will connect it and send data. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst index 4d298e18f8..07bf513a1c 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst @@ -6,11 +6,11 @@ Demo of SPP initator role This is the demo for user to use ESP_APIs to create a SPP initator. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. Then set SPP_SHOW_MODE as SPP_SHOW_DATA or SPP_SHOW_SPEED in code(should be same with bt_spp_acceptor). -After the program started, It will connect to bt_spp_acceptor and send data. \ No newline at end of file +After the program started, It will connect to bt_spp_acceptor and send data. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst index 76571c45e3..b45593eb62 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst @@ -6,9 +6,9 @@ Demo of SPP acceptor role This is the demo for user to use ESP_APIs to create a SPP acceptor. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. -After the program started, bt_spp_vfs_initator will connect it and send data. \ No newline at end of file +After the program started, bt_spp_vfs_initator will connect it and send data. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst index efb2513d91..38d9804b9c 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst @@ -6,9 +6,9 @@ Demo of SPP initator role This is the demo for user to use ESP_APIs to create a SPP initator. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. -After the program started, It will connect to bt_spp_vfs_acceptor and send data. \ No newline at end of file +After the program started, It will connect to bt_spp_vfs_acceptor and send data. diff --git a/examples/ethernet/eth2ap/README.md b/examples/ethernet/eth2ap/README.md index 26d81db121..8e0f425a62 100644 --- a/examples/ethernet/eth2ap/README.md +++ b/examples/ethernet/eth2ap/README.md @@ -18,7 +18,7 @@ To run this example, it's recommended that you have an official ESP32 Ethernet d ### Project configuration in menuconfig -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you' are using CMake based build system. +Open the project configuration menu (`idf.py menuconfig`). 1. In the `Example Configuration` menu: * Set the SSID and password for Wi-Fi ap interface under `Wi-Fi SSID` and `Wi-Fi Password`. @@ -57,7 +57,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -To build and flash the example, enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +To build and flash the example, enter `idf.py -p PORT flash monitor`. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/get-started/blink/main/blink.c b/examples/get-started/blink/main/blink.c index 20a0b94ebf..9c58645f9d 100644 --- a/examples/get-started/blink/main/blink.c +++ b/examples/get-started/blink/main/blink.c @@ -12,7 +12,7 @@ #include "driver/gpio.h" #include "sdkconfig.h" -/* Can run 'make menuconfig' to choose the GPIO to blink, +/* Can use project configuration menu (idf.py menuconfig) to choose the GPIO to blink, or you can edit the following line and set a number here. */ #define BLINK_GPIO CONFIG_BLINK_GPIO diff --git a/examples/mesh/internal_communication/README.md b/examples/mesh/internal_communication/README.md index 4131bef5aa..3c97dc427c 100644 --- a/examples/mesh/internal_communication/README.md +++ b/examples/mesh/internal_communication/README.md @@ -16,7 +16,7 @@ Features Demonstrated - other nodes receive -Run `make menuconfig` to configure the mesh network channel, router SSID, router password and mesh softAP settings. +Open project configuration menu (`idf.py menuconfig`) to configure the mesh network channel, router SSID, router password and mesh softAP settings. When the mesh network is established and if you happen to run this example on ESP-WROVER-KIT boards, the RGB light indicator will show you on which layer devices are. The pink reprents root; the yellow reprents layer 2; the red reprents layer 3; the blue reprents layer 4; the green reprents layer 5; the white reprents layer greater than 5. diff --git a/examples/mesh/manual_networking/README.md b/examples/mesh/manual_networking/README.md index 8615dbd6de..9b3ecd58cd 100644 --- a/examples/mesh/manual_networking/README.md +++ b/examples/mesh/manual_networking/README.md @@ -7,7 +7,7 @@ This example demonstrates how to scan a list of parent candidates, choose an app If no parent is found through this scan, enable the self-organized function to let the ESP-MESH handle it by itself. -Run `make menuconfig` to configure the mesh network channel, router SSID, router password and mesh softAP settings. +Open project configuration menu (`idf.py menuconfig`) to configure the mesh network channel, router SSID, router password and mesh softAP settings. When the mesh network is established and if you happen to run this example on ESP-WROVER-KIT boards, the RGB light indicator will show you on which layer devices are. The pink reprents root; the yellow reprents layer 2; the red reprents layer 3; the blue reprents layer 4; the green reprents layer 5; the white reprents layer greater than 5. diff --git a/examples/peripherals/adc/README.md b/examples/peripherals/adc/README.md index 657f01a1b9..47f58c94b9 100644 --- a/examples/peripherals/adc/README.md +++ b/examples/peripherals/adc/README.md @@ -48,7 +48,7 @@ Raw: 18 Voltage: 79mV * program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/adc2/README.md b/examples/peripherals/adc2/README.md index 1d7ba206a6..32b94f68ed 100644 --- a/examples/peripherals/adc2/README.md +++ b/examples/peripherals/adc2/README.md @@ -59,7 +59,7 @@ start conversion. * program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/i2c/i2c_self_test/README.md b/examples/peripherals/i2c/i2c_self_test/README.md index 499b35e3c0..66f64c2ffc 100644 --- a/examples/peripherals/i2c/i2c_self_test/README.md +++ b/examples/peripherals/i2c/i2c_self_test/README.md @@ -43,7 +43,7 @@ To run this example, you should have one ESP32 dev board (e.g. ESP32-WROVER Kit) ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - In the `I2C Master` submenu, you can set the pin number of SDA/SCL according to your board. Also you can modify the I2C port number and freauency of the master. - In the `I2C Slave` submenu, you can set the pin number of SDA/SCL according to your board. Also you can modify the I2C port number and address of the slave. @@ -52,7 +52,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you' are using CMake based build system. +Enter `idf.py -p PORT flash monitor` to build, flash and monitor the project. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/peripherals/i2c/i2c_tools/README.md b/examples/peripherals/i2c/i2c_tools/README.md index ca150d838b..40d6a2b69b 100644 --- a/examples/peripherals/i2c/i2c_tools/README.md +++ b/examples/peripherals/i2c/i2c_tools/README.md @@ -33,7 +33,7 @@ To run this example, you should have one ESP32 dev board (e.g. ESP32-WROVER Kit) ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - You can choose whether or not to save command history into flash in `Store command history in flash` option. - You can set the maximum number of command line arguments under `Maximum number of command line arguments` option. @@ -41,7 +41,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/peripherals/i2s/README.md b/examples/peripherals/i2s/README.md index 8f16374f10..a02f3e5e60 100644 --- a/examples/peripherals/i2s/README.md +++ b/examples/peripherals/i2s/README.md @@ -61,7 +61,7 @@ If you have a logic analyzer, you can use a logic analyzer to grab online data. * Program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/i2s_adc_dac/README.md b/examples/peripherals/i2s_adc_dac/README.md index 2d3b05bd94..7d43ef845a 100644 --- a/examples/peripherals/i2s_adc_dac/README.md +++ b/examples/peripherals/i2s_adc_dac/README.md @@ -85,7 +85,7 @@ I2S: PLL_D2: Req RATE: 16000, real rate: 1004.000, BITS: 16, CLKM: 83, BCK: 60, * Program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/ledc/README.md b/examples/peripherals/ledc/README.md index dc8a25c2a3..c66fa19ddc 100644 --- a/examples/peripherals/ledc/README.md +++ b/examples/peripherals/ledc/README.md @@ -63,7 +63,7 @@ you can also see the following output log on the serial monitor: * Programming fail - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/pcnt/README.md b/examples/peripherals/pcnt/README.md index 4ab5395eba..6e0beb6c07 100644 --- a/examples/peripherals/pcnt/README.md +++ b/examples/peripherals/pcnt/README.md @@ -68,7 +68,7 @@ Current counter value :-1 * program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/rmt_nec_tx_rx/README.md b/examples/peripherals/rmt_nec_tx_rx/README.md index 85f861fdbe..073859111d 100644 --- a/examples/peripherals/rmt_nec_tx_rx/README.md +++ b/examples/peripherals/rmt_nec_tx_rx/README.md @@ -74,7 +74,7 @@ NEC: RMT RCV --- addr: 0xda25 cmd: 0xeb14 * Programming fail - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there is any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there is any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/rmt_tx/README.md b/examples/peripherals/rmt_tx/README.md index 3b1cf4a43e..6b7f1ff171 100644 --- a/examples/peripherals/rmt_tx/README.md +++ b/examples/peripherals/rmt_tx/README.md @@ -61,7 +61,7 @@ RMT Tx: Sample transmission complete * Programming fail - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there is any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there is any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/uart/nmea0183_parser/README.md b/examples/peripherals/uart/nmea0183_parser/README.md index 6a9ce7859f..105c6a626b 100644 --- a/examples/peripherals/uart/nmea0183_parser/README.md +++ b/examples/peripherals/uart/nmea0183_parser/README.md @@ -39,7 +39,7 @@ To run this example, you need an ESP32 dev board (e.g. ESP32-WROVER Kit) or ESP3 ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - Set the size of ring buffer used by uart driver in `NMEA Parser Ring Buffer Size` option. - Set the stack size of the NMEA Parser task in `NMEA Parser Task Stack Size` option. @@ -48,7 +48,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/protocols/README.md b/examples/protocols/README.md index 0ab0a7628f..3e8570622b 100644 --- a/examples/protocols/README.md +++ b/examples/protocols/README.md @@ -14,7 +14,7 @@ The simple `example_connect()` function does not handle timeouts, does not grace ### Configuring the Example -To configure the example to use Wi-Fi or Ethernet connection, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) and navigate to "Example Connection Configuration" menu. Select either "Wi-Fi" or "Ethernet" in the "Connect using" choice. +To configure the example to use Wi-Fi or Ethernet connection, open the project configuration menu (`idf.py menuconfig`) and navigate to "Example Connection Configuration" menu. Select either "Wi-Fi" or "Ethernet" in the "Connect using" choice. When connecting using Wi-Fi, enter SSID and password of your Wi-Fi access point into the corresponding fields. If connecting to an open Wi-Fi network, keep the password field empty. diff --git a/examples/protocols/asio/chat_client/README.md b/examples/protocols/asio/chat_client/README.md index 951afad53b..edc4c71897 100644 --- a/examples/protocols/asio/chat_client/README.md +++ b/examples/protocols/asio/chat_client/README.md @@ -5,15 +5,15 @@ Simple Asio chat client using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio chat client connects to the corresponding server whose port number and IP are defined through `make menuconfig`. -- Chat client receives all messages from other chat clients, also it sends message received from stdin using `make monitor`. +- Asio chat client connects to the corresponding server whose port number and IP are defined through the project configuration menu. +- Chat client receives all messages from other chat clients, also it sends message received from stdin using `idf.py monitor`. ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server IP address and port number in menuconfig, "Example configuration". - Start chat server either on host machine or as another ESP device running chat_server example. -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet. - Receive and send messages to/from other clients on stdin/stdout via serial terminal. diff --git a/examples/protocols/asio/chat_server/README.md b/examples/protocols/asio/chat_server/README.md index e043cba32c..ec8b3e76e3 100644 --- a/examples/protocols/asio/chat_server/README.md +++ b/examples/protocols/asio/chat_server/README.md @@ -5,14 +5,14 @@ Simple Asio chat server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio chat server is started on port number defined through `make menuconfig`. +- Asio chat server is started on port number defined through the project configuration. - Chat server echoes a message (received from any client) to all connected clients. ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - Connect to the server using multiple clients, for example using any option below. - build and run asi chat client on your host machine diff --git a/examples/protocols/asio/tcp_echo_server/README.md b/examples/protocols/asio/tcp_echo_server/README.md index f672027ef4..b2443a245e 100644 --- a/examples/protocols/asio/tcp_echo_server/README.md +++ b/examples/protocols/asio/tcp_echo_server/README.md @@ -5,14 +5,14 @@ Simple Asio TCP echo server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio TCP server is started on port number defined through `make menuconfig`. +- Asio TCP server is started on port number defined through the project configuration. - Server receives and echoes back messages transmitted from client. ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - You can now send a TCP message and check it is repeated, for example using netcat `nc IP PORT`. diff --git a/examples/protocols/asio/udp_echo_server/README.md b/examples/protocols/asio/udp_echo_server/README.md index cc69fee08d..cc8a67e66c 100644 --- a/examples/protocols/asio/udp_echo_server/README.md +++ b/examples/protocols/asio/udp_echo_server/README.md @@ -5,14 +5,14 @@ Simple Asio UDP echo server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio UDP server is started on port number defined through `make menuconfig` +- Asio UDP server is started on port number defined through the project configuration - Server receives and echoes back messages transmitted from client ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - You can now send a UDP message and check it is repeated, for example using netcat `nc -u IP PORT`. diff --git a/examples/protocols/coap_client/main/coap_client_example_main.c b/examples/protocols/coap_client/main/coap_client_example_main.c index 38761267f6..921541aef2 100644 --- a/examples/protocols/coap_client/main/coap_client_example_main.c +++ b/examples/protocols/coap_client/main/coap_client_example_main.c @@ -31,7 +31,7 @@ #define COAP_LOGGING_LEVEL 0 /* The examples use uri "coap://californium.eclipse.org" that - you can set via 'make menuconfig'. + you can set via the project configuration (idf.py menuconfig) If you'd rather not, just change the below entries to strings with the config you want - ie #define COAP_DEFAULT_DEMO_URI "coap://californium.eclipse.org" diff --git a/examples/protocols/http_server/file_serving/README.md b/examples/protocols/http_server/file_serving/README.md index 241e0808c5..475cd7b0c7 100644 --- a/examples/protocols/http_server/file_serving/README.md +++ b/examples/protocols/http_server/file_serving/README.md @@ -21,13 +21,13 @@ File server implementation can be found under `main/file_server.c` which uses SP ## Usage -* Configure the project using `make menuconfig` and goto `Example Configuration` -> +* Open the project configuration menu (`idf.py menuconfig`) go to `Example Configuration` -> 1. WIFI SSID: WIFI network to which your PC is also connected to. 2. WIFI Password: WIFI password * In order to test the file server demo : - 1. compile and burn the firmware `make flash` - 2. run `make monitor` and note down the IP assigned to your ESP module. The default port is 80 + 1. compile and burn the firmware `idf.py -p PORT flash` + 2. run `idf.py monitor` and note down the IP assigned to your ESP module. The default port is 80 3. test the example interactively on a web browser (assuming IP is 192.168.43.130): 1. open path `http://192.168.43.130/` or `http://192.168.43.130/index.html` to see an HTML web page with list of files on the server (initially empty) 2. use the file upload form on the webpage to select and upload a file to the server diff --git a/examples/protocols/http_server/persistent_sockets/README.md b/examples/protocols/http_server/persistent_sockets/README.md index ded2cfd6cf..24c82a18a8 100644 --- a/examples/protocols/http_server/persistent_sockets/README.md +++ b/examples/protocols/http_server/persistent_sockets/README.md @@ -3,11 +3,11 @@ The Example consists of HTTPD server persistent sockets demo. This sort of persistency enables the server to have independent sessions/contexts per client. -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +* Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * In order to test the HTTPD server persistent sockets demo : - 1. compile and burn the firmware "make flash" - 2. run "make monitor" and note down the IP assigned to your ESP module. The default port is 80 + 1. compile and burn the firmware `idf.py -p PORT flash` + 2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80 3. run the test script "python2 scripts/adder.py \ \ \" * the provided test script sends (POST) numbers from 1 to N to the server which has a URI POST handler for adding these numbers into an accumulator that is valid throughout the lifetime of the connection socket, hence persistent * the script does a GET before closing and displays the final value of the accumulator diff --git a/examples/protocols/http_server/restful_server/README.md b/examples/protocols/http_server/restful_server/README.md index 0a2ad7d871..9923d4232c 100644 --- a/examples/protocols/http_server/restful_server/README.md +++ b/examples/protocols/http_server/restful_server/README.md @@ -57,7 +57,7 @@ Only if you deploy the website to SD card, then the following pin connection is ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. +Open the project configuration menu (`idf.py menuconfig`). In the `Example Connection Configuration` menu: @@ -88,7 +88,7 @@ npm run build After a while, you will see a `dist` directory which contains all the website files (e.g. html, js, css, images). -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/protocols/http_server/simple/README.md b/examples/protocols/http_server/simple/README.md index 969c038363..d9e9207fb4 100644 --- a/examples/protocols/http_server/simple/README.md +++ b/examples/protocols/http_server/simple/README.md @@ -4,11 +4,11 @@ The Example consists of HTTPD server demo with demostration of URI handling : 1. URI \hello for GET command returns "Hello World!" message 2. URI \echo for POST command echoes back the POSTed message -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +* Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * In order to test the HTTPD server persistent sockets demo : - 1. compile and burn the firmware "make flash" - 2. run "make monitor" and note down the IP assigned to your ESP module. The default port is 80 + 1. compile and burn the firmware `idf.py -p PORT flash` + 2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80 3. test the example : * run the test script : "python2 scripts/client.py \ \ \" * the provided test script first does a GET \hello and displays the response diff --git a/examples/protocols/https_server/README.md b/examples/protocols/https_server/README.md index be0ed0d587..088819d2c6 100644 --- a/examples/protocols/https_server/README.md +++ b/examples/protocols/https_server/README.md @@ -4,7 +4,7 @@ This example creates a SSL server that returns a simple HTML page when you visit See the `esp_https_server` component documentation for details. -Before using the example, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. +Before using the example, open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. ## Certificates diff --git a/examples/protocols/mdns/README.md b/examples/protocols/mdns/README.md index 2c35167647..2392699b60 100644 --- a/examples/protocols/mdns/README.md +++ b/examples/protocols/mdns/README.md @@ -4,15 +4,15 @@ Shows how to use mDNS to advertise lookup services and hosts ## Example workflow -- mDNS is initialized with host name and instance name defined through `make menuconfig` and `_http._tcp` service is added to be advertised -- WiFi STA is started and trying to connect to the access point defined through `make menuconfig` +- mDNS is initialized with host name and instance name defined through the project configuration and `_http._tcp` service is added to be advertised +- WiFi STA is started and trying to connect to the access point defined through the project configuration - The system event handler is used to pass the network events to mDNS so the service is aware when the interface comes up or down - GPIO0 (BOOT Button) is initialized as pulled-up input that can be monitored for button press - Example task is started to check if the button is pressed so it can execute the mDNS queries defined ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/publish_test/README.md b/examples/protocols/mqtt/publish_test/README.md index bdc2bc879d..d3db836410 100644 --- a/examples/protocols/mqtt/publish_test/README.md +++ b/examples/protocols/mqtt/publish_test/README.md @@ -22,7 +22,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. * Set brokers for all 4 transports (TCP, SSL, WS, WSS), also set certificate if needed diff --git a/examples/protocols/mqtt/ssl/README.md b/examples/protocols/mqtt/ssl/README.md index 929257d404..5925c4001e 100644 --- a/examples/protocols/mqtt/ssl/README.md +++ b/examples/protocols/mqtt/ssl/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/ssl_mutual_auth/README.md b/examples/protocols/mqtt/ssl_mutual_auth/README.md index 763e2671ac..9b20b37cad 100644 --- a/examples/protocols/mqtt/ssl_mutual_auth/README.md +++ b/examples/protocols/mqtt/ssl_mutual_auth/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/tcp/README.md b/examples/protocols/mqtt/tcp/README.md index aea6630944..7247a7a228 100644 --- a/examples/protocols/mqtt/tcp/README.md +++ b/examples/protocols/mqtt/tcp/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/ws/README.md b/examples/protocols/mqtt/ws/README.md index efe2efcb39..236521f90e 100644 --- a/examples/protocols/mqtt/ws/README.md +++ b/examples/protocols/mqtt/ws/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/wss/README.md b/examples/protocols/mqtt/wss/README.md index 9433986a51..453d52f70f 100644 --- a/examples/protocols/mqtt/wss/README.md +++ b/examples/protocols/mqtt/wss/README.md @@ -13,7 +13,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/openssl_client/README.md b/examples/protocols/openssl_client/README.md index 07be757195..272060a60c 100644 --- a/examples/protocols/openssl_client/README.md +++ b/examples/protocols/openssl_client/README.md @@ -2,7 +2,7 @@ The Example contains of OpenSSL client demo. -To configure the project, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`): * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. diff --git a/examples/protocols/openssl_client/main/openssl_client_example.h b/examples/protocols/openssl_client/main/openssl_client_example.h index 8d1645164a..206d9a91b0 100644 --- a/examples/protocols/openssl_client/main/openssl_client_example.h +++ b/examples/protocols/openssl_client/main/openssl_client_example.h @@ -11,7 +11,7 @@ #define _OPENSSL_EXAMPLE_H_ /* The examples use domain of "www.baidu.com" and port number of 433 that - you can set via 'make menuconfig'. + you can set via the project configuration menu. If you'd rather not, just change the below entries to strings with the config you want - ie #define OPENSSL_EXAMPLE_TARGET_NAME "www.baidu.com" diff --git a/examples/protocols/openssl_server/README.md b/examples/protocols/openssl_server/README.md index 6d4506e933..d304397039 100644 --- a/examples/protocols/openssl_server/README.md +++ b/examples/protocols/openssl_server/README.md @@ -2,7 +2,7 @@ The Example contains of OpenSSL server demo. -To configure the project, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`): * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. diff --git a/examples/protocols/pppos_client/README.md b/examples/protocols/pppos_client/README.md index bcfb8e5034..a449a261c7 100644 --- a/examples/protocols/pppos_client/README.md +++ b/examples/protocols/pppos_client/README.md @@ -32,7 +32,7 @@ You can also try other modules as long as they embedded PPP protocol. ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - Choose the modem module in `Choose supported modem device(DCE)` option, currently we only support BG96 and SIM800L. - Set the access point name in `Set Access Point Name(APN)` option, which should depend on the operator of your SIM card. @@ -44,7 +44,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/protocols/sntp/README.md b/examples/protocols/sntp/README.md index 1c3671f3f8..9a7078c47c 100644 --- a/examples/protocols/sntp/README.md +++ b/examples/protocols/sntp/README.md @@ -4,7 +4,7 @@ This example demonstrates the use of LwIP SNTP module to obtain time from Intern ## Configuring the Example -To configure the project, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`): * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. diff --git a/examples/protocols/sockets/udp_multicast/README.md b/examples/protocols/sockets/udp_multicast/README.md index 7bc066db07..649bd61195 100644 --- a/examples/protocols/sockets/udp_multicast/README.md +++ b/examples/protocols/sockets/udp_multicast/README.md @@ -12,7 +12,7 @@ The behaviour of the example is: ## Configuration -Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`). Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. diff --git a/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c b/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c index ee68788978..ea438991aa 100644 --- a/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c +++ b/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c @@ -25,7 +25,7 @@ #include /* The examples use simple configuration that you can set via - 'make menuconfig'. + project configuration. If you'd rather not, just change the below entries to strings with the config you want - ie #define UDP_PORT 3333 diff --git a/examples/storage/nvs_rw_blob/README.md b/examples/storage/nvs_rw_blob/README.md index 90a8f8bfa9..620edd85e8 100644 --- a/examples/storage/nvs_rw_blob/README.md +++ b/examples/storage/nvs_rw_blob/README.md @@ -19,22 +19,10 @@ If not done already, consider checking simpler example *storage/nvs_rw_value*, t This example can be run on most common development boards which have an active button connected to GPIO0. On most boards, this button is labeled as "Boot". When pressed, the button connects GPIO0 to ground. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` @@ -75,5 +63,5 @@ Run time: 2: 5860 ``` -To reset the counter and run time array, erase the contents of flash memory using `make erase_flash` (or `idf.py erase_flash`, if using CMake build system), then upload the program again as described above. +To reset the counter and run time array, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above. diff --git a/examples/storage/nvs_rw_value/README.md b/examples/storage/nvs_rw_value/README.md index 87d3405d45..df725b0e04 100644 --- a/examples/storage/nvs_rw_value/README.md +++ b/examples/storage/nvs_rw_value/README.md @@ -18,22 +18,10 @@ Check another example *storage/nvs_rw_blob*, which shows how to read and write v This example does not require any special hardware, and can be run on any common development board. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` @@ -90,5 +78,5 @@ Restarting now. Restart counter will increment on each run. -To reset the counter, erase the contents of flash memory using `make erase_flash` (or `idf.py erase_flash`, if using CMake build system), then upload the program again as described above. +To reset the counter, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above. diff --git a/examples/storage/sd_card/README.md b/examples/storage/sd_card/README.md index 09fb2c0cd2..8901c343e9 100644 --- a/examples/storage/sd_card/README.md +++ b/examples/storage/sd_card/README.md @@ -68,12 +68,6 @@ This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG` ## How to use example -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - SD card can be used in various modes. See below on choosing the mode to be used. ### 4-line and 1-line SD modes @@ -96,16 +90,12 @@ By default, the example uses SDMMC Host peripheral to access the card using SD p Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` +(Replace PORT with serial port name.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. diff --git a/examples/storage/semihost_vfs/README.md b/examples/storage/semihost_vfs/README.md index 4728f08662..d25ed1ab42 100644 --- a/examples/storage/semihost_vfs/README.md +++ b/examples/storage/semihost_vfs/README.md @@ -25,21 +25,9 @@ bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -c ' ``` This command also configures OpenOCD to expose example project `data` subdirectory to the target's semihosting VFS driver. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash -Build the project and flash it to the board, then run monitor tool to view serial output: - -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): +Replace PORT with serial port name: ``` idf.py -p PORT flash monitor diff --git a/examples/storage/spiffs/README.md b/examples/storage/spiffs/README.md index aacced044e..d568839563 100644 --- a/examples/storage/spiffs/README.md +++ b/examples/storage/spiffs/README.md @@ -20,21 +20,9 @@ SPIFFS partition size is set in partitions_example.csv file. See [Partition Tabl This example does not require any special hardware, and can be run on any common development board. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash -Build the project and flash it to the board, then run monitor tool to view serial output: - -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): +Replace PORT with serial port name: ``` idf.py -p PORT flash monitor @@ -60,4 +48,4 @@ I (19584) example: Read from file: 'Hello World!' I (19584) example: SPIFFS unmounted ``` -To erase the contents of SPIFFS partition, run `make erase_flash` command (or `idf.py erase_flash`, if using CMake build system). Then upload the example again as described above. +To erase the contents of SPIFFS partition, run `idf.py erase_flash` command. Then upload the example again as described above. diff --git a/examples/storage/spiffsgen/README.md b/examples/storage/spiffsgen/README.md index fcacb6bbdf..1176d343d5 100644 --- a/examples/storage/spiffsgen/README.md +++ b/examples/storage/spiffsgen/README.md @@ -4,7 +4,7 @@ This example demonstrates how to use the SPIFFS image generation tool [spiffsgen.py](../../../components/spiffs/spiffsgen.py) to automatically create a SPIFFS filesystem image from the contents of a host folder during build, with an option of -automatically flashing the created image on invocation of `idf.py flash` or `make flash`. +automatically flashing the created image on invocation of `idf.py flash`. For more information, see description of `spiffsgen.py` on the ESP-IDF Programming Guide under API Reference > Storage > SPIFFS Filesystem. The following gives an overview of the example: @@ -14,10 +14,10 @@ The following gives an overview of the example: 2. The function `spiffs_create_partition_image` is used to specify that a SPIFFS image should be created during build for the `storage` partition. For CMake, it is called from [the main component's CMakeLists.txt](./main/CMakeLists.txt); for Make, from the [project Makefile](./Makefile). `FLASH_IN_PROJECT` specifies that the created image -should be flashed on invocation of `idf.py flash` or `make flash` together with app, bootloader, partition table, etc. +should be flashed on invocation of `idf.py flash` together with app, bootloader, partition table, etc. For both build systems, the image is created on the example's build directory with the output filename `storage.bin`. -3. Upon invocation of `idf.py flash monitor` or `make flash monitor`, application loads and +3. Upon invocation of `idf.py flash monitor`, application loads and finds there is already a valid SPIFFS filesystem in the `storage` partition with files same as those in `spiffs_image` directory. The application is then able to read those files. @@ -56,4 +56,4 @@ I (330) example: Computed MD5 hash of alice.txt: deeb71f585cbb3ae5f7976d5127faf2 I (330) example: SPIFFS unmounted ``` -The logic of the example is contained in a [single source file](./main/spiffsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above. \ No newline at end of file +The logic of the example is contained in a [single source file](./main/spiffsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above. diff --git a/examples/storage/wear_levelling/README.md b/examples/storage/wear_levelling/README.md index 9bf11ded46..9578e16444 100644 --- a/examples/storage/wear_levelling/README.md +++ b/examples/storage/wear_levelling/README.md @@ -20,26 +20,16 @@ Wear levelling partition size is set in partitions_example.csv file. See [Partit This example does not require any special hardware, and can be run on any common development board. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` +(Replace PORT with serial port name.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. @@ -61,4 +51,4 @@ I (920) example: Unmounting FAT filesystem I (1000) example: Done ``` -To erase the contents of wear levelling partition, run `make erase_flash` command (or `idf.py erase_flash`, if using CMake build system). Then upload the example again as described above. +To erase the contents of wear levelling partition, run `idf.py erase_flash` command. Then upload the example again as described above. diff --git a/examples/system/app_trace_to_host/README.md b/examples/system/app_trace_to_host/README.md index 1abb8bde6a..aa5786242d 100644 --- a/examples/system/app_trace_to_host/README.md +++ b/examples/system/app_trace_to_host/README.md @@ -99,7 +99,7 @@ To run this example, you need an ESP32 dev board (e.g. [ESP-WROVER-KIT](https:// ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - By default, the DAC will generate 130 Hz signal within 0V..3.1V. To get 50Hz, you need to set non-standard driver of RTC 8MHz clock to lower minimum CW (Cosine Waveform) generator's frequency in `Set custom RTC 8 MHz clock divider to lower CW frequency`. @@ -107,7 +107,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build, Flash and Run -1. Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. (To exit the serial monitor, type ``Ctrl-]``.) +1. Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects. 2. In the telnet session window, run the following command. This command will collect 9000 bytes of log data and save them to `adc.log` file in `~/esp/openocd-esp32` folder. diff --git a/examples/system/cpp_exceptions/README.md b/examples/system/cpp_exceptions/README.md index 2056379edf..0589d885df 100644 --- a/examples/system/cpp_exceptions/README.md +++ b/examples/system/cpp_exceptions/README.md @@ -12,17 +12,13 @@ Example source code declares a class which can throw exception from the construc ## How to use example -### Configure the project - -Run `make menuconfig` and set serial port under Serial Flasher Options. - ### Build and Flash -Build the project and flash it to the board, then run monitor tool to view serial output: +``` +idf.py -p PORT flash monitor +``` -``` -make -j4 flash monitor -``` +(Replace PORT with the name of the serial port.) (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/system/gcov/main/gcov_example.c b/examples/system/gcov/main/gcov_example.c index 1cfa9ea534..e6d7457680 100644 --- a/examples/system/gcov/main/gcov_example.c +++ b/examples/system/gcov/main/gcov_example.c @@ -13,8 +13,8 @@ #include "esp_app_trace.h" #include "sdkconfig.h" -/* Can run 'make menuconfig' to choose the GPIO to blink, - or you can edit the following line and set a number here. +/* Can use project configuration menu (idf.py menuconfig) to choose the GPIO + to blink, or you can edit the following line and set a number here. */ #define BLINK_GPIO CONFIG_BLINK_GPIO diff --git a/examples/system/light_sleep/README.md b/examples/system/light_sleep/README.md index 2fa545dae6..bdc107cf43 100644 --- a/examples/system/light_sleep/README.md +++ b/examples/system/light_sleep/README.md @@ -17,18 +17,16 @@ The example also prints time spent in light sleep mode to illustrate that timeke This example can be used with any ESP32 development board. Most boards have a button attached to GPIO0, often labelled "BOOT". If the board does not have such button, an external button can be connected, along with a 10k pull-up resistor, and a 100nF capacitor to ground for debouncing. -### Configure the Project - -Run `make menuconfig` and set serial port under Serial Flasher Options. - ### Build and Flash Build the project and flash it to the board, then run monitor tool to view serial output: ``` -make -j4 flash monitor +idf.py -p PORT flash monitor ``` +(Replace PORT with the name of the serial port to use.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. diff --git a/examples/system/ota/README.md b/examples/system/ota/README.md index f9baa4c4bc..0baf9d048d 100644 --- a/examples/system/ota/README.md +++ b/examples/system/ota/README.md @@ -27,7 +27,7 @@ To run the OTA examples, you need an ESP32 dev board (e.g. ESP32-WROVER Kit) or ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. +Open the project configuration menu (`idf.py menuconfig`). In the `Example Connection Configuration` menu: @@ -44,7 +44,7 @@ In the `Example Configuration` menu: ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. This command will find if partition table has ota_data partition (as in our case) then ota_data will erase to initial. It allows to run the newly loaded app from a factory partition. +Run `idf.py -p PORT flash monitor` to build and flash the project.. This command will find if partition table has ota_data partition (as in our case) then ota_data will erase to initial. It allows to run the newly loaded app from a factory partition. (To exit the serial monitor, type ``Ctrl-]``.) @@ -85,7 +85,7 @@ When the example starts up, it will print "Starting OTA example" to the console 3. Write the image to flash, and configure the next boot from this image. 4. Reboot -If you want to rollback to factory app (or the first OTA partition when the factory partition do not exist) after the upgrade, then run the command `make erase_otadata` or `idf.py erase_otadata`. It can erase the ota_data partition to initial state. +If you want to rollback to factory app (or the first OTA partition when the factory partition do not exist) after the upgrade, then run the command `idf.py erase_otadata`. It can erase the ota_data partition to initial state. **Notes:** This assumes that the partition table of this project is the one that is on the device. @@ -127,4 +127,4 @@ In ``native_ota_example``, ``$PROJECT_PATH/version.txt`` is used to define the v If you see this error then check that the configured (and actual) flash size is large enough for the partitions in the partition table. The default "two OTA slots" partition table only works with 4MB flash size. To use OTA with smaller flash sizes, create a custom partition table CSV (look in components/partition_table) and configure it in menuconfig. -If changing partition layout, it is usually wise to run "make erase_flash" between steps. +If changing partition layout, it is usually wise to run "idf.py erase_flash" between steps. diff --git a/examples/system/sysview_tracing_heap_log/README.md b/examples/system/sysview_tracing_heap_log/README.md index 8d39311644..8e4dfad63e 100644 --- a/examples/system/sysview_tracing_heap_log/README.md +++ b/examples/system/sysview_tracing_heap_log/README.md @@ -19,26 +19,14 @@ when program hits breakpoint at `heap_trace_start`. Trace data will be saved to 3. [SEGGER SystemView tool](https://www.segger.com/products/development-tools/systemview/). By default SystemView shows only numeric values of IDs and parameters for IDF's heap messages in `Events` view. To make them pretty-looking you need to copy `SYSVIEW_FreeRTOS.txt` from the project's root directory to SystemView installation one. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash -Build the project and flash it to the board, then run monitor tool to view serial output: - -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` +(Replace PORT with serial port name.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. @@ -161,4 +149,4 @@ Processed 14 heap events. /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1) Found 10 leaked bytes in 4 blocks. -``` \ No newline at end of file +``` diff --git a/examples/system/unit_test/README.md b/examples/system/unit_test/README.md index acea22d5cf..fbba3cf426 100644 --- a/examples/system/unit_test/README.md +++ b/examples/system/unit_test/README.md @@ -55,9 +55,7 @@ This example doesn't require any special hardware, and can run on any ESP32 deve As explained above, this example contains two projects: application project and test project. -When using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options, in each of these projects. - -For the test project, you can explore a few options related to Unity under Component Config, Unity unit testing library. +For the test project, you can open the project configuration menu (`idf.py menuconfig`) and explore a few options related to Unity under Component Config, Unity unit testing library. ### Build and flash @@ -65,12 +63,12 @@ As explained above, this example contains two projects: application project and 1. Application project calls an API defined in the component, and displays the results. It is not of much value to run. Application project is provided mainly to illustrate the layout of all the files. If you decide to run this project, the procedure is: - * Run `make -j4 flash monitor` in the current directory (`unit_test`), or `idf.py -p PORT flash monitor` if you are using CMake build system. + * Run `idf.py -p PORT flash monitor` in the current directory (`unit_test`). * Observe the output: a list of random numbers and their mean value. 2. Test project is responsible for running the tests. - * Enter `test` directory (`unit_test/test`), and run `make -j4 flash monitor`, or `idf.py -p PORT flash monitor` if you are using CMake build system. + * Enter `test` directory (`unit_test/test`), and run `idf.py -p PORT flash monitor`. * Observe the output: results of test case execution. diff --git a/examples/wifi/getting_started/softAP/main/softap_example_main.c b/examples/wifi/getting_started/softAP/main/softap_example_main.c index 515e3618ee..0102895545 100644 --- a/examples/wifi/getting_started/softAP/main/softap_example_main.c +++ b/examples/wifi/getting_started/softAP/main/softap_example_main.c @@ -18,7 +18,7 @@ #include "lwip/err.h" #include "lwip/sys.h" -/* The examples use WiFi configuration that you can set via 'make menuconfig'. +/* The examples use WiFi configuration that you can set via project configuration menu. If you'd rather not, just change the below entries to strings with the config you want - ie #define EXAMPLE_WIFI_SSID "mywifissid" diff --git a/examples/wifi/getting_started/station/main/station_example_main.c b/examples/wifi/getting_started/station/main/station_example_main.c index 917f53cdbb..ae6101f2d4 100644 --- a/examples/wifi/getting_started/station/main/station_example_main.c +++ b/examples/wifi/getting_started/station/main/station_example_main.c @@ -19,7 +19,7 @@ #include "lwip/err.h" #include "lwip/sys.h" -/* The examples use WiFi configuration that you can set via 'make menuconfig'. +/* The examples use WiFi configuration that you can set via project configuration menu If you'd rather not, just change the below entries to strings with the config you want - ie #define EXAMPLE_WIFI_SSID "mywifissid" diff --git a/examples/wifi/scan/main/scan.c b/examples/wifi/scan/main/scan.c index 9607d61147..f5b0d29fd5 100644 --- a/examples/wifi/scan/main/scan.c +++ b/examples/wifi/scan/main/scan.c @@ -28,7 +28,7 @@ #include "esp_event.h" #include "nvs_flash.h" -/*Set the SSID and Password via "make menuconfig"*/ +/* Set the SSID and Password via project configuration, or can set directly here */ #define DEFAULT_SSID CONFIG_EXAMPLE_WIFI_SSID #define DEFAULT_PWD CONFIG_EXAMPLE_WIFI_PASSWORD diff --git a/examples/wifi/simple_sniffer/README.md b/examples/wifi/simple_sniffer/README.md index bf38632507..7c8ba2d4a9 100644 --- a/examples/wifi/simple_sniffer/README.md +++ b/examples/wifi/simple_sniffer/README.md @@ -19,7 +19,7 @@ If you want to send packets to host, make sure to connect ESP32 to some kind of ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - Check `Store command history in flash` if you want to save command history into flash (recommend). - Select where to save the pcap file in `Select destination to store pcap file` menu item. @@ -33,7 +33,11 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you' are using CMake based build system. +``` +idf.py -p PORT flash monitor +``` + +(Replace PORT with name of the serial port.) (To exit the serial monitor, type ``Ctrl-]``.) @@ -114,7 +118,7 @@ I (248800) example: Card unmounted ### Steps for sending packets to host via JTAG interface 1. Select `JTAG (App Trace)` as the destination of pcap files. -2. Build & Flash with `idf.py build flash` or `make flash`. +2. Build & Flash with `idf.py -p PORT flash` 3. Connect JTAG, run OpenOCD (for more information about how-to please refer to [JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html)). 4. Telnet to localhost with 4444 port: `telnet localhost 4444`. 5. In the telnet session, run command like `esp32 apptrace start file://sniffer-esp32.pcap 1 -1 20` (more information about this command, please refer to [apptrace command](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#openocd-application-level-tracing-commands)). diff --git a/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c b/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c index e2127d84ba..232065c4b5 100644 --- a/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c +++ b/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c @@ -30,12 +30,12 @@ #include "tcpip_adapter.h" /* The examples use simple WiFi configuration that you can set via - 'make menuconfig'. + project configuration menu. If you'd rather not, just change the below entries to strings with the config you want - ie #define EXAMPLE_WIFI_SSID "mywifissid" - You can choose EAP method via 'make menuconfig' according to the + You can choose EAP method via project configuration according to the configuration of AP. */ #define EXAMPLE_WIFI_SSID CONFIG_EXAMPLE_WIFI_SSID diff --git a/examples/wifi/wps/main/wps.c b/examples/wifi/wps/main/wps.c index 62465e2de6..5ac103b7f1 100644 --- a/examples/wifi/wps/main/wps.c +++ b/examples/wifi/wps/main/wps.c @@ -29,7 +29,7 @@ #include "nvs_flash.h" -/*set wps mode via "make menuconfig"*/ +/*set wps mode via project configuration */ #if CONFIG_EXAMPLE_WPS_TYPE_PBC #define WPS_MODE WPS_TYPE_PBC #elif CONFIG_EXAMPLE_WPS_TYPE_PIN diff --git a/tools/esp_app_trace/test/sysview/blink.c b/tools/esp_app_trace/test/sysview/blink.c index ecbdf64499..baa345be47 100644 --- a/tools/esp_app_trace/test/sysview/blink.c +++ b/tools/esp_app_trace/test/sysview/blink.c @@ -13,8 +13,8 @@ #include "sdkconfig.h" #include "esp_heap_trace.h" -/* Can run 'make menuconfig' to choose the GPIO to blink, - or you can edit the following line and set a number here. +/* Can use project configuration menu (idf.py menuconfig) to choose the GPIO + to blink or you can edit the following line and set a number here. */ #define BLINK_GPIO CONFIG_BLINK_GPIO diff --git a/tools/idf_monitor.py b/tools/idf_monitor.py index 4700980b0b..f68020613f 100755 --- a/tools/idf_monitor.py +++ b/tools/idf_monitor.py @@ -3,8 +3,8 @@ # esp-idf serial output monitor tool. Does some helpful things: # - Looks up hex addresses in ELF file with addr2line # - Reset ESP32 via serial RTS line (Ctrl-T Ctrl-R) -# - Run "make (or idf.py) flash" (Ctrl-T Ctrl-F) -# - Run "make (or idf.py) app-flash" (Ctrl-T Ctrl-A) +# - Run flash build target to rebuild and flash entire project (Ctrl-T Ctrl-F) +# - Run app-flash build target to rebuild and flash app only (Ctrl-T Ctrl-A) # - If gdbstub output is detected, gdb is automatically loaded # # Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD diff --git a/tools/unit-test-app/README.md b/tools/unit-test-app/README.md index 23ce65289b..0118fc624f 100644 --- a/tools/unit-test-app/README.md +++ b/tools/unit-test-app/README.md @@ -4,16 +4,6 @@ ESP-IDF unit tests are run using Unit Test App. The app can be built with the un # Building Unit Test App -## GNU Make - -* Follow the setup instructions in the top-level esp-idf README. -* Set IDF_PATH environment variable to point to the path to the esp-idf top-level directory. -* Change into `tools/unit-test-app` directory -* `make menuconfig` to configure the Unit Test App. -* `make TEST_COMPONENTS=` with `TEST_COMPONENTS` set to names of the components to be included in the test app. Or `make TESTS_ALL=1` to build the test app with all the tests for components having `test` subdirectory. -* Follow the printed instructions to flash, or run `make flash`. -* Unit test have a few preset sdkconfigs. It provides command `make ut-clean-config_name` and `make ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `make ut-build-default TESTS_ALL=1` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder. - ## CMake * Follow the setup instructions in the top-level esp-idf README. @@ -24,6 +14,16 @@ ESP-IDF unit tests are run using Unit Test App. The app can be built with the un * Follow the printed instructions to flash, or run `idf.py -p PORT flash`. * Unit test have a few preset sdkconfigs. It provides command `idf.py ut-clean-config_name` and `idf.py ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `idf.py -T all ut-build-default` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder. +## Legacy GNU Make + +* Follow the setup instructions in the top-level esp-idf README. +* Set IDF_PATH environment variable to point to the path to the esp-idf top-level directory. +* Change into `tools/unit-test-app` directory +* `make menuconfig` to configure the Unit Test App. +* `make TEST_COMPONENTS=` with `TEST_COMPONENTS` set to names of the components to be included in the test app. Or `make TESTS_ALL=1` to build the test app with all the tests for components having `test` subdirectory. +* Follow the printed instructions to flash, or run `make flash`. +* Unit test have a few preset sdkconfigs. It provides command `make ut-clean-config_name` and `make ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `make ut-build-default TESTS_ALL=1` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder. + # Flash Size The unit test partition table assumes a 4MB flash size. When testing `TESTS_ALL=1` (Make) or `-T all` (CMake), this additional factory app partition size is required.