Custom Development Platform

PlatformIO was developed like a tool that may build the same source code for the different development platforms via single command platformio run without any dependent software or requirements.

For this purpose PlatformIO uses own pre-configured platforms data: build scripts, toolchains, the settings for the most popular embedded boards and etc. These data are pre-built and packaged to the different packages. It allows PlatformIO to have multiple development platforms which can use the same packages(toolchains, frameworks), but have different/own build scripts, uploader and etc.

Note

If you want to change some build flags for the existing Development Platforms, you don’t need to create (or duplicate) own development platforms! Please use build_flags option.

Step-by-Step Manual

  1. Choose Packages for platform
  2. Create Manifest File platform.json
  3. Create Build Script main.py
  4. Finish with the Installation.

Packages

PlatformIO has pre-built packages for the most popular operation systems: Mac OS, Linux (+ARM) and Windows.

Name Description
framework-arduinoavr Arduino Wiring-based Framework (AVR Core, 1.6)
framework-arduinoespressif32 Arduino Wiring-based Framework (ESP32 Core)
framework-arduinoespressif8266 Arduino Wiring-based Framework (ESP8266 Core)
framework-arduinointel Arduino Wiring-based Framework (Intel ARC Core)
framework-arduinomicrochippic32 Arduino Wiring-based Framework (PIC32 Core)
framework-arduinomsp430 Arduino Wiring-based Framework (MSP430 Core)
framework-arduinonordicnrf5 Arduino Wiring-based Framework (Nordic NRF5 Core)
framework-arduinosam Arduino Wiring-based Framework (SAM Core, 1.6)
framework-arduinostm32mxchip Arduino Wiring-based Framework (ST STM32 MXChip Core)
framework-arduinoststm32 Arduino Wiring-based Framework (STM32 Core)
framework-arduinoteensy Arduino Wiring-based Framework
framework-artik-sdk ARTIK SDK is a C/C++ SDK targeting Samsung ARTIK platforms
framework-cmsis Vendor-independent hardware abstraction layer for the Cortex-M processor series
framework-energiamsp430 Energia Wiring-based Framework (MSP430 Core)
framework-energiativa Energia Wiring-based Framework (LM4F Core)
framework-esp8266-rtos-sdk ESP8266 SDK based on FreeRTOS
framework-espidf Espressif IoT Development Framework
framework-libopencm3 libOpenCM3 Framework
framework-mbed mbed Framework
framework-pumbaa Pumbaa Framework
framework-simba Simba Framework
framework-spl Standard Peripheral Library for STM32 MCUs
framework-stm32cube STM32Cube embedded software libraries
framework-wiringpi GPIO Interface library for the Raspberry Pi
ldscripts Linker Scripts
sdk-esp8266 ESP8266 SDK
tool-arduino101load Genuino101 uploader
tool-avrdude AVRDUDE
tool-bossac BOSSA CLI
tool-espotapy ESP8266 OTA utility
tool-esptool esptool-ck
tool-esptoolpy Espressif ROM Bootloader utility
tool-lm4flash Flash Programmer
tool-micronucleus Micronucleus
tool-mkspiffs Tool to build and unpack SPIFFS images
tool-mspdebug MSPDebug
tool-openocd OpenOCD
tool-pic32prog pic32prog
tool-rfdloader rfdloader
tool-scons SCons software construction tool
tool-sreccat Merging tool
tool-stlink ST-Link
tool-stm32duino STM32Duino Tools
tool-teensy Teensy Loader
toolchain-atmelavr avr-gcc
toolchain-gccarmlinuxgnueabi GCC for Linux ARM GNU EABI
toolchain-gccarmnoneeabi gcc-arm-embedded
toolchain-gcclinux32 GCC for Linux i686
toolchain-gcclinux64 GCC for Linux x86_64
toolchain-gccmingw32 MinGW
toolchain-icestorm Tools for analyzing and creating bitstream files for FPGA IceStorm
toolchain-intelarc32 GCC for Intel ARC
toolchain-iverilog Verilog simulation and synthesis tool
toolchain-microchippic32 GCC for Microchip PIC32
toolchain-timsp430 msp-gcc
toolchain-xtensa xtensa-gcc
toolchain-xtensa32 xtensa32-gcc

Manifest File platform.json

{
  "name": "myplatform",
  "title": "My Platform",
  "description": "My custom development platform",
  "url": "http://example.com",
  "homepage": "http://platformio.org/platforms/myplatform",
  "license": "Apache-2.0",
  "engines": {
    "platformio": "~3.0.0",
    "scons": ">=2.3.0,<2.6.0"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/platformio/platform-myplatform.git"
  },
  "version": "0.0.0",
  "packageRepositories": [
    "https://dl.bintray.com/platformio/dl-packages/manifest.json",
    "https://sourceforge.net/projects/platformio-storage/files/packages/manifest.json/download",
    "http://dl.platformio.org/packages/manifest.json",
    {
      "framework-%FRAMEWORK_NAME_1%": [
        {
          "url": "http://dl.example.com/packages/framework-%FRAMEWORK_NAME_1%-1.10607.0.tar.gz",
          "sha1": "adce2cd30a830d71cb6572575bf08461b7b73c07",
          "version": "1.10607.0",
          "system": "*"
        }
      ]
    }
  ],
  "frameworks": {
    "%FRAMEWORK_NAME_1%": {
      "package": "framework-%FRAMEWORK_NAME_1%",
      "script": "builder/frameworks/%FRAMEWORK_NAME_1%.py"
    },
    "%FRAMEWORK_NAME_N%": {
      "package": "framework-%FRAMEWORK_NAME_N%",
      "script": "builder/frameworks/%FRAMEWORK_NAME_N%.py"
    }
  },
  "packages": {
    "toolchain-gccarmnoneeabi": {
      "type": "toolchain",
      "version": ">=1.40803.0,<1.40805.0"
    },
    "framework-%FRAMEWORK_NAME_1%": {
      "type": "framework",
      "optional": true,
      "version": "~1.10607.0"
    },
    "framework-%FRAMEWORK_NAME_N%": {
      "type": "framework",
      "optional": true,
      "version": "~1.117.0"
    },
    "tool-direct-vcs-url": {
      "type": "uploader",
      "optional": true,
      "version": "https://github.com/user/repo.git"
    }
  }
}

Build Script main.py

Platform’s build script is based on a next-generation build tool named SCons. PlatformIO has own built-in firmware builder env.BuildProgram with the deep libraries search. Please look into a base template of main.py.

"""
    Build script for test.py
    test-builder.py
"""

from os.path import join
from SCons.Script import AlwaysBuild, Builder, Default, DefaultEnvironment

env = DefaultEnvironment()

# A full list with the available variables
# http://www.scons.org/doc/production/HTML/scons-user.html#app-variables
env.Replace(
    AR="ar",
    AS="gcc",
    CC="gcc",
    CXX="g++",
    OBJCOPY="objcopy",
    RANLIB="ranlib",

    ARFLAGS=["..."],

    ASFLAGS=["flag1", "flag2", "flagN"],
    CCFLAGS=["flag1", "flag2", "flagN"],
    CXXFLAGS=["flag1", "flag2", "flagN"],
    LINKFLAGS=["flag1", "flag2", "flagN"],

    CPPDEFINES=["DEFINE_1", "DEFINE=2", "DEFINE_N"],

    LIBS=["additional", "libs", "here"],

    UPLOADER=join("$PIOPACKAGES_DIR", "tool-bar", "uploader"),
    UPLOADCMD="$UPLOADER $SOURCES"
)

env.Append(
    BUILDERS=dict(
        ElfToBin=Builder(
            action=" ".join([
                "$OBJCOPY",
                "-O",
                "binary",
                "$SOURCES",
                "$TARGET"]),
            suffix=".bin"
        )
    )
)

# The source code of "platformio-build-tool" is here
# https://github.com/platformio/platformio-core/blob/develop/platformio/builder/tools/platformio.py

#
# Target: Build executable and linkable firmware
#
target_elf = env.BuildProgram()

#
# Target: Build the .bin file
#
target_bin = env.ElfToBin(join("$BUILD_DIR", "firmware"), target_elf)

#
# Target: Upload firmware
#
upload = env.Alias(["upload"], target_bin, "$UPLOADCMD")
AlwaysBuild(upload)

#
# Target: Define targets
#
Default(target_bin)

Installation

  1. Create platforms directory in home_dir if it doesn’t exist.
  2. Create myplatform directory in platforms
  3. Copy platform.json and builder/main.py files to myplatform directory.
  4. Search available platforms via platformio platform search command. You should see myplatform platform.
  5. Install myplatform platform via platformio platform install command.

Now, you can use myplatform for the platform option in Project Configuration File platformio.ini.

Examples

Please take a look at the source code of PlatformIO Development Platforms.