mirror of
https://github.com/platformio/platformio-core.git
synced 2025-07-30 10:07: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
|
* ``build`` data will be used by :ref:`platforms` and :ref:`frameworks` builders
|
||||||
* ``frameworks`` is the list with supported :ref:`frameworks`
|
* ``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``
|
* ``upload`` upload settings which depend on the ``platform``
|
||||||
|
|
||||||
.. code-block:: json
|
.. code-block:: json
|
||||||
|
|
||||||
{
|
{
|
||||||
"myboard": {
|
"build": {
|
||||||
"build": {},
|
"extra_flags": "-DHELLO_PLATFORMIO",
|
||||||
"frameworks": ["%LIST_WITH_SUPPORTED_FRAMEWORKS%"],
|
"f_cpu": "16000000L",
|
||||||
"name": "My test board",
|
"hwids": [
|
||||||
"platform": "%PLATFORM_TYPE_HERE%",
|
[
|
||||||
"upload": {},
|
"0x1234",
|
||||||
"url": "http://example.com",
|
"0x0013"
|
||||||
"vendor": "My Company Ltd."
|
],
|
||||||
}
|
[
|
||||||
|
"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
|
Installation
|
||||||
------------
|
------------
|
||||||
|
|
||||||
1. Create ``boards`` directory in :ref:`projectconf_pio_home_dir` if it
|
1. Create ``boards`` directory in :ref:`projectconf_pio_home_dir` if it
|
||||||
doesn't exist.
|
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
|
3. Search available boards via :ref:`cmd_boards` command. You should see
|
||||||
``myboard`` board.
|
``myboard`` board.
|
||||||
|
|
||||||
@ -68,5 +83,6 @@ Now, you can use ``myboard`` for the :ref:`projectconf_env_board` option in
|
|||||||
Examples
|
Examples
|
||||||
--------
|
--------
|
||||||
|
|
||||||
For the examples, please look into built-in ``*.json`` files with boards
|
Please take a look at the source code of
|
||||||
settings: https://github.com/platformio/platformio/tree/develop/platformio/boards.
|
`PlatformIO Development Platforms <https://github.com/platformio?query=platform->`_
|
||||||
|
and navigate to ``boards`` folder of the repository.
|
||||||
|
|||||||
@ -14,7 +14,7 @@
|
|||||||
Custom Platform
|
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`
|
for the different development platforms via single command :ref:`cmd_run`
|
||||||
without any dependent software or requirements.
|
without any dependent software or requirements.
|
||||||
|
|
||||||
@ -32,7 +32,7 @@ different/own build scripts, uploader and etc.
|
|||||||
|
|
||||||
**Step-by-Step Manual**
|
**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`
|
2. Create :ref:`platform_creating_manifest_file`
|
||||||
3. Create :ref:`platform_creating_build_script`
|
3. Create :ref:`platform_creating_build_script`
|
||||||
4. Finish with the :ref:`platform_creating_installation`.
|
4. Finish with the :ref:`platform_creating_installation`.
|
||||||
@ -184,89 +184,82 @@ Packages
|
|||||||
|
|
||||||
.. _platform_creating_manifest_file:
|
.. _platform_creating_manifest_file:
|
||||||
|
|
||||||
Manifest File
|
Manifest File ``platform.json``
|
||||||
-------------
|
-------------------------------
|
||||||
|
|
||||||
A platform manifest file is a `Python <https://www.python.org>`_ script with the
|
.. code-block:: json
|
||||||
next requirements:
|
|
||||||
|
|
||||||
1. The file should have ``.py`` extension
|
{
|
||||||
2. The **name of the file** is the **platform name** (lowercase)
|
"name": "myplatform",
|
||||||
3. The source code of this file should contain a ``class`` which describes your
|
"title": "My Platform",
|
||||||
own platform. The name of the ``class`` should start with your
|
"description": "My custom development platform",
|
||||||
**platform name** (the first letter should be capitalized) + ``Platform``
|
"url": "http://example.com",
|
||||||
ending. This ``class`` should be derived from *PlatformIO* ``BasePlatform``
|
"homepage": "http://platformio.org/platforms/myplatform",
|
||||||
class.
|
"license": {
|
||||||
|
"type": "Apache-2.0",
|
||||||
.. warning::
|
"url": "http://opensource.org/licenses/apache2.0.php"
|
||||||
If you are new to *Python* language, please read:
|
},
|
||||||
|
"engines": {
|
||||||
* `Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008>`_.
|
"platformio": "~3.0.0",
|
||||||
* A hash sign (#) that is not inside a string literal begins a comment.
|
"scons": ">=2.3.0,<2.6.0"
|
||||||
All characters after the # and up to the physical line end are part
|
},
|
||||||
of the comment and the *Python* interpreter ignores them.
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
Example of the **test** platform (``test.py``):
|
"url": "https://github.com/platformio/platform-myplatform.git"
|
||||||
|
},
|
||||||
.. code-block:: python
|
"version": "0.0.0",
|
||||||
|
"packageRepositories": [
|
||||||
import os
|
"https://dl.bintray.com/platformio/dl-packages/manifest.json",
|
||||||
|
"https://sourceforge.net/projects/platformio-storage/files/packages/manifest.json/download",
|
||||||
from platformio.platforms.base import BasePlatform
|
"http://dl.platformio.org/packages/manifest.json",
|
||||||
|
{
|
||||||
class TestPlatform(BasePlatform):
|
"framework-%FRAMEWORK_NAME_1%": [
|
||||||
# This is a description of your platform.
|
{
|
||||||
# Platformio uses it for the `platformio search / list` commands
|
"url": "http://dl.example.com/packages/framework-%FRAMEWORK_NAME_1%-1.10607.0.tar.gz",
|
||||||
"""
|
"sha1": "adce2cd30a830d71cb6572575bf08461b7b73c07",
|
||||||
My Test platform - test.py
|
"version": "1.10607.0",
|
||||||
"""
|
"system": "*"
|
||||||
|
|
||||||
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
|
|
||||||
}
|
}
|
||||||
|
]
|
||||||
}
|
}
|
||||||
|
],
|
||||||
def get_build_script(self):
|
"frameworks": {
|
||||||
""" Returns a path to build script """
|
"%FRAMEWORK_NAME_1%": {
|
||||||
|
"package": "framework-%FRAMEWORK_NAME_1%",
|
||||||
# You can return static path
|
"script": "builder/frameworks/%FRAMEWORK_NAME_1%.py"
|
||||||
#return "/path/to/test-builder.py"
|
},
|
||||||
|
"%FRAMEWORK_NAME_N%": {
|
||||||
# or detect dynamically if `test-builder.py` is located in the same
|
"package": "framework-%FRAMEWORK_NAME_N%",
|
||||||
# folder with `test.py`
|
"script": "builder/frameworks/%FRAMEWORK_NAME_N%.py"
|
||||||
return os.path.join(
|
}
|
||||||
os.path.dirname(os.path.realpath(__file__)),
|
},
|
||||||
"test-builder.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:
|
.. _platform_creating_build_script:
|
||||||
|
|
||||||
Build Script
|
Build Script ``main.py``
|
||||||
------------
|
------------------------
|
||||||
|
|
||||||
Platform's build script is based on a next-generation build tool named
|
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
|
`SCons <http://www.scons.org>`_. PlatformIO has own built-in firmware builder
|
||||||
``env.BuildProgram`` with the nested libraries search. Please look into a
|
``env.BuildProgram`` with the deep libraries search. Please look into a
|
||||||
base template of ``test-builder.py``.
|
base template of ``main.py``.
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
@ -344,15 +337,6 @@ base template of ``test-builder.py``.
|
|||||||
Default(target_bin)
|
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:
|
.. _platform_creating_installation:
|
||||||
|
|
||||||
Installation
|
Installation
|
||||||
@ -360,126 +344,17 @@ Installation
|
|||||||
|
|
||||||
1. Create ``platforms`` directory in :ref:`projectconf_pio_home_dir` if it
|
1. Create ``platforms`` directory in :ref:`projectconf_pio_home_dir` if it
|
||||||
doesn't exist.
|
doesn't exist.
|
||||||
2. Copy ``test.py`` and ``test-builder.py`` files to ``platforms`` directory.
|
2. Create ``myplatform`` directory in ``platforms``
|
||||||
3. Search available platforms via :ref:`cmd_platform_search` command. You should see
|
3. Copy ``platform.json`` and ``builder/main.py`` files to ``myplatform`` directory.
|
||||||
``test`` platform.
|
4. Search available platforms via :ref:`cmd_platform_search` command. You
|
||||||
4. Install ``test`` platform via :ref:`cmd_platform_install` command.
|
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
|
Now, you can use ``myplatform`` for the :ref:`projectconf_env_platform`
|
||||||
:ref:`projectconf`.
|
option in :ref:`projectconf`.
|
||||||
|
|
||||||
Example
|
Examples
|
||||||
-------
|
--------
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
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