PlatformIO Community

Workplaces, projects, folders, directories, libraries, files, Windows, Configurations? Huh?

I have been singularly unable to find a cogent explanation of exactly what the terms I list in the above Topic title really really mean, and how they interrelate. As a complete newbie with near-perfect ignorance of PlatformIO, I can’t get very far without knowing what those terms mean. I’ve seen discussions from the experts, but they use terms that are undefined for me. I note that in the File menu I can create a “New” File or Window, but nothing else. I note that I can “Open” a File, Folder or Workplace, but nothing else. I don’t seem to be able to create a Workplace, but I can save a new one. Where does it come from, what’s in it, and why would I want to do that?

If anyone knows of a written-word explanation of these terms, please tell me and stop reading at this point. My working circumstance (read workplace with a small w) bans the use of YouTube and all social medias, so I must have a written document to read. Anyone know of a good one?

Seen https://docs.platformio.org/en/latest/ ?

jcw… Thanks for the quick reply. I have used the link you provided a number times, and my confusion and disappointment remain. Please don’t view what I am saying as criticism–I really want to learn to use PIO for it’s obvious advantages over the Arduino IDE. But that link is full of details and organized in a very bottoms-up fashion. None of the terms I mention above are even discussed, that I could find. If they’re there, they must be buried under details. So let me be more specific about one frustration I’ve encountered:

I have done two PIO Projects that use two different ESP32 boards, and two different TFT display panels. Each Project has its own Folder, and I’ve saved a unique Workplace for that Project in that Folder, hoping that the suite of libraries would be kept separate, but they are not kept separate. To use a TFT display a certain file within the library itself must be custom-configured for the specific TFT display you are using. When I change that file using Reveal in a given Project/Workspace to find it, both Projects are affected. Worse, if I reinstall the libraries, I lose the changes I put into that file. I thought one advantage of PIO was locking libraries to Projects, but I haven’t been able to figure out how to do that. What am I doing wrong?

OK, I’ve made some progress at isolating library installs to a given project:

(1) The process for installing libraries incorrectly in PIO is easy enough:
a. Go to Home>>Libraries and the first tab (Registry) is already selected. (That’s nice.)
b. Type in enough of the name of the library into the search box and hit the magnifying icon, and select the library you want to install by clicking on it. (That’s nice.)
c. This brings up a screen for the library with the latest version number and a big blue “Install” button next to it. (Danger ahead!)
d. If you hit that button, PIO does exactly the wrong thing: It installs the library into a Global Library, something that is officially discouraged. (I find it interesting that the default action of the button does precisely the wrong thing.)
e. Instead, hit the part of the blue button with “. . .” on it, and a subtle “Install to…” box appears below. (Hard to see, actually)
f. Hit that “Install to…” option, and (Danger ahead!)
g. a screen comes up with, again, the ill-advised setting of “Global” in the second box from the top. (Again.)
h. Hit the dropdown arrow way over to the right of the Global box, and, finally, it lists your existing projects. (Very subtle arrow, actually—missed it at first.)
i. Select the Project you want to install the library for, and you’re finally done.

|(2)| Along the way I learned that the TFT_eSPI library generates information for PlatformIO to use that makes selecting a specific TFT display configuration easy. With that library installed I go to .pio>libdeps>User Setups and some 46 options are offered, including one for the TTGO_T_Display that I was using. I copied the contents of that file into an include file in my Project include folder, and there was no need to edit anything in the library itself. Might be an easier way to do this than the cut and paste process I did.
(3) As for opening an existing Project, I find it easier to the “Projects” icon on the home vertical ribbon, rather that the “Open Project” button on the home page, which requires a file drill-down process from the Windows User level.
(4) As for Workspaces, the lightbulb is dimly glowing as to what they are and why I would want to save and open them. I just didn’t understand what the term meant.

As terrific as PlatformIO is, I find the docs inscrutable. I’m sure they are accurate and precise but there’s something missing.

It reminds me of a little web server I played with on an Amiga years ago, the docs consisted of about 15 lines that made little sense… until I understood how it worked and then docs made perfect sense.

Maybe there should be a grand overview or an idea of the deign philosophy, how the bits fit together.

My current project is 10,000+ lines spread over 48 files, so I know my way around PlatformIO but when something doesn’t work as expected I’m stuck foe awhile, usually I manage to solve the problem but it’s more by luck than understanding.

1 Like

This isn’t going to be exhaustive, but will hopefully alliterate some of the confusion, whilst also causing some more :wink: :laughing:

Project - self contained folder with a platformio.ini which provides all the configuration information needed for the project to compile / upload / otherwise function. Usually as an include folder (for header files), lib folder (for private project specific libraries), src folder (for the source code) and test folder (for unit tests).

Workspace - VSCode allows you have multiple projects within the one workspace, which can be saved and re-opened later. Workspaces can also have different ‘user settings’ and extensions enabled or disabled.

Windows - You might have multiple VSCode windows open, in which you might have different workspaces, projects or even individual files open for viewing/editing.

Folders / directories / files - nothing special here - just your normal folder/directory or files. Usually accessed in VSCode using the ‘explorer’ sidebar panel.
libraries,

Configurations - probably generally relates to your platformio.ini, and the different [env:env-name] blocks you might have in it, which can be for different boards, or the same board, but with different settings. i.e. you might have some code that have something (pseudocode-ish!!) like…

#if DEVICE_MODE == 1 then
  //set device as transmitter
#elif DEVICE_MODE == 0 then
  // set device as receiver
#fi

… which means in your platformio.ini you would have two different environments (lets call them [env:tx] and [env:rx]… creative, right?), and use build_flags = -DDEVICE_MODE=0 or build_flags = -DDEVICE_MODE=1 to have them change mode… with a single click from the GUI, and no changes to the code needed.

Are you using lib_deps to install the library, or did you install it via the libraries view of PIO Home, which means it’s probably in global storage, hence why both projects are using a single copy of the library.

And if that library happens to be Bodmer 's TFT_eSPI, there is a much better way to configure it with PlatformIO than editing the configuration file, which also means you won’t loose configuration settings if you update the library. Is that the library in question?

Pfeerick…

This isn’t going to be exhaustive, but will hopefully alliterate some of the confusion, whilst also causing some more :wink:

Blockquote
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

1 Like