Since ESP-IDF version 6.0 (IIRC), Espressif has a new way of installing versions of ESP-IDF: ESP-IDF Installation Manager. Or EIM in short.
This is an improvement compared to the past: more user-friendly and you can have multiple ESP-IDF versions next to each other.
There are two possibilities to run EIM:
Or directly, running the exe
Or via Visual Studio Code, after you installed the ESP-IDF plug-in
To install the plugin, open Visual Studio Code, go to the market place, search for ESP-IDF and install. As imple as that.
Click on the Espressif icon, open the Advanced section in the list opening on the left side and select "Open ESP-IDF Installation Manager".
See image below.
Once the EIM is open, select New Installation (if that's the first time) or select Manage Installations or New Installation if you already have a version on your PC.
We're supposing a new installation here, so click New Installation.
You now will be asked what kind of installation you want to do. Select Custom Installation since that one gives you maximum freedom (version, installation location,...)
A 10-steps plan will start and during the progress, some questions will be asked:
Target chips: leave the All selected (default)
ESP-IDF version: select v6.0.1, which is the latest version as of this writing (20260524)
Download mirrors: don't change anything and take the default selected ones, just go to the next step
ESP-IDF features: take the default ones
Tools: take the default ones
Installation location: here you can select where the framework must be installed. Default is C:\ESP, which I don't like. So, change to whatever location you like.
Press Continue: the installation process will start, which takes quite some time. So, be patient.
Some time later, you will see that the installation is complete. In my case, stuff was downloaded in C:\Espressif and installed in the location I specified.
Once the installation is complete, there will be a shortcut put on the desktop to open idf.py in a PowerShell window. However, when you run that shortcut, you will see lots of errors, like so:
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:82 char:21 + $previous = $env:'_IDF.PY_COMPLETE' + ~~~~~ Variable reference is not valid. ':' was not followed by a valid variable name character. Consider using ${} to delimit the name.
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:82 char:26 + $previous = $env:'_IDF.PY_COMPLETE' + ~~~~~~~~~~~~~~~~~~ Unexpected token ''_IDF.PY_COMPLETE'' in expression or statement.
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:83 char:9 + $env:'_IDF.PY_COMPLETE' = 'powershell_source' + ~~~~~ Variable reference is not valid. ':' was not followed by a valid variable name character. Consider using ${} to delimit the name.
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:83 char:14 + $env:'_IDF.PY_COMPLETE' = 'powershell_source' + ~~~~~~~~~~~~~~~~~~ Unexpected token ''_IDF.PY_COMPLETE'' in expression or statement.
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:91 char:13 + $env:'_IDF.PY_COMPLETE' = $previous + ~~~~~ Variable reference is not valid. ':' was not followed by a valid variable name character. Consider using ${} to delimit the name.
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:91 char:18 + $env:'_IDF.PY_COMPLETE' = $previous + ~~~~~~~~~~~~~~~~~~ Unexpected token ''_IDF.PY_COMPLETE'' in expression or statement.
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:83 char:14 + $env:'_IDF.PY_COMPLETE' = 'powershell_source' + ~~~~~~~~~~~~~~~~~~ The assignment expression is not valid. The input to an assignment operator must be an object that is able to accept assignments, such as a variable or a property.
At C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1:91 char:18 + $env:'_IDF.PY_COMPLETE' = $previous + ~~~~~~~~~~~~~~~~~~ The assignment expression is not valid. The input to an assignment operator must be an object that is able to accept assignments, such as a variable or a property. + CategoryInfo : ParserError: (:) [], ParseException + FullyQualifiedErrorId : InvalidVariableReferenceWithDrive PS C:\Users\Geert\Desktop>
All the errors boill down to the fact that there are illegal statements used in the script located in:
C:\Espressif\tools\Microsoft.v6.0.1.PowerShell_profile.ps1
This script has to be modified as follows:
Search for all occurances of '_IDF_PY_COMPLETE' (mind the beginning and end quotes!!!)
Replace with _IDF_PY_COMPLETE (quotes removed and dot replaced with _)
Save the file and if you now run the shortcut, a new PowerShell window will open and you will see this:
IDF PowerShell Environment
-------------------------
Environment variables set:
IDF_PATH: D:\WinApps\Programming\Espressif\ESP\.espressif\v6.0.1\esp-idf
IDF_TOOLS_PATH: C:\Espressif\tools
IDF_PYTHON_ENV_PATH: C:\Espressif\tools\python\v6.0.1\venv
Custom commands available:
idf.py - Use this to run IDF commands (e.g., idf.py build)
esptool.py
espefuse.py
espsecure.py
otatool.py
parttool.py
Python environment activated.
You can now use IDF commands and Python tools.
If you run, for instance, the command idf.py --list-targets, then you will see the following output:
(venv) PS C:\Users\Geert\Desktop> idf.py --list-targets
esp32
esp32s2
esp32c3
esp32s3
esp32c2
esp32c6
esp32h2
esp32p4
esp32c5
esp32c61
To see all possible idf.py options, just type idf.py.
Assuming the installation is OK now, we can go for the next step: create a new project in Visual Studio Code, based on the ESP-IDF framework.
To do so, open Visual Studio Code.
The next step is to create a new project using the New Project Wizard option in the Advanced menu of the ESP-IDF plugin. So, click on the ESP-IDF icon to open the ESP-IDF explorer. Then expand the Advanced secion.
Next, click on the New Project Wizard item. A popup will appear in the bottom right, showing ESP-IDF Is busy preparing stuff. Wait a moment.
After a few seconds, a command will appear at the top of the screen, asking which version of ESP-IDF you want to use. Since we installed only one version, select the default one (should be 6.0.1 for now).
Shortly after, a New Project tab will open and you will see a window with title New Project.
Next to this, on the left side of the window, you will see two items:
ESP-IDF Examples
ESP-IDF Templates
If you're curious about the examples, open the Examples section and see what interests you. For now, open the Templates section.
You will see there's only one template: sample_project. Double-click on it and you will see a button inviting you to create a new project using that one template. Click the button.
You will be asked for different items now:
Project name: Give the project a name. That name will also be used as directory name later on.
Enter Project directory: by default it's pointing to your user account. You can press the browse button to change the location (note that you can't change the directory name, only the path to the directory name).
Choose ESP-IDF Target (IDF_TARGET): since we're using an ESP32-C3, select that one.
Choose ESP-IDF Board: since I chose esp32c3, it automatically chose the ESP32-C3 chip (via builtin USB-JTAG). Don't change it.
Choose serial port: select the serial port where your ESP32-C3 module is connected to. For example: COM3, but YMMV.
Add your ESP-IDF Component directory: I never fill in something here. It seems it's only interesting if you want to create components yourself, which I don't want to do.
Press the Create Project button: the directory and a lot of other stuff will be created for you.
At the end of this procedure, you will have the opportunity to open the project: click the Open Project button to do so.
The strange thing is that this action is opening a second Visual Studio Code. Don't know why. I then simply close the first Visual Studio Code session...
I don't know why and I don't know where, but for every new project I create, there's also a .devcontainer subdirectory created. This is only when you're intending to use Docker, but that's not what I want.
You might see a small box popping up in Visual Studio Code telling you it has decteted Docker stuff and asking if it has to do something with that. You also have the opportunity to tell Visual Studio Code not to show this anymore. Neither for this project, nor for the rest of your life!
Click it to get rid of that silly thing...
Note that this directory doesn't influence your project. I think you can even delete it if you don't like it...
When the new project is open, you will see that the status bar is changing quite a bit. Espressif did a very good job in adding lots of useful information and shortcuts in the status bar. Let's go one by one:
Double sideway triangles: open a remote connection (to me, has nothing to do with ESP-IDF...)
Folder: change project (at least, that's what I think, never used it)
ESP-IDF version: you see the version of ESP-IDF used. If you click on that one and you have more than one version installed, you can switch versions here (there will be a list of ESP-IDF versions appearing at the top of the screen)
Star (select flash method): here you can change the way you want to flash your device
Com port: here it shows which COM port is currently selected and active. Clicking on it gives you the opportunity to change.
ESP device: here it shows which ESP32 chip is selected. Clicking on it gives you the opportunity to change.
Cog wheel: gives you the opportunity to create the configuration settings forcefully. It takes a while before this is done. The result is the file sdkconfig, located in the project directory.
Note that this will also be implicitly generated when building the project for the first time.
Bin symbol: pressing this will clean the whole project. Note that a new build will take a long time then...
Wrench symbol: pressing this will build the project
Lighting symbol: pressing this will flash the build result into the ESP chip
Monitor: here you can see the logs that are possibly put in your SW
Sideways triangle with cog wheel: pressing this will start a debug session
Flame symbol: 3 actions in one; build, flash and start the SW
Monitor with symbol: start a special ESP-IDF window. This is a PowerShell window that starts a virtual Python environment and where you can run different idf.py commands (e.g. to build, flash, start your SW on the ESP chip)
Monitor with arrow: run a custom task (not used so far...)
Triangle with exclamation mark: shows number of problems, 0 if none.
OpenOCD Server: no idea, never used
QEMU: no idea, never used
Below is an example of a taskbar where you can recognise all the items explained above.
Once you opened the project after you created it, it's wise to press the wrench symbol in the status bar. This will start a build and will take some time (the very first time, some 990+ files needs to be build!).
At the end of the build you will also see a memory map with the types of memory used and how much is still available. Can come in handy at some point in time...
This will give you an indication if the setup of your new project is OK. If so, you can start building/changing/adding files for your new project.
Good luck!
Since version 6, MQTT is not part of the core framework anymore. Why? No idea.
This is what I read about it: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/protocols/mqtt.html.
If you want to have MQTT functionality in your project, you have to add the dependency yourself using the idf.py script. You better run this in a PowerShell script, so click the "Monitor with triangle and underscore" symbol in the task bar to create such session.
Then run idf.py add-dependency espressif/mqtt. This will do the following:
Create the file idf_component.yml inside the main subdirectory
Add the dependency line espressif/mqtt: '*'
A new build is needed now, but you will be able to use MQTT functionality again.
Note: the MQTT functionality is only added for this very project. New projects have to repeat the actions again.
By default, the flashing communication is set to JTAG. That won't work. The correct setting must be UART.
To change:
Click the hollow star symbol on the task bar
A choice menu will appear at the top of the screen
Select UART instead: the text next to the hollow star should change from JTAG to UART
Flashing the SW to the ESP32 chip should be OK again now.
Apparently, when using the standard configuration, only 2MB of the flash memory is used. You can see this when compiling a "bare" new project and look to the output. You will see the following line somewhere:
W (224) spi_flash: Detected size(4096k) larger than the size in the binary image header(2048k). Using the size in the binary image header.
This is not what we want, obviously. We want to use the full 4MB.
To change this, run the SDK Configuration editor. Shortcut: Ctrl-E G.
When open (I had to try a couple of times, don't know why), search for Serial flasher config.
One of the items is Flash size and is set to 2MB. Change this to 4MB like given in the image below.
Press the Save button at the top and recompile the application (note: a complete rebuild will be issued).
You should now using the full 4MB of flash memory.
You can check this with the serial monitor in Visual Studio Code: if you start an application or press the RST button on the board, you should see the following line in the output:
I (28) boot.esp32c3: SPI Speed : 80MHz
I (32) boot.esp32c3: SPI Mode : DIO
I (36) boot.esp32c3: SPI Flash Size : 4MB
I (39) boot: Enabling RNG early entropy source...
I (44) boot: Partition Table:
This proves the flash size is now set correctly.