PlatformIO Community

Right way to create a registry library

I’m struggling searching the correct way to develop a library.
I already followed instructions by ( Creating Library — PlatformIO 5.2.0a4 documentation ) with no luck.
I using vscode with platformio plugin and would of help if Projects/Create New Project wizard allow to choose between Application or RegistryLibrary to allow developer start with a correct library structure.
More could helpful if platformio examples repo contains a dedicated registry-lib folder with a bare skeleton to develop a library with src, include, examples, unit test the right way.

Btw I already published one and I succesfully use into another application but I have to remove the library.json file from the local libdeps or the compiler will generate error and I would to know why this happens.


  • from vscode, platformio create new project ( name: test1, board: nucleo f446re, framework: arduino )
  • from pio terminal : pio lib install "devel0/iot-utils@0.7.0"
  • setup src/main.cpp as follow
#include <Arduino.h>

#include <string-utils.h>

void setup() {
  // put your setup code here, to run once:

void loop() {
  // put your main code here, to run repeatedly:
  • from pio start a build
  • follows errors
PLATFORM: ST STM32 (12.1.1) > ST Nucleo F446RE
HARDWARE: STM32F446RET6 180MHz, 128KB RAM, 512KB Flash
DEBUG: Current (stlink) On-board (stlink) External (blackmagic, cmsis-dap, jlink)
 - framework-arduinoststm32 4.10900.200819 (1.9.0) 
 - framework-cmsis 2.50501.200527 (5.5.1) 
 - toolchain-gccarmnoneeabi 1.90201.191206 (9.2.1)
LDF: Library Dependency Finder ->
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 10 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Compiling .pio/build/nucleo_f446re/src/main.cpp.o
src/main.cpp:3:10: fatal error: string-utils.h: No such file or directory

to solve I have to remove or rename the .pio/libdeps/nucleo_f446re/iot-utils/library.json but I don’t know why ( here library.json relates to library itself ) ; after removed file dependency scanner correctly find the library and error disappears:

Found 11 compatible libraries
Scanning dependencies...
Dependency Graph
|-- <iot-utils> 0.7.0
Building in release mode

This is invalid.

Platforms is the microcontroller platform (e.g. ststm32), frameworks is e.g. the arduino core or mbed. Backwards. Docs are right.

PlatformIO reads this library.json and sees it can only use it for these platforms and frameworks, but its compilation configuration

does not match it, hence it sees it as a incompability library.

By deleting the library.json you delete the source of information where PlatformIO would find out that the library is incompatible, hence it works.

You get the same result if you disable the compatibility check by doing

lib_compat_mode = off

in the platformio.ini without deleting any files.

I’d just recommend to release a new library version with the library.json fixed.

@maxgerhardt thanks you!
I confirm it worked, also I updated with changes on library.json where I swapped frameworks and platforms.