library.json¶

name¶

Required | Type: String | Max. Length: 50

A name of a library.

• Must be unique

• Should be slug style for simplicity, consistency, and compatibility. Example: HelloWorld

• Can contain a-z, digits, and dashes (but not start/end with them)

• Consecutive dashes and [:;/,@<>] chars are not allowed.

version¶

Required | Type: String | Max. Length: 20

A version of a current library source code. Can contain a-z, digits, dots or dash and should be Semantic Versioning compatible.

Example:

"name": "Bar",
"version": "1.0.0",
"repository":
{
    "type": "git",
    "url": "https://github.com/foo/bar.git"
}

description¶

Required | Type: String | Max. Length: 255

The field helps users to identify and search for your library with a brief description. Describe the hardware devices (sensors, boards and etc.) which are suitable with it.

keywords¶

Required | Type: String or Array | Max. Length: 255

Used for search by keyword. Helps to make your library easier to discover without people needing to know its name.

The keyword should be lowercased, can contain a-z, digits and dash (but not start/end with them). A list from the keywords can be specified with separator , or declared as Array.

homepage¶

Optional | Type: String | Max. Length: 255

Home page of a library (if is different from repository url).

repository¶

Optional | Type: Object

The repository in which the source code can be found. The field consists of the next items:

• type the only “git”, “hg” or “svn” are supported

• url

• branch if is not specified, default branch will be used. This field will be ignored if tag/release exists with the value of version.

Example:

"repository":
{
    "type": "git",
    "url": "https://github.com/foo/bar.git"
}

authors¶

Optional | Type: Object or Array

An author contact information

• name Full name (Required)

• email

• url An author’s contact page

• maintainer Specify “maintainer” status

Examples:

"authors":
{
    "name": "John Smith",
    "email": "me@john-smith.com",
    "url": "https://www.john-smith/contact"
}

...

"authors":
[
    {
        "name": "John Smith",
        "email": "me@john-smith.com",
        "url": "https://www.john-smith/contact"
    },
    {
        "name": "Andrew Smith",
        "email": "me@andrew-smith.com",
        "url": "https://www.andrew-smith/contact",
        "maintainer": true
    }
]

license¶

Optional | Type: String

A SPDX license ID of the library. You can check the full list of SPDX license IDs (see “Identifier” column).

"license": "Apache-2.0"

frameworks¶

Optional | Type: String or Array

A list with compatible frameworks. The available framework names are defined in the Frameworks section.

Example:

"frameworks": ["espidf", "freertos"]

If the library is compatible with the all frameworks, then do not declare this field or you use * symbol:

"frameworks": "*"

platforms¶

Optional | Type: String or Array

A list with compatible development platforms. The available platform name are defined in Development Platforms section.

Example:

"platforms": ["atmelavr", "espressif8266"]

If the library is compatible with the all platforms, then do not declare this field or use * symbol:

"platforms": "*"

headers¶

Optional | Type: String or Array

A list of header files that can be included in a project source files using #include <...> directive.

Examples:

"headers": "MyLibrary.h"

"headers": ["FooCore.h", "FooFeature.h"]

examples¶

Optional | Type: Array | Glob Pattern

A list of example patterns. This field is predefined with default value:

"examples": [
    {
        "name": "Hello",
        "base": "examples/world",
        "files": [
            "platformio.ini",
            "include/world.h",
            "src/world.c",
            "README",
            "extra.py"
        ]
    },
    {
        "name": "Blink",
        "base": "examples/blink",
        "files": ["blink.cpp", "blink.h"]
    }
]

dependencies¶

Optional | Type: Array or Object

A list of dependent libraries. They will be installed automatically with pio lib install command.

Allowed requirements for dependent library:

• owner | Type: String – an owner name (username) from the PlatformIO Registry

• name | Type: String – library name

• version | Type: String – version or version range in SemVer format

• frameworks | Type: String or Array – project compatible Frameworks

• platforms | Type: String or Array – project compatible Development Platforms

The version supports Semantic Versioning ( <major>.<minor>.<patch>) and can take any of the following forms:

• 1.2.3 - an exact version number. Use only this exact version

• ^1.2.3 - any compatible version (exact version for 1.x.x versions

• ~1.2.3 - any version with the same major and minor versions, and an equal or greater patch version

• >1.2.3 - any version greater than 1.2.3. >=, <, and <= are also possible

• >0.1.0,!=0.2.0,<0.3.0 - any version greater than 0.1.0, not equal to 0.2.0 and less than 0.3.0

The rest possible values including VCS repository URLs are documented in pio lib install command.

Example:

"dependencies":
{
    "bblanchon/ArduinoJson": "^6.16.1",
    "me-no-dev/AsyncTCP": "*",
    "external-repo": "https://github.com/user/package.git#1.2.3",
    "external-zip": "https://github.com/me-no-dev/AsyncTCP/archive/master.zip"
}

More advanced usage:

"dependencies":
[
    {
        "owner": "bblanchon",
        "name": "ArduinoJson",
        "version": "^6.16.1"
    },
    {
        "owner": "me-no-dev",
        "name": "AsyncTCP",
        "version": "*",
        "platforms": ["espressif32"]
    },
    {
        "name": "external-repo",
        "version": "https://github.com/user/package.git#1.2.3"
    },
    {
        "name": "external-zip",
        "version": "https://github.com/me-no-dev/AsyncTCP/archive/master.zip"
    }
]

export¶

Optional | Type: Object

This option is useful if you need to exclude extra data (test code, docs, images, PDFs, etc). It allows one to reduce the size of the final archive.

To check which files will be included in the final packages, please use pio package pack command.

Possible options:

"export": {
    "include":
    [
        "dir/*.[ch]pp",
        "dir/examples/*",
        "*/*/*.h"
    ]
}

build¶

Optional | Type: Object

Specify advanced settings, options and flags for the build system. Possible options:

├── lib
│   ├── README
│   └── SomeLib
│       ├── extra_script.py
│       ├── hal
│       │   ├── bar
│       │   │   ├── hal.c
│       │   │   └── hal.h
│       │   ├── foo
│       │       ├── hal.c
│       │       └── hal.h
│       ├── library.json
│       ├── SomeLib.c
│       └── SomeLib.h
├── platformio.ini
└── src
    └── test.c

[env:foo]
platform = native
build_flags = -DHAL=foo

[env:bar]
platform = native
build_flags = -DHAL=bar

{
    "name": "SomeLib",
    "version": "0.0.0",
    "build": {
        "extraScript": "extra_script.py"
    }
}

Import('env')
from os.path import join, realpath

# private library flags
for item in env.get("CPPDEFINES", []):
    if isinstance(item, tuple) and item[0] == "HAL":
        env.Append(CPPPATH=[realpath(join("hal", item[1]))])
        env.Replace(SRC_FILTER=["+<*>", "-<hal*>", "+<hal/%s>" % item[1]])
        break

# pass flags to a global build environment (for all libraries, etc)
global_env = DefaultEnvironment()
global_env.Append(
    CPPDEFINES=[
        ("MQTT_MAX_PACKET_SIZE", 512),
        "ARDUINOJSON_ENABLE_STD_STRING",
        ("BUFFER_LENGTH", 32)
    ]
)

Examples¶

1. Custom macros/defines

"build": {
    "flags": "-D MYLIB_REV=1.2.3 -DRELEASE"
}

2. Extra includes for C preprocessor

"build": {
    "flags": [
        "-I inc",
        "-I inc/target_x13"
    ]
}

3. Force to use C99 standard instead of C11

"build": {
    "unflags": "-std=gnu++11",
    "flags": "-std=c99"
}

4. Build source files (c, cpp, h) at the top level of the library

"build": {
    "srcFilter": [
        "+<*.c>",
        "+<*.cpp>",
        "+<*.h>"
    ]
}

5. Extend PlatformIO Build System with own extra script

"build": {
    "extraScript": "generate_headers.py"
}

generate_headers.py

Import('env')
# print(env.Dump())
env.Append(
    CPPDEFINES=["HELLO=WORLD", "TAG=1.2.3", "DEBUG"],
    CPPPATH=["inc", "inc/devices"]
)

# some python code that generates header files "on-the-fly"