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

PlatformIO IDE
1

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?

1 Like
2

Seen Professional collaborative platform for embedded development — PlatformIO latest documentation ?

3

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?

1 Like
4

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.

1 Like
5

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.

2 Likes
6

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?

1 Like
7

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
8

If you planned to use all the good features of the Arduino IDE, then the explanation of working with the PlatformIO concept, must have been based on experience working with the ArduinoIDE. Of course this applies to the “Arduino” framework. ArduinoIDE way to search the library as:
"#include “library name”
“#include <library name>”
is good enough to determine the library search path.
For example, I’ve been trying for two days to open examples for sipeed-maixduino, but it doesn’t work.
Examples are constantly being opened for K210, but not for maixduino.Although I see that in “…\platformio\packages\framework-maixduino\libraries…” there are examples related to libraries, but it is impossible to get to them in the normal Arduino way, or in some similar way that is explained.
These criticisms of mine are not aimed at undermining your product, but on the contrary to facilitate the transition from ArduinoIDE to PlatformIO in some way. I think it’s time for a serious document called “Migration from ArduinoIDE to PlatformIO”

regards

9

This is a rather old topic, but it could still be informative. How ever; when I search on “How open an exiting Workspace in PlatformIO/VSCode” I don’t find what I, looking for. What I do find is this:

Quite nice, that’s exactly what I have, but…
How do I open that existing Workspace with all the contents in it?

1 Like
10

To save a workspace to file, File -> Save Workspace As..., and give the workspace file name.

To restore a save workspace, File -> Open Workspace..., and open that saved workspace file.

If you want to re-open one you’ve saved or had open recently, it’ll be listed in the File -> Open Recent submenu, with (Workspace) at the end of the name.

11

Yes! That was in the past, before I removed the list in “Recent”.

But now when I do: File > Open Workspace > I land in the Finder where I can perfectly navigate to the workspace folder in question and Open it, but I’m never able to open the workspace and return to VSCode/PlatformIO.

So, is there just maybe a command line statement to open a specific workspace in VSCode/PlatformIO?

I just found out that Start > Open folder > navigate to the Workspace folder in question does the trick. Yes! It’s obscure, but after a good night rest…

12

Ok, that’s because workspace is not what you are actually after :wink:

A workspace in VSCode can be a collection of ‘different’ folders (i.e. not in the same parent folder), the configuration of which is saved to a file, which is what you can then later re-open.

If you have a set of projects organised in the one folder, you want the ‘File → Open folder’ option instead.

13

Thank you!
I’m struggling with this subject from the moment I entered VSCode/PlatformIO. Every time I want to open a new project within and existing WorkSpace, it’s a hassle to get it right and working the way I want it to.
If I understand you well, your’e saying that a Workspace in VSCode/PlatformIO is notting more than a folder with a specific name.
OK, when that is correct; than what is the purpose/meaning of the file: “MyWorkSpace.code-workspace”. At the moment I manually adjust the contents of this file to get things working the way I want them to work. Which is of course not the proper way of doing things; we should use a computer for just that.
But, lacking the knowledge and/or the experience, I see no other option.
Any enlightenment in this matter would be greatly appreciated!

To gain insight on the structure I’m using, see: Schermafbeelding-2021-04-27-om-13-09-07 hosted at ImgBB — ImgBB

14

No, a workspace is a virtual construct, and just a mechanism for letting you organise things.

Think of it like your web browser, you have a series of tab open, for different shopping websites, and you want to save all those tabs for later, so you can re-open those tabs. They are completely different websites, but you have the ability to save that collection as you’ve organised it.

Maybe this will help illustrate it better…

image
image987×383 38.8 KB

This ‘workspace’ is a set of four folders, two of which are in the Projects/PlatformIO/ESP8266 folder… and two of which are in the repos/gitea folder… basically no-where near each other, but they are all grouped together in the one workspace.

If you only want to open a single folder, i.e. WS_Testen or WS_WebRadio, you should be using the File → Open Folder option, to open those folder, not using workspaces.

But if you want to be able to have both listed in file browser sidebar at the sime time, you can open folder with File → Open Folder, and then use the ‘File → Add Folder to Workspace’ option to add the second folder to the workspace.

15

Thanks for the explanation, You’ve made it somewhat more clear.
But…
When I do: File > Open > WS_WebRadio I get:
![Schermafbeelding 2021-04-27 om 16.46.18|690x330](upload://qK

Schermafbeelding 2021-04-27 om 16.46.18
Schermafbeelding 2021-04-27 om 16.46.181285×616 173 KB
9SQGC1dQZwGNZr7eAnsivw8Gx.png)
Which havocs al my “links” to libraries somehow.
Whereas when I do: Recent > WebRadio [~/PlatformIO/WS_WebRadio
all is well.

16

Ok, sorry for the delay.

Right, because it’s your subfolders (Web_Radio_01, Web_Radio_2, etc) that are the ones that actually contain the platformio.ini that needs to be in the root, rather than the WS_WebRadio folder. So, you need to either open those folders and work on them individually - OR - add each of those one by one to a workspace… as it seems you want a multi-root configuration.

Basically, either open a folder that contains a platform.ini, or manually add multiple folders which have platformio.ini … and you can then save that as a workspace.