library.json¶

name¶

Required | Type: String | Max. Length: 50

A name of a library.

• Must be unique in the PlatformIO Registry

• 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: SPDX Expression

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

Examples

A single license

"license": "Apache-2.0"

Multiple license using SPDX Expression

"license": "MIT AND (LGPL-2.1-or-later OR BSD-3-Clause)"

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 that will be automatically installed.

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 Requirements or Package Specifications

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

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

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 pkg pack command.

Possible options:

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

scripts¶

Optional | Type: Object

Execute custom scripts during the special Package Management CLI life cycle events:

Examples

1. Run a custom Python script located in the package “scripts” folder AFTER the package is installed. Please note that you don’t need to specify a Python interpreter for Python scripts.

   "scripts": {
       "postinstall": "scripts/after_install.py"
   }
   

2. Run a custom Bash script BEFORE the package is uninstalled. The script is declared as a list of command arguments and is located at the root of a package:

   "scripts": {
       "preuninstall": ["maintainance.sh", "--action", "uninstall"]
   }
   

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 flags (only for the current "SomeLib" source files)
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 the global env (project files, frameworks)
global_env = DefaultEnvironment()
global_env.Append(CPPDEFINES=[("TEST_GLOBAL", 1)])

# pass flags to the project dependencies (libraries)
for lb in env.GetLibBuilders():
    lb.env.Append(CPPDEFINES=[("TEST_LIBDEPS", 1)])

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"