Creating Library

PlatformIO Library Manager doesn’t have any requirements to a library source code structure. The only one requirement is library’s manifest file - library.json. It can be located inside your library or in the another location where PlatformIO Library Registry Crawler will have HTTP access.

Updates to existing libraries are done every 24 hours. In case a more urgent update is required, you can post a request on PlatformIO community.

Source Code Location

There are a several ways how to share your library with the whole world (see examples).

You can hold a lot of libraries (split into separated folders) inside one of the repository/archive. In this case, you need to specify include option of export field to relative path to your library’s source code.

At GitHub

Recommended

If a library source code is located at GitHub, then you need to specify only these fields in the library.json:

PlatformIO Library Registry Crawler will populate the rest fields, like authors with an actual information from GitHub.

Example, DallasTemperature:

{
  "name": "DallasTemperature",
  "keywords": "onewire, 1-wire, bus, sensor, temperature",
  "description": "Arduino Library for Dallas Temperature ICs (DS18B20, DS18S20, DS1822, DS1820)",
  "repository":
  {
    "type": "git",
    "url": "https://github.com/milesburton/Arduino-Temperature-Control-Library.git"
  },
  "authors":
  [
    {
      "name": "Miles Burton",
      "email": "miles@mnetcs.com",
      "url": "http://www.milesburton.com",
      "maintainer": true
    },
    {
      "name": "Tim Newsome",
      "email": "nuisance@casualhacker.net"
    },
    {
      "name": "Guil Barros",
      "email": "gfbarros@bappos.com"
    },
    {
      "name": "Rob Tillaart",
      "email": "rob.tillaart@gmail.com"
    }
  ],
  "dependencies":
  {
    "name": "OneWire",
    "authors": "Paul Stoffregen",
    "frameworks": "arduino"
  },
  "version": "3.7.7",
  "frameworks": "arduino",
  "platforms": "*"
}

Under VCS (SVN/GIT)

PlatformIO Library Registry Crawler can operate with a library source code that is under VCS control. The list of required fields in the library.json will look like:

Example:

{
    "name": "XBee",
    "keywords": "xbee, protocol, radio",
    "description": "Arduino library for communicating with XBees in API mode",
    "authors":
    {
        "name": "Andrew Rapp",
        "email": "andrew.rapp@gmail.com",
        "url": "https://code.google.com/u/andrew.rapp@gmail.com/"
    },
    "repository":
    {
        "type": "git",
        "url": "https://code.google.com/p/xbee-arduino/"
    },
    "frameworks": "arduino",
    "platforms": "atmelavr"
}

Self-hosted

You can manually archive (Zip, Tar.Gz) your library source code and host it in the Internet. Then you should specify the additional fields, like version and downloadUrl. The final list of required fields in the library.json will look like:

{
    "name": "OneWire",
    "keywords": "onewire, 1-wire, bus, sensor, temperature, ibutton",
    "description": "Control devices (from Dallas Semiconductor) that use the One Wire protocol (DS18S20, DS18B20, DS2408 and etc)",
    "authors":
    {
        "name": "Paul Stoffregen",
        "url": "http://www.pjrc.com/teensy/td_libs_OneWire.html"
    },
    "version": "2.2",
    "downloadUrl": "http://www.pjrc.com/teensy/arduino_libraries/OneWire.zip",
    "export": {
        "include": "OneWire"
    },
    "frameworks": "arduino",
    "platforms": "atmelavr"
}

Register

The registration requirements:

  • A library must adhere to the library.json specification.
  • There must be public HTTP access to the library library.json file.

Now, you can register your library and allow others to install it.

Examples

Command:

$ platformio lib register http://my.example.com/library.json