Introduction to Common Commands

ESP-IDF uses CMake (project configuration tool), Ninja (project building tool) and esptool (flash tool) in the process of code compilation. Each tool plays a different role in the compilation, building, and flash process, and also supports different operating commands. To facilitate user operation, ESP-IDF adds a unified front-end idf.py that allows the above commands to be called quickly.

Before using idf.py, make sure that:

  • The environment variable IDF_PATH of ESP-IDF has been added to the current terminal.
  • The command execution directory is the root directory of the project, which includes the project compilation script CMakeLists.txt.

The common commands of idf.py are as follows:

  • idf.py --help: displaying a list of commands and their usage instructions.
  • idf.py set-target <target>: setting the compilation target, such as replacing <target> with esp32c3.
  • idf.py menuconfig: launching menuconfig, a terminal graphical configuration tool, which can select or modify configuration options, and the configuration results are saved in the sdkconfig file.
  • idf.py build: initiating code compilation. The intermediate files and the final executable program generated by the compilation will be saved in the build directory of the project by default. The compilation process is incremental, which means that if only one source file is modified, only the modified file will be compiled next time.
  • idf.py clean: cleaning the intermediate files generated by the project compilation. The entire project will be forced to compile in the next compilation. Note that the CMake configuration and the configuration modifications made by menuconfig will not be deleted during cleanup.
  • idf.py fullclean: deleting the entire build directory, including all CMake configuration output files. When building the project again, CMake will configure the project from scratch. Please note that this command will recursively delete all files in the build directory, so use it with caution, and the project configuration file will not be deleted.
  • idf.py flash: flashing the executable program binary file generated by build to the target ESP32-C3. The options -p <port_name> and -b <baud_rate> are used to set the device name of the serial port and the baud rate for flashing, respectively. If these two options are not specified, the serial port will be automatically detected and the default baud rate will be used.
  • idf.py monitor: displaying the serial port output of the target ESP32-C3. The option -p can be used to specify the device name of the host-side serial port. During serial port printing, press the key combination Ctrl+] to exit the monitor.

The above commands can also be combined as needed. For example, the command idf.py build flash monitor will perform code compilation, flash, and open the serial port monitor in sequence.

You can visit https://bookc3.espressif.com/build-system to know more about ESP-IDF compilation system.