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

Choose Packages for platform
Create Manifest File platform.json
Create Build Script main.py
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-nonos-sdk	ESP8266 Non-OS SDK
framework-esp8266-rtos-sdk	ESP8266 SDK based on FreeRTOS
framework-espidf	Espressif IoT Development Framework
framework-freedom-e-sdk	Open Source Software for Developing on the SiFive Freedom E Platform
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-tizenrt	TizenRT RTOS with library
framework-wiringpi	GPIO Interface library for the Raspberry Pi
ldscripts	Linker Scripts
sdk-esp8266	ESP8266 SDK
tool-arduino101load	Genuino101 uploader
tool-artik-openocd	OpenOCD for ARTIK
tool-avrdude	AVRDUDE
tool-bossac	BOSSA CLI
tool-espotapy	ESP8266 OTA utility
tool-esptool	esptool-ck
tool-esptoolpy	ESP8266 and ESP32 serial bootloader utility
tool-lm4flash	Flash Programmer
tool-micronucleus	Micronucleus
tool-mkspiffs	Tool to build and unpack SPIFFS images
tool-mspdebug	MSPDebug
tool-nrfjprog	nRF5x command line tool
tool-openocd	OpenOCD
tool-openocd-esp32	OpenOCD for Espressif 32
tool-pic32prog	pic32prog
tool-pyocd	Open source python library for programming and debugging ARM Cortex-M microcontrollers using CMSIS-DAP
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-riscv	GNU toolchain for RISC-V, including GCC
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": "https://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 ¶

Create platforms directory in home_dir if it doesn’t exist.
Create myplatform directory in platforms
Copy platform.json and builder/main.py files to myplatform directory.
Search available platforms via platformio platform search command. You should see myplatform platform.
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.

Custom Development Platform¶

Packages¶

Manifest File platform.json¶

Build Script main.py¶

Installation¶

Examples¶

Custom Development Platform ¶

Packages ¶

Manifest File `platform.json`¶

Build Script `main.py`¶

Installation ¶

Examples ¶