diff --git a/platformio/builder/scripts/frameworks/arduino.py b/platformio/builder/scripts/frameworks/arduino.py index f154d5c9..ba3871bc 100644 --- a/platformio/builder/scripts/frameworks/arduino.py +++ b/platformio/builder/scripts/frameworks/arduino.py @@ -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: diff --git a/platformio/builder/scripts/frameworks/cmsis.py b/platformio/builder/scripts/frameworks/cmsis.py index 66bc005c..1b9c0236 100644 --- a/platformio/builder/scripts/frameworks/cmsis.py +++ b/platformio/builder/scripts/frameworks/cmsis.py @@ -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 diff --git a/platformio/builder/scripts/frameworks/energia.py b/platformio/builder/scripts/frameworks/energia.py index 8e1e4901..d240aa6a 100644 --- a/platformio/builder/scripts/frameworks/energia.py +++ b/platformio/builder/scripts/frameworks/energia.py @@ -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 diff --git a/platformio/builder/scripts/frameworks/mbed.py b/platformio/builder/scripts/frameworks/mbed.py index 03f54616..fcf263be 100644 --- a/platformio/builder/scripts/frameworks/mbed.py +++ b/platformio/builder/scripts/frameworks/mbed.py @@ -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", [])) )) diff --git a/platformio/builder/scripts/frameworks/opencm3.py b/platformio/builder/scripts/frameworks/opencm3.py index 330fcd07..d89fe44c 100644 --- a/platformio/builder/scripts/frameworks/opencm3.py +++ b/platformio/builder/scripts/frameworks/opencm3.py @@ -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 diff --git a/platformio/builder/scripts/frameworks/spl.py b/platformio/builder/scripts/frameworks/spl.py index b4644678..21394b82 100644 --- a/platformio/builder/scripts/frameworks/spl.py +++ b/platformio/builder/scripts/frameworks/spl.py @@ -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 diff --git a/platformio/builder/scripts/nxplpc.py b/platformio/builder/scripts/nxplpc.py index 4782c81e..39b9dfd9 100644 --- a/platformio/builder/scripts/nxplpc.py +++ b/platformio/builder/scripts/nxplpc.py @@ -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() diff --git a/platformio/exception.py b/platformio/exception.py index 5646befe..451e7761 100644 --- a/platformio/exception.py +++ b/platformio/exception.py @@ -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'" diff --git a/platformio/platforms/atmelavr.py b/platformio/platforms/atmelavr.py index f8b34bb9..6ca3e0f4 100644 --- a/platformio/platforms/atmelavr.py +++ b/platformio/platforms/atmelavr.py @@ -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 = { diff --git a/platformio/platforms/atmelsam.py b/platformio/platforms/atmelsam.py index f5913ce9..aacb03a1 100644 --- a/platformio/platforms/atmelsam.py +++ b/platformio/platforms/atmelsam.py @@ -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 = { diff --git a/platformio/platforms/base.py b/platformio/platforms/base.py index dcfef9d9..869f0e15 100644 --- a/platformio/platforms/base.py +++ b/platformio/platforms/base.py @@ -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): diff --git a/platformio/platforms/freescalekinetis.py b/platformio/platforms/freescalekinetis.py index 09243ec8..61106fea 100644 --- a/platformio/platforms/freescalekinetis.py +++ b/platformio/platforms/freescalekinetis.py @@ -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 = { diff --git a/platformio/platforms/nordicnrf51.py b/platformio/platforms/nordicnrf51.py index 17126aac..975b4ce4 100644 --- a/platformio/platforms/nordicnrf51.py +++ b/platformio/platforms/nordicnrf51.py @@ -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 = { diff --git a/platformio/platforms/nxplpc.py b/platformio/platforms/nxplpc.py index 9c9e3152..4da1334f 100644 --- a/platformio/platforms/nxplpc.py +++ b/platformio/platforms/nxplpc.py @@ -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 = { diff --git a/platformio/platforms/ststm32.py b/platformio/platforms/ststm32.py index bf1e99bf..a33947f1 100644 --- a/platformio/platforms/ststm32.py +++ b/platformio/platforms/ststm32.py @@ -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 = { diff --git a/platformio/platforms/teensy.py b/platformio/platforms/teensy.py index 8e0f2179..648c1c3f 100644 --- a/platformio/platforms/teensy.py +++ b/platformio/platforms/teensy.py @@ -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 = { diff --git a/platformio/platforms/timsp430.py b/platformio/platforms/timsp430.py index ae17a121..a15b5fd1 100644 --- a/platformio/platforms/timsp430.py +++ b/platformio/platforms/timsp430.py @@ -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 = { diff --git a/platformio/platforms/titiva.py b/platformio/platforms/titiva.py index 657cffa9..ed14d2da 100644 --- a/platformio/platforms/titiva.py +++ b/platformio/platforms/titiva.py @@ -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 = { diff --git a/scripts/docspregen.py b/scripts/docspregen.py new file mode 100644 index 00000000..0b6b5a50 --- /dev/null +++ b/scripts/docspregen.py @@ -0,0 +1,194 @@ +# Copyright (C) Ivan Kravets +# 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 `_ (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())