In this tutorial, you’ll learn how to deal with workspaces on VS Code to organize your ESP32 and ESP8266 projects. You’ll learn what is a single-folder workspace, a multi-root workspace, the advantages of workspaces, and how to use them.
To get familiar with VS Code with the ESP32 and ESP8266, follow the next tutorial first:
You can also use VS Code to program your boards with MicroPython firmware:
Table of Contents
Throughout this tutorial, we’ll cover the following topics:
- What is a Workspace (VS Code)?
- Add Folders to Workspace
- Save Workspace
- Workspace File
- Workspace Settings
- Workspace Enabled/Disabled Extensions
- Upload a Project in a Multi-Root Workspace
- Open/Close Workspace
What is a Workspace (VS Code)?
The workspace concept might be difficult to understand, mainly when you’re getting started with VS Code. But, you’ll see that it is a straightforward and useful concept to organize your projects. We’ll try to keep this concept as simple as possible and applied to our ESP32 and ESP8266 projects. If you want to learn more, you can read the workspaces documentation.
A workspace is simply a collection of one or more project folders opened in a VS Code window (File Explorer).
Single Folder Worskapce
In most cases, you work with only one project folder at a time—in this scenario, the workspace is your project’s single root folder.
For example, create a new PlatformIO project or open a new project folder. In the following example, I created a new PlatformIO project called ESP32 Web Server. The workspace is the project folder itself.
However, depending on the project, it might be useful to include multiple project folders in the workspace. For example, imagine that your project requires two or three ESP32 or ESP8266 boards that communicate with each other. In that case, it might be useful to have all the boards’ project folders inside a single workspace—this is called Multi-root workspace.
For example, if you create another PlatformIO project, it will add it to the current workspace. In this case, the workspace name will be Untitled until you save it and give it a name. In this case, I created another project called ESP32 esp-now sender.
Advantages of Workspaces
- [Multi-root workspace] It allows you to open/list on the File Explorer all folders inside that workspace without the need to open a single folder at a time.
- A workspace is like a folder with extra capabilities. For example, a workspace can have configured settings that only applies to its folders (or to the folder itself, in the case of single-folder workspaces). Any other folder opened in VS Code outside that workspace won’t have the same settings.
- You can selectively enable or disable extensions for a specific workspace. This is useful if you interchangeably work with MicroPython or Arduino core projects. This allows you to automatically enable the right extensions for the project you’re working on (PlatformIO for Arduino core projects, and PyMakr for MicroPython projects).
Adding Folders To Workspace
You can also add existing folders to the current workspace. You need to go to File > Add Folder to Workspace.. and select the project folder you want to add.
At this point, I have three projects under my untitled workspace.
You can save your workspace and give it a name. To save your workspace, you need to go to File > Save Workspace As...
The workspace is saved as a file with the .code-workspace extension. In my case, I called my workspace file ESP-NOW-project.code-workspace.
Now, it shows up on the Explorer tab with the new name.
A workspace file has the .code-workspace extension, and it is simply a file that contains a list of the folders and files that should be listed on the File Explorer. Projects saved on the same workspace will show up simultaneously on VS Code File Explorer tab.
Additionally, the workspace file may also contain specific settings for the included folders, as we’ll see in the next section.
To see how a workspace file looks like, go to File > Open File and select the .code-workspace file you’ve created when you saved the workspace.
As you can see, it includes the paths of the included project folders. At the moment, it doesn’t have any custom settings yet. Let’s see how to add custom settings to workspaces in the next section.
As mentioned previously, a workspace is like a folder with extra capabilities. It can have configured settings that only apply to its folders (or to the folder itself, in single-folder workspaces).
To set custom settings for your workspace, you can go to File > Preferences > Settings. Then, select the workspace tab (this way, the defined setting will only apply to the currently opened workspace).
There are lots of settings that you can define for your workspace. For demonstration purposes, we’ve only made a few changes. Under the Commonly Used settings, we set the Auto Save to afterDelay and the font size to 12.
We also changed the Color Theme—go to Workbench > Appearance > Color Theme. We selected the Light + theme.
From now on, every time you open that workspace, it will show the light color theme.
Nonetheless, the default VS Code color theme remains the Dark +. This means that if you close the workspace or open another project, it will get back to the default settings or whatever settings you have defined for that specific workspace.
Now, if you open your workspace file, you’ll see that it contains the new settings.
Workspace Enabled/Disabled Extensions
You can also enable or disable extensions for a specific workspace. For example, if you open a MicroPython project, you want the PyMakr extension to be enabled by default. However, you don’t want that extension enabled if you’re working on a project programmed with the Arduino core.
To show you how to do that, we’ll enable the PyMakr extension for this specific workspace (imagine it contains several Micropython project folders).
You need to go to the Extensions tab and search for a specific extension. In our case, it’s the PyMakr extension. Select that extension, and then under the Enable button, click on Enable (Workspace). For the changes to take effect, you need to restart VS Code.
From now on, that extension will be enabled when you’re working on that workspace.
Uploading a Project in a Multi-Root Workspace
This section refers to PlaformIO projects (Arduino core).
When dealing with multi-root workspaces, you need to be able to choose which project you want to upload to your board. For that, you need to click on the current project name, as shown in the following image.
Then, a drop-down menu will show up at the top of the window with all the project folders on the workspace. You need to select the project folder you want to upload to your board.
To close the current workspace, you need to go to File > Close Workspace.
To open an existing workspace, go to File > Open Workspace…
Using VS Code is one of the best choices for advanced (or even simple) ESP32 and ESP8266 projects. You can use VS Code to program your boards with the Arduino core using the PaltformIO extension, or with MicroPython firmware using the PyMakr extension. Both extensions were already covered in our blog (PlatformIO, PyMakr).
One of the biggest disadvantages of using VS Code is the learning curve. It may be tough for beginners to understand how everything works. One of the topics that confuse our readers a lot is the concept of Workspace. The workspace is simply a folder or collection of folders that show up on the File Explorer tab. The workspace can be configured with specific settings that apply to its folders.
After following this tutorial, we hope that you better understand what a workspace is and that you can take advantage of the workspace concept, mainly for projects that require multiple boards.
Let us know in the comments below if this is clear for you now.
Learn more about the ESP32/ESP8266 with our resources:
- Build ESP32/ESP8266 Web Servers
- ESP32 Projects
- ESP8266 Projects
- MicroPython Projects (ESP32 and ESP8266)
Thanks for reading.
8 thoughts on “VS Code Workspaces with ESP32 and ESP8266 Projects”
This is a great tutorial. I was hoping this would solve the mystery for new Platform IO users as to how the file management systems compares to the “tab” feature in Arduino. Maybe you could touch on this in the next tutorial in the Platform IO series.
Why you are not making the projects using the ESP-IDF toolchain for ESP32.
Would appreciate one on version control in VScode
John, to do version control you need to use Git, it works seamlessly with VS code. There is an excellent free book on using Git. It seems a bit daunting at first but once you begin to use it becomes quite easy. Hopefully Ruis and Sarah will do a tutorial in their inimitable style.
This recent tutorials on workspaces is the best I have seen, particularly the last section on how to select which file is uploaded, a LOT of people struggle with that. Once you lnow the method it is simple.
These tutorials are great, thank you!
I agree. As follow-up to this tutorial, guidance (in this very style!) how to use git on adding external libraries from github, managing own code in a separate repository etc would be helpful.
I still get confused how to lay out my code base to keep things tidy.
Maybe I just have not found the right guide yet, would appreciate links.
Thanks for the suggestions.
I’m looking forward to installing Platform IO for about the 4th or 5th time. All previous attempts proved fruitless: at first I didn’t have all the parts while following the instructions for OTHER website (not RandomNerd), then when I did have installed there were no clear instructions on how to do anything. De-installed 4 or 5 times.
NOW, it looks like RandomNerds has really did a good job of spelling it all out. When I used to write labs for my students, I left no ambiguities and my labs worked perfectly and I got high praise for them. I’ve got RandomNerds as a favourite, downloaded some of their books. Their work and site is the really the best of all in its genre. So…soon, I’ll be trying Platform I/O, Random Nerd version. Thanks for all your good work.
Thank you for your nice words.
I’m glad our tutorials are helpful.