library.json¶

name¶

Required | Type: String | Max. Length: 50

A name of the library.

• Must be unique.

• Should be slug style for simplicity, consistency and compatibility. Example: Arduino-SPI

• Title Case, Aa-z, can contain digits and dashes (but not start/end with them).

• Consecutive dashes are not allowed.

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 | 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 ,

authors¶

Required if repository field is not defined | 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": "http://www.john-smith/contact"
}

...

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

repository¶

Required if downloadUrl field is not defined | 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"
}

version¶

Required if repository field is not defined | Type: String | Max. Length: 20

A version of the current library source code. Can contain a-z, digits, dots or dash. Semantic Versioning IS RECOMMENDED.

Case 1:

version and repository fields are defined. The repository is hosted on GitHub or Bitbucket.

PlatformIO Library Registry Crawler will lookup for release tag named as value of version or with v prefix (you do not need to pass this v prefix to the version field).

Case 2:

version and repository fields are defined and repository does not contain tag/release with value of version.

PlatformIO Library Registry Crawler will use the latest source code from repository and link it with specified version. If repository branch is not specified, then default branch will be used. Also, if you push new commits to repository and do not update version field, the library will not be updated until you change the version.

Case 3:

version field is not defined and repository field is defined.

PlatformIO Library Registry Crawler will use the VCS revision from the latest commit as “current version”. For example, 13 (SVN) or first 10 chars of SHA digest e4564b7da4 (Git). If repository branch is not specified, then default branch will be used.

We recommend to use version field and specify the real release version and make appropriate tag in the repository. In other case, users will receive updates for library with each new commit to repository.

Example:

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

license¶

Optional | Type: String

A license of the library. You can check the full list of SPDX license IDs. Ideally you should pick one that is OSI approved.

"license": "Apache-2.0"

downloadUrl¶

Required if repository field is not defined | Type: String

It is the HTTP URL to the archived source code of library. It should end with the type of archive (.zip or .tar.gz).

Example with detached release/tag on GitHub:

"version": "1.0.0",
"downloadUrl": "https://github.com/foo/bar/archive/v1.0.0.tar.gz",
"include": "bar-1.0.0"

See more library.json Examples.

homepage¶

Optional | Type: String | Max. Length: 255

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

export¶

Optional | Type: Object

Explain PlatformIO Library Crawler which content from the repository/archive should be exported as “source code” of the library. This option is useful if need to exclude extra data (test code, docs, images, PDFs, etc). It allows one to reduce size of the final archive.

Possible options:

"include": "some/child/dir/LibrarySourceCodeHere"

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

frameworks¶

Optional | Type: String or Array

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

If the library is compatible with the all frameworks, then you can use * symbol:

"frameworks": "*"

platforms¶

Optional | Type: String or Array

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

If the library is compatible with the all platforms, then you can use * symbol:

"platforms": "*"

dependencies¶

Optional | Type: Array or Object

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

Allowed requirements for dependent library:

• name | Type: String

• version | Type: String

• authors | Type: String or Array

• frameworks | Type: String or Array

• platforms | Type: String or Array

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 platformio lib install command.

Example:

"dependencies":
[
    {
        "name": "Library-Foo",
        "authors":
        [
            "Jhon Smith",
            "Andrew Smith"
        ]
    },
    {
        "name": "Library-Bar",
        "version": "~1.2.3"
    },
    {
        "name": "lib-from-repo",
        "version": "https://github.com/user/package.git#1.2.3"
    }
]

A short definition of dependencies is allowed:

"dependencies": {
    "mylib": "1.2.3",
    "lib-from-repo": "githubuser/package"
}

See more library.json Examples.

examples¶

Optional | Type: String or Array | Glob Pattern

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

"examples": [
    "[Ee]xamples/*.c",
    "[Ee]xamples/*.cpp",
    "[Ee]xamples/*.ino",
    "[Ee]xamples/*.pde",
    "[Ee]xamples/*/*.c",
    "[Ee]xamples/*/*.cpp",
    "[Ee]xamples/*/*.ino",
    "[Ee]xamples/*/*.pde",
    "[Ee]xamples/*/*/*.c",
    "[Ee]xamples/*/*/*.cpp",
    "[Ee]xamples/*/*/*.ino",
    "[Ee]xamples/*/*/*.pde"
]

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>", "+<%s>" % join("hal", 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"