ESP32 + ESP-IDF on Windows: Fixing PlatformIO whitespace path errors, CP2102 Code 28, and CLI setup
I recently set up an ESP32 development environment using:
- VS Code
- PlatformIO CLI
- ESP-IDF
- DOIT ESP32 DEVKIT V1
- Windows
During the setup I ran into a few problems that may be useful to other beginners.
1. pio was not recognized
Initially PowerShell returned:
pio : The term 'pio' is not recognized...
The PlatformIO executable was installed inside the PlatformIO Python environment, but its Scripts directory wasn’t available through PATH.
After adding the PlatformIO Scripts directory to PATH and restarting VS Code, pio --version worked.
2. ESP-IDF reported a whitespace path error
The next problem was:
Error: Detected a whitespace character in project paths.
The project itself had been moved to a path without spaces, but PlatformIO was still using its default Core directory under the Windows user profile.
I moved PlatformIO’s Core directory to a path without spaces:
D:\PlatformIO
and configured:
PLATFORMIO_CORE_DIR=D:\PlatformIO
After restarting VS Code, pio system info showed the new Core directory.
This resolved the whitespace-path issue.
3. Creating the ESP-IDF project from CLI
I then created the project using:
pio project init --board esp32doit-devkit-v1 --project-option="framework=espidf"
The project was opened directly in VS Code and built using:
pio run
The ESP-IDF build completed successfully.
4. ESP32 was detected by Windows but no COM port appeared
pio device list initially returned nothing.
Device Manager showed:
CP2102 USB to UART Bridge Controller
Code 28
The problem was the missing Silicon Labs CP210x USB-to-UART driver.
After manually installing the driver through:
Device Manager
→ Update Driver
→ Browse my computer for drivers
and selecting the folder containing silabser.inf, Windows detected the device as:
Silicon Labs CP210x USB to UART Bridge
A COM port then appeared and PlatformIO detected it.
5. Upload
Finally, the firmware was uploaded using:
pio run -t upload --upload-port COMx
The upload completed successfully.
Complete guide
I documented the complete process, including the troubleshooting steps and recommended folder structure:
Hopefully this helps someone who gets stuck during the initial ESP32 + PlatformIO + ESP-IDF setup on Windows.
If there are better/recommended ways to handle the whitespace-path issue or PlatformIO installation layout, corrections are welcome.