What is the correct procedure for using local libraries in Workbench?


I have a difficult time using libraries in Workbench. There are a couple of scenarios, and I’d like to know the proper process for getting each one setup:

Scenario 1 - Using a library from the Particle cloud
Honestly, this one seems pretty straight forward. I use “Particle Install Library” and install to my local folder from the Particle Cloud. This reliably allows a library to be included in my project using the #include <library.h> syntax. In other words, both cloud and local compile work in this case.

Scenario 2 - Using a library that’s not in the Particle cloud
I can only get this to work for the simplest scenario imaginable. If I have a .h file and a .cpp file in the same directory as my .ino then life is good (I think). If I want to start making folders in my project and organizing things in to folders and subfolders then it all goes south. Neither Intellisense nor the compiler seem to be able to find anything.

Scenario 3 - Using a local copy of a library that exists in the Particle cloud, but a newer/alternate version (likely from github)
I get the idea that there are steps needed beyond just downloading the library and sorting out the issues I have in scenario 2.

I’m assuming all of this will eventually be covered in the docs for Workbench. Right now the only reference I can find to libraries is for the Particle libs.



Scenario 1 - Using a library from the Particle cloud

Yes, that works well.

Scenario 2 - Using a library that’s not in the Particle cloud

You should manually copy the library into a subdirectory of the libs directory in the top level of your project folder. It should have the same directory structure as a real library, so it needs a library.properties file and typically a src directory.

Scenario 3 - Using a local copy of a library that exists in the Particle cloud, but a newer/alternate version (likely from github)

Copy the whole directory structure to a subdirectory in libs, as well.

Another scenario: If you install the library (Scenario 1) and then decide to edit your local copy you can do so. However you must also remove the library from the dependencies of your project.properties file! The libs directory will be uploaded, but if you leave the library in both places, the cloud version (in project.properties) has precedence.


Here’s what I just did, and can’t get to work:

  1. Created a new project called LibraryTesting
  2. Executed Particle: Install Library and installed ArduinoJSON from the cloud

I see the newly created lib directory, and ArduinoJSON under that. I can add #include <ArduinoJSON.h> to my .INO and it still compiles both cloud and local (#include “ArduinoJSON.h” does not work though) even with the examples still in place.

I now remove the dependency in project.properties because I want to make sure that the local copy is the one used when compiling. I made no changes to the actual library, but let’s assume I wanted to. Cloud compile now fails with:

In file included from src/LibraryTesting.ino:1:0:
lib/ArduinoJson/src/ArduinoJson.h:9:27: fatal error: ArduinoJson.hpp: No such file or directory
#include “ArduinoJson.hpp”

Local compile still appears to work, although I’ve not yet been able to cloud flash anything I’ve compiled locally (different problem for another day).

This is, fundamentally, the error that I get when I start with libraries from github as well.

Here’s the folder structure if it helps:


That’s a special case. For cloud compile only project.properties, .ino, .h, .cpp & .c files are uploaded to the cloud. Your .hpp file will be left behind.
Before Libraries v2.0 you could nominate extra files via a spark.include or exclude via spark.ignore files but that option hasn’t been carried over (unfortunately).

[ISSUE] Local compile OK - cloud compile has errors

OK, well that explains it. I guess I’ll have to get myself functional with local compile for now. Hope the other options return at some point, as cloud compile/flash in one step is sure handy.


Hmmmm. Turn out that’s not my only issue. I’m suspicious that this may be something buggered up with my particular VSCode install because I could swear this worked previously…

Anyway here’s the picture. I created a very simple “library” which has one class with one method that adds two integers. I simply can not get Workbench to find the .h file

I’ve tried all sorts of permutations of specifying the whole path and none of them seem to help.

Where is the include path defined? Is this path used for both compile and Intelisense, or does the later have it’s own configuration?


IntelliSense isn’t to be taken seriously :wink: It’s often slow to learn new skills :blush:
And the compile error seems to be a cloud build output. Do you have a more elaborate build result message to post? (view log)


Odd. I had closed VSCode after posting. Now I reopened it to get the info for @ScruffR and it works. It cloud compiled just fine, and IntelliSense is acting - sensible if I dare say so.

It’s kind of a moot point anyway though. With the file extension limitations in V2 libraries I doubt I’ll be trying this too often. I’ll likely stick with Particle libraries when I want cloud compile, and work fully locally when I want to use Github code.

I am still curious where the include path is defined. I can envision use cases where you may want to include a library that isn’t stored in the project folder hierarchy.


That’s a question I’d defer to @m_m


Did you ever figure out how to do this? I find it disconcerting that this question hasn’t been answered since February.


From the images of the library structure posted - this library layout structure recommendations have not been followed. it is also documented here, interns of the structure required (whether you contribute the library or not)