mirror of
https://github.com/platformio/platformio-core.git
synced 2025-07-29 17:47:14 +02:00
Update documentation for the new decentralised development platforms // Resolve #479
This commit is contained in:
Ivan Kravets
@ -35,29 +35,44 @@ The key fields:
|
||||
|
||||
* ``build`` data will be used by :ref:`platforms` and :ref:`frameworks` builders
|
||||
* ``frameworks`` is the list with supported :ref:`frameworks`
|
||||
* ``platform`` main type of :ref:`platforms`
|
||||
* ``platform`` name of :ref:`platforms`
|
||||
* ``upload`` upload settings which depend on the ``platform``
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"myboard": {
|
||||
"build": {},
|
||||
"frameworks": ["%LIST_WITH_SUPPORTED_FRAMEWORKS%"],
|
||||
"name": "My test board",
|
||||
"platform": "%PLATFORM_TYPE_HERE%",
|
||||
"upload": {},
|
||||
"url": "http://example.com",
|
||||
"vendor": "My Company Ltd."
|
||||
}
|
||||
"build": {
|
||||
"extra_flags": "-DHELLO_PLATFORMIO",
|
||||
"f_cpu": "16000000L",
|
||||
"hwids": [
|
||||
[
|
||||
"0x1234",
|
||||
"0x0013"
|
||||
],
|
||||
[
|
||||
"0x4567",
|
||||
"0x0013"
|
||||
]
|
||||
],
|
||||
"mcu": "%MCU_TYPE_HERE%"
|
||||
},
|
||||
"frameworks": ["%LIST_WITH_SUPPORTED_FRAMEWORKS%"],
|
||||
"name": "My Test Board",
|
||||
"upload": {
|
||||
"maximum_ram_size": 2048,
|
||||
"maximum_size": 32256
|
||||
},
|
||||
"url": "http://example.com",
|
||||
"vendor": "MyCompany"
|
||||
}
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
1. Create ``boards`` directory in :ref:`projectconf_pio_home_dir` if it
|
||||
doesn't exist.
|
||||
2. Create ``my_own_boards.json`` file and put to ``boards`` directory.
|
||||
2. Create ``myboard.json`` file and put to ``boards`` directory.
|
||||
3. Search available boards via :ref:`cmd_boards` command. You should see
|
||||
``myboard`` board.
|
||||
|
||||
@ -68,5 +83,6 @@ Now, you can use ``myboard`` for the :ref:`projectconf_env_board` option in
|
||||
Examples
|
||||
--------
|
||||
|
||||
For the examples, please look into built-in ``*.json`` files with boards
|
||||
settings: https://github.com/platformio/platformio/tree/develop/platformio/boards.
|
||||
Please take a look at the source code of
|
||||
`PlatformIO Development Platforms <https://github.com/platformio?query=platform->`_
|
||||
and navigate to ``boards`` folder of the repository.
|
||||
|
||||
@ -14,7 +14,7 @@
|
||||
Custom Platform
|
||||
===============
|
||||
|
||||
*PlatformIO* was developed like a tool which would build the same source code
|
||||
*PlatformIO* was developed like a tool that may build the same source code
|
||||
for the different development platforms via single command :ref:`cmd_run`
|
||||
without any dependent software or requirements.
|
||||
|
||||
@ -32,7 +32,7 @@ different/own build scripts, uploader and etc.
|
||||
|
||||
**Step-by-Step Manual**
|
||||
|
||||
1. Chose :ref:`platform_creating_packages` for platform
|
||||
1. Choose :ref:`platform_creating_packages` for platform
|
||||
2. Create :ref:`platform_creating_manifest_file`
|
||||
3. Create :ref:`platform_creating_build_script`
|
||||
4. Finish with the :ref:`platform_creating_installation`.
|
||||
@ -184,89 +184,82 @@ Packages
|
||||
|
||||
.. _platform_creating_manifest_file:
|
||||
|
||||
Manifest File
|
||||
-------------
|
||||
Manifest File ``platform.json``
|
||||
-------------------------------
|
||||
|
||||
A platform manifest file is a `Python <https://www.python.org>`_ script with the
|
||||
next requirements:
|
||||
.. code-block:: json
|
||||
|
||||
1. The file should have ``.py`` extension
|
||||
2. The **name of the file** is the **platform name** (lowercase)
|
||||
3. The source code of this file should contain a ``class`` which describes your
|
||||
own platform. The name of the ``class`` should start with your
|
||||
**platform name** (the first letter should be capitalized) + ``Platform``
|
||||
ending. This ``class`` should be derived from *PlatformIO* ``BasePlatform``
|
||||
class.
|
||||
|
||||
.. warning::
|
||||
If you are new to *Python* language, please read:
|
||||
|
||||
* `Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008>`_.
|
||||
* A hash sign (#) that is not inside a string literal begins a comment.
|
||||
All characters after the # and up to the physical line end are part
|
||||
of the comment and the *Python* interpreter ignores them.
|
||||
|
||||
Example of the **test** platform (``test.py``):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import os
|
||||
|
||||
from platformio.platforms.base import BasePlatform
|
||||
|
||||
class TestPlatform(BasePlatform):
|
||||
# This is a description of your platform.
|
||||
# Platformio uses it for the `platformio search / list` commands
|
||||
"""
|
||||
My Test platform - test.py
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
"toolchain-foo": {
|
||||
|
||||
# alias is used for quick access to package.
|
||||
# For example,
|
||||
# `> platformio install test --without-package=toolchain`
|
||||
"alias": "toolchain",
|
||||
|
||||
# Flag which allows PlatformIO to install this package by
|
||||
# default via `> platformio install test` command
|
||||
"default": True
|
||||
},
|
||||
|
||||
"tool-bar": {
|
||||
"alias": "uploader",
|
||||
"default": True
|
||||
},
|
||||
|
||||
"framework-baz": {
|
||||
"default": True
|
||||
{
|
||||
"name": "myplatform",
|
||||
"title": "My Platform",
|
||||
"description": "My custom development platform",
|
||||
"url": "http://example.com",
|
||||
"homepage": "http://platformio.org/platforms/myplatform",
|
||||
"license": {
|
||||
"type": "Apache-2.0",
|
||||
"url": "http://opensource.org/licenses/apache2.0.php"
|
||||
},
|
||||
"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": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
def get_build_script(self):
|
||||
""" Returns a path to build script """
|
||||
|
||||
# You can return static path
|
||||
#return "/path/to/test-builder.py"
|
||||
|
||||
# or detect dynamically if `test-builder.py` is located in the same
|
||||
# folder with `test.py`
|
||||
return os.path.join(
|
||||
os.path.dirname(os.path.realpath(__file__)),
|
||||
"test-builder.py"
|
||||
)
|
||||
],
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.. _platform_creating_build_script:
|
||||
|
||||
Build Script
|
||||
------------
|
||||
Build Script ``main.py``
|
||||
------------------------
|
||||
|
||||
Platform's build script is based on a next-generation build tool named
|
||||
`SCons <http://www.scons.org>`_. PlatformIO has own built-in firmware builder
|
||||
``env.BuildProgram`` with the nested libraries search. Please look into a
|
||||
base template of ``test-builder.py``.
|
||||
``env.BuildProgram`` with the deep libraries search. Please look into a
|
||||
base template of ``main.py``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -344,15 +337,6 @@ base template of ``test-builder.py``.
|
||||
Default(target_bin)
|
||||
|
||||
|
||||
Please look into the examples with built-in scripts for the popular
|
||||
platforms:
|
||||
|
||||
* `baseavr.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/baseavr.py>`_
|
||||
* `basearm.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/basearm.py>`_
|
||||
* `atmelavr.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/atmelavr.py>`_
|
||||
* `timsp430.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/timsp430.py>`_
|
||||
* `ststm32.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/ststm32.py>`_
|
||||
|
||||
.. _platform_creating_installation:
|
||||
|
||||
Installation
|
||||
@ -360,126 +344,17 @@ Installation
|
||||
|
||||
1. Create ``platforms`` directory in :ref:`projectconf_pio_home_dir` if it
|
||||
doesn't exist.
|
||||
2. Copy ``test.py`` and ``test-builder.py`` files to ``platforms`` directory.
|
||||
3. Search available platforms via :ref:`cmd_platform_search` command. You should see
|
||||
``test`` platform.
|
||||
4. Install ``test`` platform via :ref:`cmd_platform_install` command.
|
||||
2. Create ``myplatform`` directory in ``platforms``
|
||||
3. Copy ``platform.json`` and ``builder/main.py`` files to ``myplatform`` directory.
|
||||
4. Search available platforms via :ref:`cmd_platform_search` command. You
|
||||
should see ``myplatform`` platform.
|
||||
5. Install ``myplatform`` platform via :ref:`cmd_platform_install` command.
|
||||
|
||||
Now, you can use ``test`` for the :ref:`projectconf_env_platform` option in
|
||||
:ref:`projectconf`.
|
||||
Now, you can use ``myplatform`` for the :ref:`projectconf_env_platform`
|
||||
option in :ref:`projectconf`.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
Let's use the real example which was requested by our user in `issue 175 <https://github.com/platformio/platformio/issues/175>`_. Need to add support for uploading firmware using GDB to
|
||||
:ref:`platform_ststm32`.
|
||||
|
||||
First of all, need to create new folder ``platforms`` in :ref:`projectconf_pio_home_dir`
|
||||
and copy there two files:
|
||||
|
||||
1. Platform manifest file ``ststm32gdb.py`` with the next content:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import os
|
||||
|
||||
from platformio.platforms.ststm32 import Ststm32Platform
|
||||
|
||||
|
||||
class Ststm32gdbPlatform(Ststm32Platform):
|
||||
|
||||
"""
|
||||
ST STM32 using GDB as uploader
|
||||
|
||||
http://www.st.com/web/en/catalog/mmc/FM141/SC1169?sc=stm32
|
||||
"""
|
||||
|
||||
def get_build_script(self):
|
||||
|
||||
return os.path.join(
|
||||
os.path.dirname(os.path.realpath(__file__)),
|
||||
"ststm32gdb-builder.py"
|
||||
)
|
||||
|
||||
2. Build script file ``ststm32gdb-builder.py`` with the next content:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
"""
|
||||
Builder for ST STM32 Series ARM microcontrollers with GDB upload.
|
||||
"""
|
||||
|
||||
from os.path import join
|
||||
|
||||
from SCons.Script import (COMMAND_LINE_TARGETS, AlwaysBuild, Default,
|
||||
DefaultEnvironment, SConscript)
|
||||
|
||||
|
||||
env = DefaultEnvironment()
|
||||
|
||||
SConscript(env.subst(join("$PIOBUILDER_DIR", "scripts", "basearm.py")))
|
||||
|
||||
env.Replace(
|
||||
UPLOADER=join(
|
||||
"$PIOPACKAGES_DIR", "toolchain-gccarmnoneeabi",
|
||||
"bin", "arm-none-eabi-gdb"
|
||||
),
|
||||
UPLOADERFLAGS=[
|
||||
join("$BUILD_DIR", "firmware.elf"),
|
||||
"-batch",
|
||||
"-x", join("$PROJECT_DIR", "upload.gdb")
|
||||
],
|
||||
|
||||
UPLOADCMD="$UPLOADER $UPLOADERFLAGS"
|
||||
)
|
||||
|
||||
env.Append(
|
||||
CPPDEFINES=[
|
||||
"${BOARD_OPTIONS['build']['variant'].upper()}"
|
||||
],
|
||||
|
||||
LINKFLAGS=[
|
||||
"-nostartfiles",
|
||||
"-nostdlib"
|
||||
]
|
||||
)
|
||||
|
||||
#
|
||||
# Target: Build executable and linkable firmware
|
||||
#
|
||||
|
||||
target_elf = env.BuildProgram()
|
||||
|
||||
#
|
||||
# Target: Build the .bin file
|
||||
#
|
||||
|
||||
if "uploadlazy" in COMMAND_LINE_TARGETS:
|
||||
target_firm = join("$BUILD_DIR", "firmware.bin")
|
||||
else:
|
||||
target_firm = env.ElfToBin(join("$BUILD_DIR", "firmware"), target_elf)
|
||||
|
||||
#
|
||||
# Target: Print binary size
|
||||
#
|
||||
|
||||
target_size = env.Alias("size", target_elf, "$SIZEPRINTCMD")
|
||||
AlwaysBuild(target_size)
|
||||
|
||||
#
|
||||
# Target: Upload by default .bin file
|
||||
#
|
||||
|
||||
upload = env.Alias(
|
||||
["upload", "uploadlazy"], target_firm, "$UPLOADCMD")
|
||||
AlwaysBuild(upload)
|
||||
|
||||
#
|
||||
# Target: Define targets
|
||||
#
|
||||
|
||||
Default([target_firm, target_size])
|
||||
|
||||
Now, we should see ``ststm32gdb`` platform using :ref:`cmd_platform_search` command output
|
||||
and can install it via :ref:`platformio platform install ststm32gdb <cmd_platform_install>` command.
|
||||
Examples
|
||||
--------
|
||||
|
||||
Please take a look at the source code of
|
||||
`PlatformIO Development Platforms <https://github.com/platformio?query=platform->`_.
|
||||
|
||||
Reference in New Issue
Block a user