Getting Started with VSCode & PlatformIO! A Complete Guide to Building an Embedded Software Development Environment on WSL

Up until now, I have introduced embedded software development using VSCode and PlatformIO in the following articles.

• Trying out IoT (Part 14: OLED SSD1306 Edition with Organic EL Display)
• Debugging an ESP32 Development Board using ESP-PROG and PlatformIO
• Debugging a Raspberry Pi Pico using a Raspberry Pi Debug Probe and PlatformIO
• Debugging an STM32 Microcontroller Board (STM32F103C8T6) using an ST-Link V2 Compatible Device and PlatformIO
• Remote Development with the Ever-Popular VSCode and the Embedded Software Development Environment PlatformIO (Arduino)

Now, today's topic is "Let's install PlatformIO on WSL (Ubuntu) and create an embedded software development environment."
The final setup image is envisioned as follows:

Assume that VSCode is already installed on Windows.

The steps for the setup are as follows:

• Install Ubuntu 24.04 on Windows using WSL
• Install the VSCode extension (WSL or Remote Development)
• Connect to WSL in VSCode
• Install PlatformIO on WSL
• Recognize USB devices in WSL (using Usbipd-WIN)
• Upload the program to Arduino from WSL (using PlatformIO)

Now, let's get started.

WSL (Windows Subsystem for Linux) is a feature that allows you to run a Linux environment on Windows.
Using WSL, you can easily set up a Linux environment on Windows.

For detailed steps on installing Linux (Ubuntu) on Windows using WSL, please refer to this article.
Note, however, that there is no need to install Docker this time.

The software development itself is carried out in VSCode, which is installed on Windows.
To connect from VSCode to WSL, the "WSL" extension is used.

In the future, if you plan to develop via SSH connections or within Docker containers, it is advisable to install the "Remote Development" extension.

When you install the "Remote Development" extension, the following four extensions are installed simultaneously:

• WSL (the extension used in this article)
• Remote - SSH
• Dev Containers
• Remote - Tunnels

Once the extensions are installed, the "Remote Explorer" is added to the left pane in VSCode.

Click on the "Open a Remote Window" button at the bottom left of VSCode and select "Connect to WSL".

Once the connection is complete, the display at the bottom left of VSCode changes as shown below (when connected to Ubuntu 24.04 in WSL):

Whether PlatformIO is installed on WSL or on the local environment, the installation method is the same.
Make sure you are connected to WSL in VSCode (★ This is important) and then install the "PlatformIO IDE" extension in VSCode.

When PlatformIO is correctly installed on the WSL side, a marker indicating that the installation target is remote appears at the bottom right of the extension's icon.
Additionally, it will display which WSL environment the extension is active in.

Now, here's a challenge.
While the Arduino microcontroller is connected to the host PC and the program is uploaded via the USB COM port, this time the development environment is Ubuntu on WSL.

"How do we get the USB from the host PC to be recognized in WSL (Ubuntu)?"

In a virtual environment like VirtualBox, you might be able to set it up to recognize USB devices, but I have no desire to give up on WSL now and switch to another environment.
So, is there any way to get the USB COM port recognized in WSL (Ubuntu)?
After some searching, I found this information on Microsoft's website.
It appears that using usbipd-win as introduced there can solve the problem.
Download the latest version from the above site and install it on the host PC.

After installing the application, display the list of USB devices by running the following command.

usbipd list

In my environment, the following USB device list was displayed.

After connecting the Arduino microcontroller to the host PC, run the USB device list command again.
This time, one additional device appears.
It seems that the BUSID "3-2" corresponds to the USB device created when the Arduino microcontroller was connected.

Now, share (bind) the USB device indicated by this BUSID so that it can be used from WSL.
Launch PowerShell or the Command Prompt as an administrator and run the following command.
(Replace the BUSID according to your environment.)

usbipd bind --busid 3-2

Then, the STATE field changes to "Shared", indicating that the device is now shared.

However, in this state, the USB device is still not usable from WSL.
To utilize it, you need to attach it.
Attach the USB device to WSL by executing the following command.

usbipd attach --wsl --busid 3-2

The following log was output.

When you check the USB device list again, you can confirm that the STATE has changed to "Attached".

By the way, the command to detach is as follows.

usbipd detach --busid <busid>

Additionally, the command to unbind (stop sharing) is as follows.

usbipd unbind --busid <busid>

Also, when using PlatformIO on Linux, the "99-platformio-udev.rules configuration" introduced in a previous article is required, so perform this configuration on Ubuntu running on WSL.
(The article introduced above targeted Rasbian (Raspberry Pi), but since it's Linux-based, the same procedure applies.)

Now, the environment for program development and uploading is finally set up.
Looking back, it seems that configuring the USB device was far more troublesome than setting up PlatformIO.

For uploading the program to the Arduino microcontroller, the usual "Blink (L-Chika) program" is used.
The program is the same as the one found here.

Click the upload button.

After the upload, if the log output appears as shown below and the LED on the Arduino microcontroller blinks at one-second intervals, the upload is successful.

For those who find it tedious to perform USB sharing and attachment via the command line, here is a GUI tool for you.
Installing this tool allows you to manage USB sharing and attachment through a graphical interface.

The interface looks something like this:

I had hoped to accomplish everything with just VSCode + WSL + PlatformIO, but to manage USB device operations, it was necessary to install some applications on Windows.
However, since usbipd-win is also featured on Microsoft's website, that's acceptable for now.
With this, you now have an environment to develop embedded software on Ubuntu running on WSL without cluttering your host PC.
I plan to continue introducing various embedded device development environments in the future.