VS Code Workspaces with ESP32 and ESP8266 Projects

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:
Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266
You can also use VS Code to program your boards with MicroPython firmware:
MicroPython: Program ESP32/ESP8266 using VS Code and Pymakr
Table of Contents
Throughout this tutorial, we’ll cover the following topics:
What is a Workspace (VS Code)?
Single-folder Workspace
Multi-root Workspace
Advantages of Workspaces
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.
Multi-Root Workspace
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.
Save 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-workspac
e.
Now, it shows up on the Explorer tab with the new name.
Workspace File
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.
Worskpace Settings
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.
Open/Close Workspave
To close the current workspace, you need to go to
File
>
Close Workspace
To open an existing workspace, go to
File
>
Open Workspace…
Wrapping Up
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 yo