New user bit confused with workspcace /folder structure / project

Hi, I have been mainly using the arduino IDE for constructing my projects and yesterday moved to vsscode and platformio, which I have found to be brilliant. I’ve read a lot of documentation, but I’m struggling a bit with workspace, folders and projects.

In my arduino ide world, I use Github to version control the source code for my projects and each project has a folder intialised as a git repo, containing the ino and gitignore.

So today I’ve had some great help to get a debug environment working for my mega2560 boards and I configured the platformio.ini file accordingly, using a led blink test sketch.

Next, I thought I’d import one of my arduino projects from the local git repo and I did that from platformio home ‘import arduino project’. However, it’s apparent that the source code is being saved elsewhere (not in my git repo ) and I’ve verified that by adding a comment to the source, saving it and then inspecting the file in the git repo. Also the changes I made to the platformio.ini are no longer there (probably not lost I’m guessing - I have a copy anyway).

So I think I’m missing something to do with workspace and project organisation in platformio/ vsscode.

Any help with a good approach would be welcome,


I never use VSCode workspaces. For some reason, I just don’t see the point! Maybe it’s just me.

I create a new project using the PlatformIO commandline commands:

cd SourceCode/PlatformIO
mkdir myProject 
cd myProject
pio init --board uno

You can do the equivalent from the PlatformIO Home page in VSCode, the “create project” option.

Then, I open the folder that I’m in, the new project folder, using the command code . – the dot is required, it means “current folder”.

I now have my project open in VSCode ready to work with.

If I want version control locally I just git init as normal.

If I wan’t to put it on GitHub, I tend to create a new repository while logged in to GitHub, add a; add a licence – usually MIT; add a .gitignore for C++ projects.

I then clone that repo, update the readme and .gitignore as required, then – and this is definitely not the most efficient method – copy my project contents over!

Then the usual git status, git add, git commit and git push.

From now on, I can edit, commit etc in VSCode.

This workflow works fine for me as it fits in with other stuff I do in my day job, but as I mentioned, it’s not highly efficient. It works for me.



1 Like

Indeed. By using “Import Arduino Project” PlatformIO will allow you to select a folder with a .ino file and select a board. It will then create a new folder in which it initializes a standard PlatformIO project with the given board, plus that .ino file as initial source code.


That folder will by default be created in the user’s “Documents” folder in “PlatformIO/Projects”. It will not modify the original directory.

The standard PlatformIO project folder structure can e.g. be seen at platform-atmelavr/examples/arduino-blink at develop · platformio/platform-atmelavr · GitHub.

Source files which are supposed to be compiled should be in src/, include files (.h) which are not compiled can go in include/ (or src/), lib/ can be used as folder in which further library folders can be stored that the project needs locally, and test/ is for files regarding unit testing.

The pio init command also says that.

>pio init -b uno

The current working directory C:\Users\Max\Desktop\test will be used for the project.

The next files/directories have been created in C:\Users\Max\Desktop\test
include - Put project header files here
lib - Put here project specific (private) libraries
src - Put project source files here
platformio.ini - Project Configuration File

All of these foldernames and paths can be abritrarily reconfigured (docs) using platformio.ini directives.

So using that it would e.g. be possible to have a folder structure where it’s just one .ino file and the platformio.ini in one folder. But that’s not standard configuration. Example:

A folder contains the platformio.ini:

; redirect src/ dir from "src/" to "here"
src_dir = .

platform = atmelavr
board = uno
framework = arduino

and a main.ino file

void setup() { pinMode(LED_BUILTIN, OUTPUT); }
void loop() {
  digitalWrite(LED_BUILTIN, LOW);
  digitalWrite(LED_BUILTIN, HIGH);

Such a project folder can used directly using the command line

>pio run
Processing uno (platform: atmelavr; board: uno; framework: arduino)
Verbose mode can be enabled via `-v, --verbose` option
PLATFORM: Atmel AVR (3.0.0) > Arduino Uno
HARDWARE: ATMEGA328P 16MHz, 2KB RAM, 31.50KB Flash
DEBUG: Current (avr-stub) On-board (avr-stub, simavr)
 - framework-arduino-avr 5.1.0
 - toolchain-atmelavr 1.50400.190710 (5.4.0)
Converting main.ino
LDF: Library Dependency Finder ->
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 5 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Compiling .pio\build\uno\src\main.ino.cpp.o
Linking .pio\build\uno\firmware.elf
Building .pio\build\uno\firmware.hex
Checking size .pio\build\uno\firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM:   [          ]   0.4% (used 9 bytes from 2048 bytes)
Flash: [          ]   2.9% (used 930 bytes from 32256 bytes)
============================ [SUCCESS] Took 1.88 seconds ============================

And can be imported into VSCode using the “Open Project” button (not Import Arduino Project! This is a valid PlatformIO project already since it has a platformio.ini) and be edited normally.

Note though that for editing code in a sensible way, the file extension should be .cpp and not .ino, since the Microsoft C++ Intellisense extension only works on cpp files. Also note conversion rules.

Thus you could e.g. add a plaformio.ini of the style above in your sketch folder and treat is a PlatformIO project with just a modified folder structure.

For ease of development and separation of things (e.g. includes from source files, and project source code from library source code), the normal structure should be preferred though.

1 Like

thanks very much for replies, it’s all very helpful. I’ll probably stick with the platformio structure on reflection. I can work on moving the git repo to the new locations

Hello again,

I’ve imported two arduino projects, one is an Azimuth Encoder and the other is a Command Processor.

The system names the projects in the following fashion:


and the name above describes my command processor project .

This naming doesn’t really describe the project in a meaningful way, so can I change the project name ? (preferably at import time as I have a few to import).


The project name is just the folder name. Can be abitrary.

In VSCode, you can right-click on the folder and select “Reveal in explorer”. Then in VSCode you should right-click on the folder again to “Remove folder from workspace”. Then go ahead and rename the folder, then use PIO home with the “Open Project” button to import the folder again.

(That procedure because with VSCode open you can’t just rename the folder directly because files are opened in there – also PIO will look for this folder after restart and get a little confused if it suddenly isn’t there anymore, so a clean unload-reload is good)

There’s no such setting sadly. I’ve opened Feature request: Let "Project name" text input in "Import Arduino Project" dialogue · Issue #2306 · platformio/platformio-vscode-ide · GitHub for that.

Thanks, I closed vsscode, renamed the project folder name to ‘Command Processor’ and I can now open the project folder from platformio ‘open platformio project’. Brill.


I was unable to find my project until I found out that I can right click the tab of the file and select Reveal in folder and I found that is saving my projects in Onedrive.