This isn’t going to be exhaustive, but will hopefully alliterate some of the confusion, whilst also causing some more
Perfect answer, thanks very much. This is precisely what’s missing when you try to initially use PlatformIO and are a complete novice. The documentation does not define some critical terms, but goes on to use them as if everyone knows what they mean. There’s lots of “here’s why you want to use PlatformIO instead of the Arduino IDE”, but no explanation of actually how to make that transition. I don’t want a link to a video I can’t watch, I want a written-word tutorial.
Since many PlatformIO users are transitioning from the Arduino IDE, a good document would describe the Arduino IDE as-is, then describe the equivalent structures and concepts for Platform. For example…
"In the Arduino IDE, sketches are contained in a folder that includes one special .ino file that is required to have the same name as the folder. This is the main program of the sketch in a language similar to C++. Additional .h and .ino files can be in the parent folder, and they appear as tabs in the Arduino IDE. This allows you to divide up you sketch into logical parts. They are compiled and linked for upload to your target board.
With PlatformIO, sketches are organized into “Projects” that are contained in a “Folder” that has a specific sub-folder structure, and some additional files that further define the project. Two important folders are the “src” folder (for .ino or .cpp files), and the “include” folder (for .h files). One important file is the platformio.ini file, which specifies the target board for the sketch, the “Framework” (usually Arduino), and optionally other configuration items, like upload speed and serial monitor speed. There are other files in the Project Folder that are automatically generated by PlatformIO to, for instance, keep track of the libraries used by the Project.
When you are at the “Home” screen in PlatformIO and hit the “New Project” button, you must first name the project, then select the target board, and then the Framework is automatically set to Arduino. This process creates the Project folder structure, and the platformIO.ini file inside it. So in PlatformIO, a project is always tied to a specific board type.
In the Arduino IDE you must select the Port from the Tools menu, but with PlatformIO port selection is automatic.
In the Arduino IDE, source files have the extension .ino or .h, and the code is based on C++, but a lot of leeway is granted as to syntax and usage. PlatformIO defaults to .cpp file extensions, but .ino is also allowed, and treated as a .cpp file. With PlatformIO, be prepared to program rigorously in C++, and all that that means. That can be frustrating for some. Sketches that work in the Arduino IDE may not compile and link correctly in PlatformIO. You’ll have tighter code at the end of the day, but sometimes those days are long and fraught with learning.
In the Arduino IDE there is one “global” library for all the sketches and boards you may have, and the IDE attempts to sort it out what is needed at compile/link/upload. While this works well enough initially, after many sketches and boards are used, the library management can be a headache. With PlatformIO you may install a library as global (not generally recommended) or as a Project Library (which eliminates the conflicts between boards/sketches).
In the Arduino IDE, some libraries require you to edit one or more “Setup” files in the library to tailor the library for the specific configuration of your hardware, such a TFT display screen size for instance. Since you’re editing a global library, this may cause a project with a different display screen to stop working correctly. PlatformIO has hooks into some of the libraries to make this more automatic and specific only to the target board/screen for the Project. Drill down in the .pio/libdeps/(your library), if you need this advanced feature.
Finally, you make have multiple Projects open simultaneously, and you may have tailored things for a specific purpose in a certain way, and you can save all as a “Workplace”."
So, pfeerick, I hope you get the idea: I’ve dumbed down the concepts for a newbie like myself. Thanks very much for your guidance and quick support on this…Jack