mirror of
https://github.com/platformio/platformio-core.git
synced 2025-07-30 01:57:13 +02:00
Add script for dynamically generating RST documents. Update platforms and frameworks documentation // Resolve 114
This commit is contained in:
Valeriy Koval
@ -2,7 +2,11 @@
|
||||
# See LICENSE for details.
|
||||
|
||||
"""
|
||||
Build script for Arduino Framework (based on Wiring).
|
||||
Arduino Framework allows writing cross-platform software to control
|
||||
devices attached to a wide range of Arduino boards to create all
|
||||
kinds of creative coding, interactive objects, spaces or physical experiences.
|
||||
|
||||
http://arduino.cc/en/Reference/HomePage
|
||||
"""
|
||||
|
||||
from os import listdir, walk
|
||||
@ -146,7 +150,6 @@ if BOARD_BUILDOPTS.get("core", None) == "teensy":
|
||||
# Target: Build Core Library
|
||||
#
|
||||
|
||||
|
||||
libs = []
|
||||
|
||||
if "variant" in BOARD_BUILDOPTS:
|
||||
|
||||
@ -2,7 +2,15 @@
|
||||
# See LICENSE for details.
|
||||
|
||||
"""
|
||||
Build script for CMSIS Framework.
|
||||
The ARM Cortex Microcontroller Software Interface Standard (CMSIS) is a
|
||||
vendor-independent hardware abstraction layer for the Cortex-M processor
|
||||
series and specifies debugger interfaces. The CMSIS enables consistent and
|
||||
simple software interfaces to the processor for interface peripherals,
|
||||
real-time operating systems, and middleware. It simplifies software
|
||||
re-use, reducing the learning curve for new microcontroller developers
|
||||
and cutting the time-to-market for devices.
|
||||
|
||||
http://www.arm.com/products/processors/cortex-m/cortex-microcontroller-software-interface-standard.php
|
||||
"""
|
||||
|
||||
from os.path import join
|
||||
|
||||
@ -2,7 +2,13 @@
|
||||
# See LICENSE for details.
|
||||
|
||||
"""
|
||||
Build script for Energia Framework (based on Wiring).
|
||||
Energia framework enables pretty much anyone to start easily creating
|
||||
microcontroller-based projects and applications. Its easy-to-use libraries
|
||||
and functions provide developers of all experience levels to start
|
||||
blinking LEDs, buzzing buzzers and sensing sensors more quickly than ever
|
||||
before.
|
||||
|
||||
http://energia.nu/reference/
|
||||
"""
|
||||
|
||||
from os.path import join
|
||||
|
||||
@ -2,7 +2,15 @@
|
||||
# See LICENSE for details.
|
||||
|
||||
"""
|
||||
Build script for Mbed Framework
|
||||
The mbed framework The mbed SDK has been designed to provide enough
|
||||
hardware abstraction to be intuitive and concise, yet powerful enough to
|
||||
build complex projects. It is built on the low-level ARM CMSIS APIs,
|
||||
allowing you to code down to the metal if needed. In addition to RTOS,
|
||||
USB and Networking libraries, a cookbook of hundreds of reusable
|
||||
peripheral and module libraries have been built on top of the SDK by
|
||||
the mbed Developer Community.
|
||||
|
||||
http://mbed.org/
|
||||
"""
|
||||
|
||||
import xml.etree.ElementTree as ElementTree
|
||||
@ -123,17 +131,17 @@ for lib_path in eixdata.get("CPPPATH"):
|
||||
|
||||
|
||||
#
|
||||
# Target: Build MBED Library
|
||||
# Target: Build mbed Library
|
||||
#
|
||||
|
||||
libs = [l for l in eixdata.get("STDLIBS", []) if l not in env.get("LIBS")]
|
||||
|
||||
env.VariantDir(
|
||||
join("$BUILD_DIR", "FrameworkMBED"),
|
||||
join("$BUILD_DIR", "FrameworkMbed"),
|
||||
join("$PLATFORMFW_DIR", "core")
|
||||
)
|
||||
libs.append(env.Library(
|
||||
join("$BUILD_DIR", "FrameworkMBED"),
|
||||
join("$BUILD_DIR", "FrameworkMbed"),
|
||||
get_source_files(eixdata.get("FILES", []))
|
||||
))
|
||||
|
||||
|
||||
@ -2,7 +2,12 @@
|
||||
# See LICENSE for details.
|
||||
|
||||
"""
|
||||
Build script for OpenCM3 Framework.
|
||||
The libopencm3 framework aims to create a free/libre/open-source
|
||||
firmware library for various ARM Cortex-M0(+)/M3/M4 microcontrollers,
|
||||
including ST STM32, Ti Tiva and Stellaris, NXP LPC 11xx, 13xx, 15xx,
|
||||
17xx parts, Atmel SAM3, Energy Micro EFM32 and others.
|
||||
|
||||
http://www.libopencm3.org/wiki/Main_Page
|
||||
"""
|
||||
|
||||
import re
|
||||
|
||||
@ -2,7 +2,12 @@
|
||||
# See LICENSE for details.
|
||||
|
||||
"""
|
||||
Build script for SPL Framework
|
||||
The ST Standard Peripheral Library provides a set of functions for
|
||||
handling the peripherals on the STM32 Cortex-M3 family.
|
||||
The idea is to save the user (the new user, in particular) having to deal
|
||||
directly with the registers.
|
||||
|
||||
http://www.st.com/web/en/catalog/tools/FM147/CL1794/SC961/SS1743?sc=stm32embeddedsoftware
|
||||
"""
|
||||
|
||||
from os.path import join
|
||||
|
||||
@ -16,7 +16,7 @@ def UploadToDisk(target, source, env): # pylint: disable=W0613,W0621
|
||||
env.AutodetectUploadPort()
|
||||
copyfile(join(env.subst("$BUILD_DIR"), "firmware.bin"),
|
||||
join(env.subst("$UPLOAD_PORT"), "firmware.bin"))
|
||||
print ("Firmware has been successfully uploaded.\n" +
|
||||
print ("Firmware has been successfully uploaded.\n"
|
||||
"Please restart your board.")
|
||||
|
||||
env = DefaultEnvironment()
|
||||
|
||||
@ -44,6 +44,11 @@ class UnknownBoard(PlatformioException):
|
||||
MESSAGE = "Unknown board type '%s'"
|
||||
|
||||
|
||||
class UnknownFramework(PlatformioException):
|
||||
|
||||
MESSAGE = "Unknown framework '%s'"
|
||||
|
||||
|
||||
class UnknownPackage(PlatformioException):
|
||||
|
||||
MESSAGE = "Detected unknown package '%s'"
|
||||
|
||||
@ -8,8 +8,13 @@ from platformio.util import get_boards
|
||||
class AtmelavrPlatform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for Atmel AVR microcontrollers
|
||||
(with Arduino Framework)
|
||||
Atmel AVR 8- and 32-bit MCUs deliver a unique combination of
|
||||
performance, power efficiency and design flexibility. Optimized to
|
||||
speed time to market-and easily adapt to new ones-they are based on
|
||||
the industrys most code-efficient architecture for C and assembly
|
||||
programming.
|
||||
|
||||
http://www.atmel.com/products/microcontrollers/avr/default.aspx
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -7,8 +7,11 @@ from platformio.platforms.base import BasePlatform
|
||||
class AtmelsamPlatform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for Atmel SAM microcontrollers
|
||||
(with Arduino Framework)
|
||||
Atmel | SMART offers Flash- based ARM products based on the ARM
|
||||
Cortex-M0+, Cortex-M3 and Cortex-M4 architectures, ranging from 8KB
|
||||
to 2MB of Flash including a rich peripheral and feature mix.
|
||||
|
||||
http://www.atmel.com/products/microcontrollers/arm/default.aspx
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -12,6 +12,86 @@ from platformio import exception, util
|
||||
from platformio.app import get_state_item, set_state_item
|
||||
from platformio.pkgmanager import PackageManager
|
||||
|
||||
PLATFORM_PACKAGES = {
|
||||
|
||||
"framework-arduinoavr": [
|
||||
("Arduino Wiring-based Framework (AVR Core, 1.6)",
|
||||
"http://arduino.cc/en/Reference/HomePage")
|
||||
],
|
||||
"framework-arduinosam": [
|
||||
("Arduino Wiring-based Framework (SAM Core, 1.6)",
|
||||
"http://arduino.cc/en/Reference/HomePage")
|
||||
],
|
||||
"framework-arduinoteensy": [
|
||||
("Arduino Wiring-based Framework",
|
||||
"http://arduino.cc/en/Reference/HomePage")
|
||||
],
|
||||
"framework-energiamsp430": [
|
||||
("Energia Wiring-based Framework (MSP430 Core)",
|
||||
"http://energia.nu/reference/")
|
||||
],
|
||||
"framework-energiativa": [
|
||||
("Energia Wiring-based Framework (LM4F Core)",
|
||||
"http://energia.nu/reference/")
|
||||
],
|
||||
"framework-cmsis": [
|
||||
("Vendor-independent hardware abstraction layer for the Cortex-M "
|
||||
"processor series",
|
||||
"http://www.arm.com/products/processors/"
|
||||
"cortex-m/cortex-microcontroller-software-interface-standard.php")
|
||||
],
|
||||
"framework-spl": [
|
||||
("Standard Peripheral Library for STM32 MCUs",
|
||||
"http://www.st.com"
|
||||
"/web/catalog/tools/FM147/CL1794/SC961/SS1743/PF257890")
|
||||
],
|
||||
"framework-opencm3": [
|
||||
("libOpenCM3 Framework", "http://www.libopencm3.org/")
|
||||
],
|
||||
"framework-mbed": [
|
||||
("mbed Framework", "http://mbed.org")
|
||||
],
|
||||
"ldscripts": [
|
||||
("Linker Scripts",
|
||||
"https://sourceware.org/binutils/docs/ld/Scripts.html")
|
||||
],
|
||||
"toolchain-atmelavr": [
|
||||
("avr-gcc", "https://gcc.gnu.org/wiki/avr-gcc"),
|
||||
("GDB", "http://www.gnu.org/software/gdb/"),
|
||||
("AVaRICE", "http://avarice.sourceforge.net/"),
|
||||
("SimulAVR", "http://www.nongnu.org/simulavr/")
|
||||
],
|
||||
"toolchain-gccarmnoneeabi": [
|
||||
("gcc-arm-embedded", "https://launchpad.net/gcc-arm-embedded"),
|
||||
("GDB", "http://www.gnu.org/software/gdb/")
|
||||
],
|
||||
"toolchain-timsp430": [
|
||||
("msp-gcc", "http://sourceforge.net/projects/mspgcc/"),
|
||||
("GDB", "http://www.gnu.org/software/gdb/")
|
||||
],
|
||||
"tool-avrdude": [
|
||||
("AVRDUDE", "http://www.nongnu.org/avrdude/")
|
||||
],
|
||||
"tool-micronucleus": [
|
||||
("Micronucleus", "https://github.com/micronucleus/micronucleus")
|
||||
],
|
||||
"tool-bossac": [
|
||||
("BOSSA CLI", "https://sourceforge.net/projects/b-o-s-s-a/")
|
||||
],
|
||||
"tool-stlink": [
|
||||
("ST-Link", "https://github.com/texane/stlink")
|
||||
],
|
||||
"tool-teensy": [
|
||||
("Teensy Loader", "https://www.pjrc.com/teensy/loader.html")
|
||||
],
|
||||
"tool-lm4flash": [
|
||||
("Flash Programmer", "http://www.ti.com/tool/lmflashprogrammer")
|
||||
],
|
||||
"tool-mspdebug": [
|
||||
("MSPDebug", "http://mspdebug.sourceforge.net/")
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
class PlatformFactory(object):
|
||||
|
||||
|
||||
@ -7,7 +7,12 @@ from platformio.platforms.base import BasePlatform
|
||||
class FreescalekinetisPlatform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for Freescale Kinetis series ARM microcontrollers
|
||||
Freescale Kinetis Microcontrollers is family of multiple hardware- and
|
||||
software-compatible ARM Cortex-M0+, Cortex-M4 and Cortex-M7-based MCU
|
||||
series. Kinetis MCUs offer exceptional low-power performance,
|
||||
scalability and feature integration.
|
||||
|
||||
http://www.freescale.com/webapp/sps/site/homepage.jsp?code=KINETIS
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -7,7 +7,14 @@ from platformio.platforms.base import BasePlatform
|
||||
class Nordicnrf51Platform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for Nordic nRF51 series ARM microcontrollers
|
||||
The Nordic nRF51 Series is a family of highly flexible,
|
||||
multi-protocol, system-on-chip (SoC) devices for ultra-low power
|
||||
wireless applications. nRF51 Series devices support a range of
|
||||
protocol stacks including Bluetooth Smart (previously called
|
||||
Bluetooth low energy), ANT and proprietary 2.4GHz protocols such as
|
||||
Gazell.
|
||||
|
||||
https://www.nordicsemi.com/eng/Products/nRF51-Series-SoC
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -7,7 +7,14 @@ from platformio.platforms.base import BasePlatform
|
||||
class NxplpcPlatform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for NXP LPC series ARM microcontrollers
|
||||
The NXP LPC is a family of 32-bit microcontroller integrated circuits
|
||||
by NXP Semiconductors. The LPC chips are grouped into related series
|
||||
that are based around the same 32-bit ARM processor core, such as the
|
||||
Cortex-M4F, Cortex-M3, Cortex-M0+, or Cortex-M0. Internally, each
|
||||
microcontroller consists of the processor core, static RAM memory,
|
||||
flash memory, debugging interface, and various peripherals.
|
||||
|
||||
http://www.nxp.com/products/microcontrollers/
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -7,7 +7,14 @@ from platformio.platforms.base import BasePlatform
|
||||
class Ststm32Platform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for ST STM32 ARM microcontrollers
|
||||
The STM32 family of 32-bit Flash MCUs based on the ARM Cortex-M
|
||||
processor is designed to offer new degrees of freedom to MCU users.
|
||||
It offers a 32-bit product range that combines very high performance,
|
||||
real-time capabilities, digital signal processing, and low-power,
|
||||
low-voltage operation, while maintaining full integration and ease of
|
||||
development.
|
||||
|
||||
http://www.st.com/web/en/catalog/mmc/FM141/SC1169?sc=stm32
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -8,8 +8,13 @@ from platformio.util import get_boards
|
||||
class TeensyPlatform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for Teensy boards
|
||||
(with Arduino Framework)
|
||||
Teensy is a complete USB-based microcontroller development system, in
|
||||
a very small footprint, capable of implementing many types of projects.
|
||||
All programming is done via the USB port. No special programmer is
|
||||
needed, only a standard "Mini-B" USB cable and a PC or Macintosh with
|
||||
a USB port.
|
||||
|
||||
https://www.pjrc.com/teensy
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -5,9 +5,14 @@ from platformio.platforms.base import BasePlatform
|
||||
|
||||
|
||||
class Timsp430Platform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for TI MSP430 microcontrollers
|
||||
(with Energia Framework)
|
||||
MSP430 microcontrollers (MCUs) from Texas Instruments (TI)
|
||||
are 16-bit, RISC-based, mixed-signal processors designed for ultra-low
|
||||
power. These MCUs offer the lowest power consumption and the perfect
|
||||
mix of integrated peripherals for thousands of applications.
|
||||
|
||||
http://www.ti.com/lsds/ti/microcontrollers_16-bit_32-bit/msp/overview.page
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
@ -7,8 +7,12 @@ from platformio.platforms.base import BasePlatform
|
||||
class TitivaPlatform(BasePlatform):
|
||||
|
||||
"""
|
||||
An embedded platform for TI TIVA C ARM microcontrollers
|
||||
(with Energia and OpenCM3 Frameworks)
|
||||
Texas Instruments TM4C12x MCUs offer the industrys most popular
|
||||
ARM Cortex-M4 core with scalable memory and package options, unparalleled
|
||||
connectivity peripherals, advanced application functions, industry-leading
|
||||
analog integration, and extensive software solutions.
|
||||
|
||||
http://www.ti.com/lsds/ti/microcontrollers_16-bit_32-bit/c2000_performance/control_automation/tm4c12x/overview.page
|
||||
"""
|
||||
|
||||
PACKAGES = {
|
||||
|
||||
194
scripts/docspregen.py
Normal file
194
scripts/docspregen.py
Normal file
@ -0,0 +1,194 @@
|
||||
# Copyright (C) Ivan Kravets <me@ikravets.com>
|
||||
# See LICENSE for details.
|
||||
|
||||
from os.path import dirname, join, realpath
|
||||
from sys import path
|
||||
from sys import exit as sys_exit
|
||||
from math import ceil
|
||||
path.append("..")
|
||||
from platformio import util
|
||||
from platformio.platforms.base import PLATFORM_PACKAGES, PlatformFactory
|
||||
|
||||
|
||||
def generate_boards(boards):
|
||||
|
||||
def _round_memory_size(size):
|
||||
size = ceil(size)
|
||||
for b in (64, 32, 16, 8, 4, 2, 1):
|
||||
if b < size:
|
||||
return int(ceil(size / b) * b)
|
||||
assert NotImplemented()
|
||||
|
||||
lines = []
|
||||
|
||||
lines.append("""
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Type ``board``
|
||||
- Name
|
||||
- Microcontroller
|
||||
- Frequency
|
||||
- Flash
|
||||
- RAM""")
|
||||
|
||||
for board in sorted(boards):
|
||||
for type_, data in board.iteritems():
|
||||
assert type_ in util.get_boards()
|
||||
board_ram = float(data['upload']['maximum_ram_size']) / 1024
|
||||
lines.append(
|
||||
"""
|
||||
* - ``{type}``
|
||||
- `{name} <{url}>`_
|
||||
- {mcu}
|
||||
- {f_cpu:d} MHz
|
||||
- {rom} Kb
|
||||
- {ram} Kb
|
||||
""".format(
|
||||
type=type_,
|
||||
name=data['name'],
|
||||
url=data['url'],
|
||||
mcu=data['build']['mcu'].upper(),
|
||||
f_cpu=int((data['build']['f_cpu'][:-1])) / 1000000,
|
||||
ram=int(board_ram) if board_ram % 1 == 0 else board_ram,
|
||||
rom=_round_memory_size(
|
||||
data['upload']['maximum_size'] / 1024)
|
||||
)
|
||||
)
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def generate_packages(packages):
|
||||
lines = []
|
||||
lines.append(""".. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Contents""")
|
||||
for type_, data in packages.iteritems():
|
||||
assert type_ in PLATFORM_PACKAGES
|
||||
contitems = [
|
||||
"`%s <%s>`_" % (name, url)
|
||||
for name, url in PLATFORM_PACKAGES[type_]
|
||||
]
|
||||
lines.append("""
|
||||
* - ``{type_}``
|
||||
- {contents}""".format(
|
||||
type_=type_,
|
||||
contents=", ".join(contitems)))
|
||||
|
||||
lines.append("""
|
||||
.. warning::
|
||||
**Linux Users:** Don't forget to install "udev" rules file
|
||||
`99-platformio-udev.rules <https://github.com/ivankravets/platformio/blob/develop/scripts/99-platformio-udev.rules>`_ (an instruction is located in the file).
|
||||
|
||||
""")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def generate_platform(name):
|
||||
print "Processing platform: %s" % name
|
||||
lines = []
|
||||
|
||||
lines.append(".. _platform_%s:" % name)
|
||||
lines.append("")
|
||||
|
||||
_title = "Platform ``%s``" % name
|
||||
lines.append(_title)
|
||||
lines.append("=" * len(_title))
|
||||
|
||||
p = PlatformFactory.newPlatform(name)
|
||||
lines.extend([l.strip() for l in p.__doc__.split("\n")])
|
||||
|
||||
lines.append(""".. contents::""")
|
||||
lines.append("""
|
||||
Packages
|
||||
--------
|
||||
""")
|
||||
lines.append(generate_packages(p.get_packages()))
|
||||
lines.append("""
|
||||
Boards
|
||||
------
|
||||
|
||||
.. note::
|
||||
* You can list pre-configured boards by :ref:`cmd_boards` command
|
||||
* For more detailed ``board`` information please scroll tables below by
|
||||
horizontal.
|
||||
""")
|
||||
|
||||
vendors = {}
|
||||
for board, data in util.get_boards().items():
|
||||
platform = data['platform']
|
||||
vendor = data['vendor']
|
||||
if name in platform:
|
||||
if vendor in vendors:
|
||||
vendors[vendor].append({board: data})
|
||||
else:
|
||||
vendors[vendor] = [{board: data}]
|
||||
for vendor, boards in sorted(vendors.iteritems()):
|
||||
lines.append(str(vendor))
|
||||
lines.append("~" * len(vendor))
|
||||
lines.append(generate_boards(boards))
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def update_platform_docs():
|
||||
for name in PlatformFactory.get_platforms().keys():
|
||||
rst_path = join(
|
||||
dirname(realpath(__file__)), "..", "docs", "platforms", "%s.rst" % name)
|
||||
with open(rst_path, "w") as f:
|
||||
f.write(generate_platform(name))
|
||||
|
||||
|
||||
def generate_framework(name, data):
|
||||
print "Processing framework: %s" % name
|
||||
lines = []
|
||||
|
||||
lines.append(".. _framework_%s:" % name)
|
||||
lines.append("")
|
||||
|
||||
_title = "Framework ``%s``" % name
|
||||
lines.append(_title)
|
||||
lines.append("=" * len(_title))
|
||||
lines.append(data['description'])
|
||||
lines.append("""\n.. contents::""")
|
||||
lines.append("""
|
||||
Boards
|
||||
------
|
||||
|
||||
.. note::
|
||||
* You can list pre-configured boards by :ref:`cmd_boards` command
|
||||
* For more detailed ``board`` information please scroll tables below by horizontal.
|
||||
""")
|
||||
|
||||
vendors = {}
|
||||
for board, data in util.get_boards().items():
|
||||
frameworks = data['frameworks']
|
||||
vendor = data['vendor']
|
||||
if name in frameworks:
|
||||
if vendor in vendors:
|
||||
vendors[vendor].append({board: data})
|
||||
else:
|
||||
vendors[vendor] = [{board: data}]
|
||||
for vendor, boards in sorted(vendors.iteritems()):
|
||||
lines.append(str(vendor))
|
||||
lines.append("~" * len(vendor))
|
||||
lines.append(generate_boards(boards))
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def update_framework_docs():
|
||||
for name, data in util.get_frameworks().items():
|
||||
rst_path = join(util.get_source_dir(), "..", "docs", "frameworks",
|
||||
"%s.rst" % name)
|
||||
with open(rst_path, "w") as f:
|
||||
f.write(generate_framework(name, data))
|
||||
|
||||
|
||||
def main():
|
||||
update_platform_docs()
|
||||
update_framework_docs()
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys_exit(main())
|
||||
Reference in New Issue
Block a user