Arduino Library creation


Has anyone had experience with creating an Arduino Library with platformio ?

How do you setup the environment? I haven’t managed to get very far with this at all

Many thanks


I’ve written a couple for my up coming book, but I’ve not documented the process. Mine are usable on both Arduino and PlatformIO with no code changes, so slightly different to the usual Arduino libraries.

This explanation from Sparkfun might be useful. How to Write A Great Arduino Library - News - SparkFun Electronics



Hi Norm

Many thanks for your message!

I’m actually going through a Sparkfun tut on it now!

Any chance of sneak previewing your book?



Just create a normal PlatformIO project with the microcontrollers your library is targeting, then start developing the library in a folder in lib/ with testing code in the src/ folder of the project. If development is done, publish the lib/ in a repo standalone (or pull it in via a git submodule in the first place).

The needed folder layout of the library is always written in the README.

If you strictly want to write an Arduino library, you should add a of the documented format to the library.

An example is e.g. GitHub - adafruit/Adafruit-MCP23017-Arduino-Library: Arduino Library for Adafruit MCP23017

Sorry, no can do. It’s not about libraries, they just wheedled their way in by the back door as some example code.

I’m not allowed to publish related/similar material if it contains “too much” of the book stuff. Publishers, eh? :wink:

Give me a shout (private message) if you have any questions on you library though, I’ll try ti help.

Also, pay attention to what @maxgerhardt posted above.


Thanks for your message. I’m just testing a simple example and not sure how to tell the testing code in ‘src’ about the lib code - hence getting a ‘No such file or directory’. How do I specify the lib path?

Many thanks


Screen Shot 2021-08-24 at 7.31.25 pm

You have not followed the README I linked to in regards to the needed folder structure in lib/.

Ok noted - I’ll take a look.

Yep - that worked. Thanks!

In any case I’d probably be interested in buying your book when it comes out



1 Like

Hi (again) - the structure is all good but for the life of me I can’t include an examples folder and get the source to compile.

I have included the examples in the ‘lib’ folder as per the README and each example.cpp file is in a folder of the same name.
I have also placed an include in the [env] section of the .ini file:

-I lib/RandomNumber/examples/example-01

example-01.cpp is not getting compiled however

Apologies if the question seems a bit simple - I’m not normally a C/C++ programmer

Screen Shot 2021-08-24 at 10.55.31 pm

Many thanks


It appears that you have the examples folder within lib\RandomNumber?

The example @maxgerhardt links above is a pure Arduino library, in the format that the Arduino IDE likes to have. The structure is of this format:


Within src, you just have the sources and headers for the library itself. Within examples (lower case is a necessity!) you have various sub-directories containing the *.ino files for each example.

PlatformIO can read and understand this directory structure when used with the Arduino framework. If you were to convert this to a dedicated PlatformIO library, then as @maxgerhardt indicated above, you would copy the src folder into lib and rename it to the name of your library. Then, obviously, remove the files from the original src directory.

If you intend to write a library for PlatformIO, which is not in the Arduino structure, this is exceedingly helpful! Creating Library — PlatformIO latest documentation.



A -I flag is for adding a path to the include search path, so that if a code does #include <some_file.h>, the compiler may find in one of the added paths. It does not add a file to the build-system. Refer to my post above as to what files are compiled in a PlatformIO project.

If you want to run the example, either copy the contents of example-01.cpp to the src/main.cpp file of your test project, or use a pio ci command on the console. This creates and compiles an example on-the-fly. Uploading is not possible though, it’s intended for a compilation check, as can e.g. be seen on the Continuous Integration page.

Example usage

pio ci --board=uno lib/MyTestLibrary/examples/example-01 --lib lib/MyTestLibrary

Would dynamically create a board = uno (with the default setting framework = arduino), using the source files in lib/MyTestLibrary/examples/example-01 while copying the contents of lib/MyTestLibrary into the newly-created project’s lib/ folder.

See GitHub - maxgerhardt/pio-arduino-lib-development-example.

I think its back to the drawing board. Whilst I appreciate both of your replies, I’m still in the dark as to where to put the examples and how to build them. I understand the structure of the Arduino library - that’s not the issue.

Anyway, I’ll post here again when (if) I make any progress. I don’t understand why something that should be trivially simple is so difficult to get right and why there is no decent instruction on it.

Anyway no worries


You’ve already put the examples in the correct location, and I’ve referenced two ways you can build them.

After a longer look I realised this once I’d seen your git repo. I didn’t know about the correct ‘pio’ command. The examples now compile - not sure why the example files aren’t built anywhere and also if it is possible to automate a distribution build but with what you’ve given me I can move forward

Many thanks


What do you define as a “distribution build”?

A distribution folder with the production build eg you would change all .cpp files to ino, add in docs or other files…etc Maven, grunt, webpack…etc

The file extension in the examples can be .ino, PIO will be able to build that too. The other stuff is not related to PIO builds.

I found an older post on here about someone running gulp. Also noticed the pre & post directives and the ability to get to ‘env’ to execute stuff. So I should be able to work it out from there