Merge branch 'release/v0.7.0'

.gitignore

@@ -5,3 +5,4 @@
 .sconsign.dblite
 examples/ide-eclipse/.metadata
 examples/ide-eclipse/RemoteSystemsTempFiles
+docs/_build

HISTORY.rst

@@ -1,8 +1,19 @@
 Release History
 ===============
 
-1.0.0 (?)
----------
+0.7.0 (2014-09-24)
+------------------
+
+* Implemented new ``[platformio]`` section for Configuration File with ``home_dir``
+  option (`issue #14 <https://github.com/ivankravets/platformio/issues/14>`_)
+* Implemented *Library Manager* (`issue #6 <https://github.com/ivankravets/platformio/issues/6>`_)
+
+0.6.0 (2014-08-09)
+------------------
+
+* Implemented ``serialports monitor`` (`issue #10 <https://github.com/ivankravets/platformio/issues/10>`_)
+* Fixed an issue ``ImportError: No module named platformio.util`` (`issue #9 <https://github.com/ivankravets/platformio/issues/9>`_)
+* Fixed bug with auto-conversation from Arduino \*.ino to \*.cpp
 
 0.5.0 (2014-08-04)
 ------------------
@@ -15,8 +26,8 @@ Release History
   with external library (Adafruit CC3000)
 * Implemented ``platformio upgrade`` command and "auto-check" for the latest
   version (`issue #8 <https://github.com/ivankravets/platformio/issues/8>`_)
-* Fixed issue with "auto-reset" for Raspduino board (thanks [David Mills](https://github.com/g7uvw) for testing)
-* Fixed bug with nested libs building (thanks [Antonio Vanegas](https://github.com/hpsaturn) for testing)
+* Fixed an issue with "auto-reset" for Raspduino board
+* Fixed a bug with nested libs building
 
 0.4.0 (2014-07-31)
 ------------------

README.rst

@@ -17,31 +17,36 @@ PlatformIO
     :target: https://pypi.python.org/pypi/platformio/
     :alt:  License
 
-`Quickstart <#quickstart>`_ |
-`Installation <#installation>`_ |
-`Documentation <#documentation>`_ |
-`Examples <https://github.com/ivankravets/platformio/tree/develop/examples>`_ |
-`Embedded Platform Boards <#embedded-platform-boards>`_ |
-`IDE Integration <#ide-integration>`_ |
-`Blog <http://www.ikravets.com/category/computer-life/platformio>`_
-
+`Website <http://platformio.ikravets.com>`_ |
+`Documentation <http://docs.platformio.ikravets.com>`_ |
+`Project Examples <https://github.com/ivankravets/platformio/tree/develop/examples>`_ |
+`Bugs/Questions <https://github.com/ivankravets/platformio/issues>`_ |
+`Blog <http://www.ikravets.com/category/computer-life/platformio>`_ |
+`Twitter <https://twitter.com/smartanthill>`_
 
 **PlatformIO** is a cross-platform code builder and library manager.
 
-You have no need to install any *IDE* or compile any toolchains. *PlatformIO*
+* `Website + Library Search <http://platformio.ikravets.com>`_
+* `Quickstart <http://docs.platformio.ikravets.com/en/latest/quickstart.html>`_
+* `Installation <http://docs.platformio.ikravets.com/en/latest/installation.html>`_
+* `Project Configuration File <http://docs.platformio.ikravets.com/en/latest/projectconf.html>`_
+* `Platforms & Embedded Boards <http://docs.platformio.ikravets.com/en/latest/platforms/index.html>`_
+* `User Guide <http://docs.platformio.ikravets.com/en/latest/userguide/index.html>`_
+* `IDE Integration <http://docs.platformio.ikravets.com/en/latest/ide.html>`_
+* `Release History <http://docs.platformio.ikravets.com/en/latest/history.html>`_
+
+You have no need to install any *IDE* or compile any tool chains. *PlatformIO*
 has pre-built different development platforms including: compiler, debugger,
-flasher (for embedded) and many other useful tools.
+uploader (for embedded boards) and many other useful tools.
 
 **PlatformIO** allows developer to compile the same code with different
-platforms using only one command ``platformio run``. This happens due to
-``platformio.ini`` project's file (see
-`default template <https://github.com/ivankravets/platformio/blob/develop/platformio/projectconftpl.ini>`_)
-where you can setup different environments with specific settings: platform,
-firmware uploading options, pre-built framework and many more.
-
-Each platform consists of packages which are located in own repository.
-Due to ``platformio update`` command you will have up-to-date development
-instruments.
+platforms using only one command
+`platformio run <http://docs.platformio.ikravets.com/en/latest/userguide/cmd_run.html>`_.
+This happens due to
+`Project Configuration File <http://docs.platformio.ikravets.com/en/latest/projectconf.html>`_
+where you can setup different environments with specific
+options: platform type, firmware uploading settings, pre-built framework
+and many more.
 
 .. image:: examples/platformio-examples.png
     :target: https://github.com/ivankravets/platformio/raw/develop/examples/platformio-examples.png
@@ -68,565 +73,10 @@ It has support for many popular embedded platforms like these:
   (including `TIVA C Series LaunchPads <http://www.ti.com/ww/en/launchpad/launchpads-connected.html>`_)
 
 
-See project `examples with screenshots <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
-
-
-IDE Integration
----------------
-
-* [Eclipse] `Building and debugging Atmel AVR (Arduino-based) project using Eclipse IDE+PlatformIO <http://www.ikravets.com/computer-life/programming/2014/06/20/building-and-debugging-atmel-avr-arduino-based-project-using-eclipse-ideplatformio>`_
-
-
-Embedded Platform Boards
-------------------------
-
-**PlatformIO** has pre-configured settings for most popular platform boards. You
-have no need to specify in ``platformio.ini`` type or frequency of MCU, upload
-protocol or etc. Please use ``board`` option (for
-`example <https://github.com/ivankravets/platformio/blob/develop/examples/wiring-blink/platformio.ini>`_).
-
-
-Platform ``atmelavr``
-~~~~~~~~~~~~~~~~~~~~~
-
-* ``diecimilaatmega168`` Arduino Duemilanove or Diecimila (ATmega168)
-* ``diecimilaatmega328`` Arduino Duemilanove or Diecimila (ATmega328)
-* ``fio`` Arduino Fio
-* ``leonardo`` Arduino Leonardo
-* ``LilyPadUSB`` Arduino LilyPad USB
-* ``lilypadatmega168`` Arduino LilyPad (ATmega168)
-* ``lilypadatmega328`` Arduino LilyPad (ATmega328)
-* ``megaatmega1280`` Arduino Mega (ATmega1280)
-* ``megaatmega2560`` Arduino Mega (ATmega2560)
-* ``megaADK`` Arduino Mega ADK
-* ``micro`` Arduino Micro
-* ``miniatmega168`` Arduino Mini (ATmega168)
-* ``miniatmega328`` Arduino Mini (ATmega328)
-* ``nanoatmega168`` Arduino Nano (ATmega168)
-* ``nanoatmega328`` Arduino Nano (ATmega328)
-* ``pro8MHzatmega168`` Arduino Pro or Pro Mini (ATmega168, 3.3V, 8MHz)
-* ``pro16MHzatmega168`` Arduino Pro or Pro Mini (ATmega168, 5V, 16MHz)
-* ``pro8MHzatmega328`` Arduino Pro or Pro Mini (ATmega328, 3.3V, 8MHz)
-* ``pro16MHzatmega328`` Arduino Pro or Pro Mini (ATmega328, 5V, 16MHz)
-* ``uno`` Arduino Uno
-* ``raspduino`` Raspduino
-* ``328p8m`` Microduino Core (ATmega328P, 3.3V, 8MHz)
-* ``328p16m`` Microduino Core (Atmega328P, 5V, 16MHz)
-* ``168pa8m`` Microduino Core (ATmega168PA, 3.3V, 8MHz)
-* ``168pa16m`` Microduino Core (ATmega168PA, 5V, 16MHz)
-* ``644pa8m`` Microduino Core+ (ATmega644PA, 3.3V, 8MHz)
-* ``644pa16m`` Microduino Core+ (ATmega644PA, 5V, 16MHz)
-* ``1284p8m`` Microduino-Core+ (ATmega1284P, 3.3V, 8MHz)
-* ``1284p16m`` Microduino-Core+ (ATmega1284P, 5V, 16MHz)
-* ``32u416m`` Microduino-Core USB (ATmega32U4, 5V, 16MHz)
-
-
-
-Platform ``timsp430``
-~~~~~~~~~~~~~~~~~~~~~
-
-* ``lpmsp430g2231`` TI LaunchPad MSP430 (msp430g2231)
-* ``lpmsp430g2452`` TI LaunchPad MSP430 (msp430g2452)
-* ``lpmsp430g2553`` TI LaunchPad MSP430 (msp430g2553)
-* ``lpmsp430f5529`` TI LaunchPad MSP430 (msp430f5529, 16MHz)
-* ``lpmsp430f5529_25`` TI LaunchPad MSP430 (msp430f5529, 25MHz)
-* ``lpmsp430fr5969`` TI LaunchPad MSP430 (msp430fr5969)
-* ``lpmsp430fr5739`` TI FraunchPad MSP430 (msp430fr5739)
-
-
-Platform ``titiva``
-~~~~~~~~~~~~~~~~~~~
-
-* ``lplm4f120h5qr`` TI Stellaris LM4F120 LaunchPad
-* ``lptm4c1230c3pm`` TI Tiva C Series TM4C123G LaunchPad
-* ``lptm4c1294ncpdt`` TI Tiva C Series TM4C1294 Connected LaunchPad
-
-
-Python & OS Support
--------------------
-
-**PlatformIO** is written in `Python <https://www.python.org>`_ and works with
-versions 2.6 and 2.7 on Unix/Linux, OS X, and Windows.
-
-
-Quickstart
-----------
-
-.. code-block:: bash
-
-    # Print all availalbe development platforms for installing
-    $ platformio search all
-
-    # Install new development platform
-    $ platformio install SomePlatform
-
-    # Initialize new platformio based project
-    $ cd /path/to/empty/directory
-    $ platformio init
-
-    # Process the project's environments
-    $ platformio run
-
-For more detailed information please follow to `Installation <#installation>`_
-and `Documentation <#documentation>`_ sections.
-
-
-Installation
-------------
-
-All commands below should be executed in
-`Command-line <http://en.wikipedia.org/wiki/Command-line_interface>`_
-application in your *OS*:
-
-* *Unix/Linux/OS X* this is *Terminal* application.
-* *Windows* this is
-  `Command Prompt <http://en.wikipedia.org/wiki/Command_Prompt>`_ (``cmd.exe``)
-  application.
-
-Also, the `Python Interpreter <https://www.python.org/downloads/>`_ (2.6 or 2.7)
-is required.
-
-
-Super-Quick
-~~~~~~~~~~~
-
-To install or upgrade *PlatformIO*, download
-`get-platformio.py <https://raw.githubusercontent.com/ivankravets/platformio/develop/scripts/get-platformio.py>`_ script.
-
-Then run the following (which may require administrator access):
-
-.. code-block:: bash
-
-    $ python get-platformio.py
-
-An alternative short version for *Mac/Linux* users:
-
-.. code-block:: bash
-
-    $ curl -L http://bit.ly/1lpanta | python
-
-
-On *Windows OS* it may look like:
-
-.. code-block:: bash
-
-    C:\Python27\python.exe get-platformio.py
-
-
-Full Guide
-~~~~~~~~~~
-
-1. Check a ``python`` version (only 2.6-2.7 is supported):
-
-.. code-block:: bash
-
-    $ python --version
-
-*Windows OS* Users only:
-
-    * `Download Python 2.7 <https://www.python.org/downloads/>`_ and install it.
-    * Add to PATH system variable ``;C:\Python27;C:\Python27\Scripts;`` and
-       reopen *Command Prompt* (``cmd.exe``) application. Please read this
-       article `How to set the path and environment variables in Windows
-       <http://www.computerhope.com/issues/ch000549.htm>`_.
-
-
-2. Check a ``pip`` tool for installing and managing *Python* packages:
-
-.. code-block:: bash
-
-    $ pip search platformio
-
-You should see short information about ``platformio`` package.
-
-If your computer does not recognize ``pip`` command, try to install it first
-using `these instructions <http://www.pip-installer.org/en/latest/installing.html>`_.
-
-3. Install a ``platformio`` and related packages:
-
-.. code-block:: bash
-
-    $ pip install platformio && pip install --egg scons
-
-For upgrading the ``platformio`` to new version please use this command:
-
-.. code-block:: bash
-
-    $ pip install -U platformio
-
-
-Documentation
--------------
-
-To print all available commands and options:
-
-.. code-block:: bash
-
-    $ platformio --help
-    $ platformio COMMAND --help
-
-    # Example
-    $ platformio --help
-    Usage: platformio [OPTIONS] COMMAND [ARGS]...
-
-    Options:
-      --version  Show the version and exit.
-      --help     Show this message and exit.
-
-    Commands:
-      init         Initialize new PlatformIO based project
-      install      Install new platforms
-      list         List installed platforms
-      run          Process project environments
-      search       Search for development platforms
-      serialports  List Serial ports
-      show         Show details about an installed platforms
-      uninstall    Uninstall platforms
-      update       Update installed platforms
-      upgrade      Upgrade PlatformIO to the latest version
-
-
-``platformio init``
-~~~~~~~~~~~~~~~~~~~
-
-Initialize new PlatformIO based project.
-
-.. code-block:: bash
-
-    # Change directory to future project
-    $ cd /path/to/empty/directory
-    $ platformio init
-
-    # Example
-    $ platformio init
-    Project has been initialized!
-    Please put your source code to `src` directory, external libraries to `lib`
-    and setup environments in `platformio.ini` file.
-    Then process project with `platformio run` command.
-
-After this command ``platformio`` will create:
-
-* ``.pioenvs`` - a temporary working directory.
-* ``lib`` - a directory for project specific libraries. PlatformIO will
-  compile their to static libraries and link to executable file
-* ``src`` - a source directory. Put code here.
-* ``platformio.ini`` - a configuration file for project
-
-
-``platformio install``
-~~~~~~~~~~~~~~~~~~~~~~
-
-*PlatformIO* has pre-built development platforms with related packages. You
-can install one of them:
-
-.. code-block:: bash
-
-    $ platformio install SomePlatform
-    $ platformio install SomePlatform --with-package=toolchain|uploader|PackageName
-    $ platformio install SomePlatform --without-package=toolchain|uploader|PackageName
-    $ platformio install SomePlatform --skip-default-package
-
-    # Example
-    $ platformio install timsp430
-    Installing toolchain-timsp430 package:
-    Downloading  [####################################]  100%
-    Unpacking  [####################################]  100%
-    Installing tool-mspdebug package:
-    Downloading  [####################################]  100%
-    Unpacking  [####################################]  100%
-    Installing framework-energiamsp430 package:
-    Downloading  [####################################]  100%
-    Unpacking  [####################################]  100%
-    The platform 'timsp430' has been successfully installed!
-
-    # Skip default packages and install uploader utility only
-    $ platformio install timsp430 --skip-default-package --with-package=uploader
-    Installing tool-mspdebug package:
-    Downloading  [####################################]  100%
-    Unpacking  [####################################]  100%
-    The platform 'timsp430' has been successfully installed!
-
-
-``platformio list``
-~~~~~~~~~~~~~~~~~~~
-
-To list installed platforms:
-
-.. code-block:: bash
-
-    $ platformio list
-
-    # Example
-    $ platformio list
-    timsp430    with packages: toolchain-timsp430, tool-mspdebug, framework-energiamsp430
-
-
-``platformio run``
-~~~~~~~~~~~~~~~~~~
-
-Process the project's environments defined in ``platformio.ini`` file:
-
-.. code-block:: bash
-
-    $ platformio run
-
-    # Example
-    $ platformio run
-    Processing arduino_pro5v environment:
-    scons: `.pioenvs/arduino_pro5v/firmware.elf' is up to date.
-    scons: `.pioenvs/arduino_pro5v/firmware.hex' is up to date.
-
-    Processing launchpad_msp430g2 environment:
-    scons: `.pioenvs/launchpad_msp430g2/firmware.elf' is up to date.
-    scons: `.pioenvs/launchpad_msp430g2/firmware.hex' is up to date.
-
-    Processing launchpad_lm4f120 environment:
-    scons: `.pioenvs/launchpad_lm4f120/firmware.elf' is up to date.
-    scons: `.pioenvs/launchpad_lm4f120/firmware.hex' is up to date
-
-Process specific environments:
-
-.. code-block:: bash
-
-    $ platformio run -e myenv1 -e myenv2
-
-    # Example
-    $ platformio run -e arduino_pro5v -e launchpad_lm4f120
-    Processing arduino_pro5v environment:
-    scons: `.pioenvs/arduino_pro5v/firmware.elf' is up to date.
-    scons: `.pioenvs/arduino_pro5v/firmware.hex' is up to date.
-
-    Processing launchpad_lm4f120 environment:
-    scons: `.pioenvs/launchpad_lm4f120/firmware.elf' is up to date.
-    scons: `.pioenvs/launchpad_lm4f120/firmware.hex' is up to date.
-
-Process specific target:
-
-.. code-block:: bash
-
-    $ platformio run -t clean
-    $ platformio run -t upload --upload-port=/dev/ttyUSBX
-
-    # Example
-    platformio run -t clean
-    Processing arduino_pro5v environment:
-    Removed .pioenvs/arduino_pro5v/src/main.o
-    ...
-    Removed .pioenvs/arduino_pro5v/firmware.hex
-
-    Processing launchpad_msp430g2 environment:
-    Removed .pioenvs/launchpad_msp430g2/src/main.o
-    ...
-    Removed .pioenvs/launchpad_msp430g2/firmware.hex
-
-    Processing launchpad_lm4f120 environment:
-    Removed .pioenvs/launchpad_lm4f120/src/main.o
-    ...
-    Removed .pioenvs/launchpad_lm4f120/firmware.hex
-
-Mix environments and targets:
-
-.. code-block:: bash
-
-    $ platformio run -e myembeddeddevice -t upload
-
-    # Example
-    $ platformio run -e launchpad_msp430g2 -t upload
-    Processing launchpad_msp430g2 environment:
-    /Users/ikravets/.platformio/timsp430/tools/mspdebug/mspdebug rf2500 --force-reset "prog .pioenvs/launchpad_msp430g2/firmware.hex"
-    MSPDebug version 0.20 - debugging tool for MSP430 MCUs
-    Copyright (C) 2009-2012 Daniel Beer <dlbeer@gmail.com>
-    This is free software; see the source for copying conditions.  There is NO
-    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-
-    Trying to open interface 1 on 009
-    Initializing FET...
-    FET protocol version is 30394216
-    Configured for Spy-Bi-Wire
-    Sending reset...
-    Set Vcc: 3000 mV
-    Device ID: 0x2553
-      Code start address: 0xc000
-      Code size         : 16384 byte = 16 kb
-      RAM  start address: 0x200
-      RAM  end   address: 0x3ff
-      RAM  size         : 512 byte = 0 kb
-    Device: MSP430G2553/G2403
-    Code memory starts at 0xc000
-    Number of breakpoints: 2
-    Chip ID data: 25 53
-    Erasing...
-    Programming...
-    Writing  646 bytes at c000...
-    Writing   32 bytes at ffe0...
-    Done, 678 bytes total
-
-
-``platformio search``
-~~~~~~~~~~~~~~~~~~~~~
-
-Search for development platforms:
-
-.. code-block:: bash
-
-    # Print all available development platforms
-    $ platformio search all
-
-    # Filter platforms by "Query"
-    $ platformio search "Query"
-
-    # Example
-    $ platformio search ti
-    timsp430 - An embedded platform for TI MSP430 microcontrollers (with Energia Framework)
-    titiva   - An embedded platform for TI TIVA C ARM microcontrollers (with Energia Framework)
-
-    $ platformio search arduino
-    atmelavr - An embedded platform for Atmel AVR microcontrollers (with Arduino Framework)
-
-
-``platformio serialports``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To list available `Serial Ports <http://en.wikipedia.org/wiki/Serial_port>`_:
-
-.. code-block:: bash
-
-    $ platformio serialports
-
-    # Example (Posix)
-    $ platformio serialports
-    /dev/cu.SLAB_USBtoUART
-    ----------
-    Hardware ID: USB VID:PID=10c4:ea60 SNR=0001
-    Description: CP2102 USB to UART Bridge Controller
-
-    /dev/cu.uart-1CFF4676258F4543
-    ----------
-    Hardware ID: USB VID:PID=451:f432 SNR=1CFF4676258F4543
-    Description: Texas Instruments MSP-FET430UIF
-
-    # Example (Windows)
-    $ platformio serialports
-    COM4
-    ----------
-    Hardware ID: USB VID:PID=0451:F432
-    Description: MSP430 Application UART (COM4)
-
-    COM3
-    ----------
-    Hardware ID: USB VID:PID=10C4:EA60 SNR=0001
-    Description: Silicon Labs CP210x USB to UART Bridge (COM3)
-
-
-``platformio show``
-~~~~~~~~~~~~~~~~~~~
-
-To show details about an installed platform:
-
-.. code-block:: bash
-
-    $ platformio show SomePlatform
-
-    # Example
-    $ platformio show atmelavr
-    atmelavr    - An embedded platform for Atmel AVR microcontrollers (with Arduino Framework)
-    ----------
-    Package: toolchain-atmelavr
-    Alias: toolchain
-    Location: /Users/ikravets/.platformio/atmelavr/tools/toolchain
-    Version: 1
-    ----------
-    Package: tool-avrdude
-    Alias: uploader
-    Location: /Users/ikravets/.platformio/atmelavr/tools/avrdude
-    Version: 1
-    ----------
-    Package: framework-arduinoavr
-    Location: /Users/ikravets/.platformio/atmelavr/frameworks/arduino
-    Version: 1
-
-
-``platformio uninstall``
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-To uninstall platform:
-
-.. code-block:: bash
-
-    $ platformio uninstall SomePlatform
-
-    # Example
-    $ platformio uninstall timsp430
-    Uninstalling toolchain-timsp430 package:        [OK]
-    Uninstalling tool-mspdebug package:             [OK]
-    Uninstalling framework-energiamsp430 package:   [OK]
-    The platform 'timsp430' has been successfully uninstalled!
-
-
-``platformio update``
-~~~~~~~~~~~~~~~~~~~~~
-
-To check or update installed platforms:
-
-.. code-block:: bash
-
-    $ platformio update
-
-    # Example
-    $ platformio update
-
-    Platform atmelavr
-    --------
-    Updating toolchain-atmelavr package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-    Updating framework-arduinoavr package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-    Updating tool-avrdude package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-
-    Platform timsp430
-    --------
-    Updating toolchain-timsp430 package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-    Updating tool-mspdebug package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-    Updating framework-energiamsp430 package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-
-    Platform titiva
-    --------
-    Updating toolchain-gccarmnoneeabi package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-    Updating tool-lm4flash package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-    Updating framework-energiativa package:
-    Versions: Current=1, Latest=1 	 [Up-to-date]
-
-
-``platformio upgrade``
-~~~~~~~~~~~~~~~~~~~~~~
-
-To check or upgrade PlatformIO to the latest version:
-
-.. code-block:: bash
-
-    $ platformio upgrade
-
-    # If you have problem with permissions try:
-    $ sudo platformio upgrade
-
-
-Questions & Bugs
-----------------
-
-Please use the
-`issue tracker <https://github.com/ivankravets/platformio/issues>`_
-to ask questions or report bugs.
-
-
 Licence
 -------
 
 Copyright (C) 2014 Ivan Kravets
 
 Licenced under the MIT Licence.
+

docs/Makefile

@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PlatformIO.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PlatformIO.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/PlatformIO"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PlatformIO"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/conf.py

@@ -0,0 +1,277 @@
+# -*- coding: utf-8 -*-
+#
+# PlatformIO documentation build configuration file, created by
+# sphinx-quickstart on Sun Aug  3 19:13:49 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import sys
+
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath(os.pardir))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'PlatformIO'
+copyright = u'2014, Ivan Kravets'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+import platformio
+# The short X.Y version.
+version = '.'.join(map(str, platformio.VERSION[0:2]))
+# The full version, including alpha/beta/rc tags.
+release = platformio.__version__
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PlatformIOdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'PlatformIO.tex', u'PlatformIO Documentation',
+   u'Ivan Kravets', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'platformio', u'PlatformIO Documentation',
+     [u'Ivan Kravets'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'PlatformIO', u'PlatformIO Documentation',
+   u'Ivan Kravets', 'PlatformIO', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+#intersphinx_mapping = {'http://docs.python.org/': None}
+
+# Read the Docs Sphinx Theme patch
+# on_rtd is whether we are on readthedocs.org,
+# this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# A timeout value, in seconds, for the linkcheck builder
+# http://sphinx-doc.org/config.html#confval-linkcheck_timeout
+linkcheck_timeout = 30

docs/history.rst

@@ -0,0 +1 @@
+.. include:: ../HISTORY.rst

docs/ide.rst

@@ -0,0 +1,37 @@
+.. _ide:
+
+IDE Integration
+===============
+
+Eclipse
+-------
+`Building and debugging Atmel AVR (Arduino-based) project using Eclipse IDE+PlatformIO <http://www.ikravets.com/computer-life/programming/2014/06/20/building-and-debugging-atmel-avr-arduino-based-project-using-eclipse-ideplatformio>`_
+
+
+VIM
+---
+
+Recommended bundles:
+
+* Syntax highlight - `Arduino-syntax-file <https://github.com/vim-scripts/Arduino-syntax-file>`_
+* Code Completion - `YouCompleteMe <https://github.com/Valloric/YouCompleteMe>`_
+* Syntax checking - `Syntastic <https://github.com/scrooloose/syntastic>`_
+
+Put to the project directory ``Makefile`` wrapper with contents:
+
+.. code-block:: make
+
+    # Uncomment lines below if you have problems with $PATH
+    #SHELL := /bin/bash
+    #PATH := /usr/local/bin:$(PATH)
+
+    all:
+        platformio run -t upload
+
+    clean:
+        platformio run -t clean
+
+
+Now, in VIM ``cd /path/to/this/project`` and press ``Ctrl+B`` or ``Cmd+B``
+(Mac). *PlatformIO* should compile your source code from the ``src`` directory,
+make firmware and upload it.

docs/index.rst

@@ -0,0 +1,49 @@
+PlatformIO: A cross-platform code builder and library manager
+=============================================================
+
+`Website + Library Search <http://platformio.ikravets.com>`_ |
+`Project Examples <https://github.com/ivankravets/platformio/tree/develop/examples>`_ |
+`Source Code <https://github.com/ivankravets/platformio>`_ |
+`Bugs/Questions <https://github.com/ivankravets/platformio/issues>`_ |
+`Blog <http://www.ikravets.com/category/computer-life/platformio>`_ |
+`Twitter <https://twitter.com/smartanthill>`_
+
+You have no need to install any *IDE* or compile any tool chains. *PlatformIO*
+has pre-built different development platforms including: compiler, debugger,
+uploader (for embedded) and many other useful tools.
+
+**PlatformIO** allows developer to compile the same code with different
+platforms using only one command :ref:`cmd_run`. This happens due to
+:ref:`projectconf` where you can setup different environments with specific
+options: platform type, firmware uploading settings, pre-built framework
+and many more.
+
+Each platform consists of packages which are located in own repository.
+Due to :ref:`cmd_update` command you will have up-to-date development
+instruments.
+
+**PlatformIO** is well suited for **embedded development**. It can:
+
+* Automatically analyse dependency
+* Reliably detect build changes
+* Build framework or library source code to static library
+* Build *ELF* (executable and linkable firmware)
+* Convert *ELF* to *HEX* or *BIN* file
+* Extract *EEPROM* data
+* Upload firmware to your device
+
+
+Contents
+--------
+
+.. toctree::
+    :maxdepth: 2
+
+    quickstart
+    installation
+    projectconf
+    platforms/index
+    librarymanager/index
+    userguide/index
+    ide
+    history

docs/installation.rst

@@ -0,0 +1,88 @@
+.. _installation:
+
+Installation
+============
+
+*PlatformIO* is written in `Python <https://www.python.org>`_ and works with
+versions 2.6 and 2.7 on Unix/Linux, OS X, Windows and Credit-card ARM-based
+computers (Raspberry Pi).
+
+All commands below should be executed in
+`Command-line <http://en.wikipedia.org/wiki/Command-line_interface>`_
+application in your *OS*:
+
+* *Unix/Linux/OS X* this is *Terminal* application.
+* *Windows* this is
+  `Command Prompt <http://en.wikipedia.org/wiki/Command_Prompt>`_ (``cmd.exe``)
+  application.
+
+
+Super-Quick
+-----------
+
+To install or upgrade *PlatformIO*, download
+`get-platformio.py <https://raw.githubusercontent.com/ivankravets/platformio/develop/scripts/get-platformio.py>`_ script.
+
+Then run the following (which may require administrator access):
+
+.. code-block:: bash
+
+    $ [sudo] python get-platformio.py
+
+
+On *Windows OS* it may look like:
+
+.. code-block:: bash
+
+    C:\Python27\python.exe get-platformio.py
+
+.. warning::
+    **Mac OS Users**: If you have an error ``pkg_resources.DistributionNotFound`` please
+    upgrade *SetupTools* package: ``$ [sudo] pip uninstall setuptools``
+    and ``$ [sudo] pip install setuptools``.
+    Then re-install *PlatformIO*: ``$ [sudo] pip uninstall platformio``
+    and ``$ [sudo] pip install platformio``.
+
+
+Full Guide
+----------
+
+1. Check a ``python`` version (only 2.6-2.7 is supported):
+
+.. code-block:: bash
+
+    $ python --version
+
+*Windows OS* Users only:
+
+    * `Download Python 2.7 <https://www.python.org/downloads/>`_ and install it.
+    * Add to PATH system variable ``;C:\Python27;C:\Python27\Scripts;`` and
+       reopen *Command Prompt* (``cmd.exe``) application. Please read this
+       article `How to set the path and environment variables in Windows
+       <http://www.computerhope.com/issues/ch000549.htm>`_.
+
+
+2. Check a ``pip`` tool for installing and managing *Python* packages:
+
+.. code-block:: bash
+
+    $ pip search platformio
+
+You should see short information about ``platformio`` package.
+
+If your computer does not recognize ``pip`` command, try to install it first
+using `these instructions <https://pip.pypa.io/en/latest/installing.html>`_.
+
+3. Install a ``platformio`` and related packages:
+
+.. code-block:: bash
+
+    $ pip install platformio && pip install --egg scons
+
+For upgrading the ``platformio`` to new version please use this command:
+
+.. code-block:: bash
+
+    $ pip install -U platformio
+
+

docs/librarymanager/config.rst

@@ -0,0 +1,247 @@
+.. _library_config:
+
+library.json
+============
+
+*PlatformIO*-suitable library should be defined by a manifest file
+``library.json`` in a `JSON-style <http://en.wikipedia.org/wiki/JSON>`_.
+A data in ``library.json`` should be represented via
+`associative array <http://en.wikipedia.org/wiki/Associative_array>`_
+(name/value pairs). An order doesn't matter.
+
+The allowable fields (names from pairs) are described below. The fields
+(:ref:`libjson_name`, :ref:`libjson_description` and :ref:`libjson_keywords`)
+will be displayed in the search results at the :ref:`cmd_lib_search` (*CLI*)
+and at the *WebSite*. Also, they can be used for searching for libraries.
+
+.. contents::
+
+.. _libjson_name:
+
+``name``
+--------
+
+**Required** | Type: ``String`` | Max. Length: 50
+
+A name of the library.
+
+* Must be unique.
+* Should be slug style for simplicity, consistency and compatibility.
+  Example: *Arduino-SPI*
+* Title Case, Aa-z, can contain digits and dashes (but not start/end
+  with them).
+* Consecutive dashes are not allowed.
+
+
+.. _libjson_description:
+
+``description``
+---------------
+
+**Required** | Type: ``String`` | Max. Length: 255
+
+The field helps users to identify and search for your library with a brief
+description. Describe the hardware devices (sensors, boards and etc.) which
+are suitable with it.
+
+
+.. _libjson_keywords:
+
+``keywords``
+------------
+
+**Required** | Type: ``String`` | Max. Length: 255
+
+Used for search by keyword. Helps to make your library easier to discover
+without people needing to know its name.
+
+The keyword should be lowercased, can contain a-z, digits and dash (but not
+start/end with them). A list from the keywords can be specified with
+separator ``,``
+
+
+.. _libjson_version:
+
+``version``
+-----------
+
+*Required* if :ref:`libjson_repository` field is not defined | Type: ``String``
+| Max. Length: 20
+
+A version of the current library source code.
+
+* Can contain a-z, digits, dots or dash.
+* `Semantic Versioning <http://semver.org>`_ is recommended.
+* A `CVS <http://en.wikipedia.org/wiki/Concurrent_Versions_System>`_
+  revision from the latest commit. Example: ``13`` (*SVN*) or first 10
+  chars of *SHA* digest ``e4564b7da4`` (*Git*).
+
+.. note::
+    You can omit :ref:`libjson_version` field and define
+    :ref:`libjson_repository` field. In this case
+    *PlatformIO-API Crawler* will use the *CVS*-revision from the latest commit.
+
+
+.. _libjson_author:
+
+``author``
+----------
+
+*Required* if :ref:`libjson_repository` field is not defined | Type: ``Object``
+
+An author contact information
+
+* ``name`` Full name (**Required**)
+* ``email``
+* ``url`` An author's contact page
+
+Example:
+
+.. code-block:: javascript
+
+    "author":
+    {
+        "name": "John Smith",
+        "email": "me@john-smith.com",
+        "url": "http://www.john-smith/contact"
+    }
+
+.. note::
+    You can omit :ref:`libjson_author` field and define
+    :ref:`libjson_repository` field. Only *GitHub-based* repository is
+    supported now. In this case
+    *PlatformIO-API Crawler* will use information from
+    `GitHub API Users <https://developer.github.com/v3/users/>`_.
+
+
+.. _libjson_repository:
+
+``repository``
+--------------
+
+*Required* if :ref:`libjson_downloadurl` field is not defined | Type: ``Object``
+
+The repository in which the source code can be found.
+
+Example:
+
+.. code-block:: javascript
+
+    "repository":
+    {
+        "name": "git",
+        "url": "https://github.com/foo/bar.git"
+    }
+
+
+.. _libjson_downloadurl:
+
+``downloadUrl``
+---------------
+
+*Required* if :ref:`libjson_repository` field is not defined | Type: ``String``
+
+It is the *HTTP URL* to the archived source code of library. It should end
+with the type of archive (``.zip`` or ``.tar.gz``).
+
+
+.. _libjson_include:
+
+``include``
+-----------
+
+*Optional* | Type: ``String`` or ``Array`` |
+`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
+
+If :ref:`libjson_include` field is a type of ``String``, then
+*PlatformIO-API Crawler* will recognize it like a "relative path inside
+repository/archive to library source code". See example below where the only
+source code from the relative directory ``LibrarySourceCodeHere`` will be
+included.
+
+.. code-block:: javascript
+
+    "include": "some/child/dir/LibrarySourceCodeHere"
+
+If :ref:`libjson_include` field is a type of ``Array``, then
+*PlatformIO-API Crawler* firstly will apply :ref:`libjson_exclude` filter and
+then include only directories/files which match with :ref:`libjson_include`
+patterns.
+
+Example:
+
+.. code-block:: javascript
+
+    "include":
+    [
+        "dir/*.[ch]pp",
+        "dir/examples/*",
+        "*/*/*.h"
+    ]
+
+Pattern	Meaning
+
+.. list-table::
+    :header-rows:  1
+
+    * - Pattern
+      - Meaning
+    * - ``*``
+      - matches everything
+    * - ``?``
+      - matches any single character
+    * - ``[seq]``
+      - matches any character in seq
+    * - ``[!seq]``
+      - matches any character not in seq
+
+
+.. _libjson_exclude:
+
+``exclude``
+-----------
+
+*Optional* | Type: ``String`` or ``Array`` |
+`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
+
+Exclude the directories and files which match with :ref:`libjson_exclude`
+patterns.
+
+
+.. _libjson_dependencies:
+
+``dependencies``
+----------------
+
+*Optional* | Type: ``Array``
+
+A list of dependent libraries. They will be installed automatically with
+:ref:`cmd_lib_install` command.
+
+Example:
+
+.. code-block:: javascript
+
+    "dependencies":
+    [
+        "Library-Foo",
+        "Library-Bar"
+    ]
+
+
+.. _libjson_examples:
+
+``examples``
+----------------
+
+*Optional* | Type: ``String`` or ``Array`` |
+`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
+
+A list of example patterns. This field is predefined with default value:
+
+.. code-block:: javascript
+
+    "examples": [
+        "[Ee]xamples/*/*.ini",
+        "[Ee]xamples/*/*.pde"
+    ]

docs/librarymanager/creating.rst

@@ -0,0 +1,130 @@
+.. _library_creating:
+.. |PIOAPICR| replace:: *PlatformIO-API Crawler*
+
+Creating Library
+================
+
+*PlatformIO* :ref:`librarymanager` doesn't have any requirements to a library
+source code structure. The only one requirement is library's manifest file -
+:ref:`library_config`. It can be located inside your library or in the another
+location where |PIOAPICR| will have *HTTP* access.
+
+.. contents::
+
+Source Code Location
+--------------------
+
+There are a several ways how to share your library with the whole world
+(see `examples <https://github.com/ivankravets/platformio-libmirror/tree/master/configs>`_).
+
+You can hold a lot of libraries (split into separated folders) inside one of
+the repository/archive. In this case please use :ref:`libjson_include`
+field to specify the relative path to your library's source code.
+
+
+At GitHub
+^^^^^^^^^
+
+**Recommended**
+
+If a library source code is located at `GitHub <https://github.com>`_, then
+you **need to specify** only these fields in the :ref:`library_config`:
+
+* :ref:`libjson_name`
+* :ref:`libjson_keywords`
+* :ref:`libjson_description`
+* :ref:`libjson_repository`
+
+|PIOAPICR| will populate the rest fields, like :ref:`libjson_version` or
+:ref:`libjson_author` with an actual information from *GitHub*.
+
+Example:
+
+.. code-block:: javascript
+
+    {
+        "name": "Arduino-IRremote",
+        "keywords": "infrared, ir, remote",
+        "description": "Send and receive infrared signals with multiple protocols",
+        "repository":
+        {
+            "type": "git",
+            "url": "https://github.com/shirriff/Arduino-IRremote.git"
+        }
+    }
+
+Under CVS (SVN/GIT)
+^^^^^^^^^^^^^^^^^^^
+
+|PIOAPICR| can operate with a library source code that is under *CVS* control.
+The list of **required** fields in the :ref:`library_config` will look like:
+
+* :ref:`libjson_name`
+* :ref:`libjson_keywords`
+* :ref:`libjson_description`
+* :ref:`libjson_author`
+* :ref:`libjson_repository`
+
+Example:
+
+.. code-block:: javascript
+
+    {
+        "name": "Arduino-XBee",
+        "keywords": "xbee, protocol, radio",
+        "description": "Arduino library for communicating with XBees in API mode",
+        "author":
+        {
+            "name": "Andrew Rapp",
+            "email": "andrew.rapp@gmail.com",
+            "url": "https://code.google.com/u/andrew.rapp@gmail.com/"
+        },
+        "repository":
+        {
+            "type": "git",
+            "url": "https://code.google.com/p/xbee-arduino/"
+        }
+    }
+
+Self-hosted
+^^^^^^^^^^^
+
+You can manually archive (*Zip, Tar.Gz*) your library source code and host it
+in the *Internet*. Then you should specify the additional fields,
+like :ref:`libjson_version` and :ref:`libjson_downloadurl`. The final list
+of **required** fields in the :ref:`library_config` will look like:
+
+* :ref:`libjson_name`
+* :ref:`libjson_keywords`
+* :ref:`libjson_description`
+* :ref:`libjson_author`
+* :ref:`libjson_version`
+* :ref:`libjson_downloadurl`
+
+.. code-block:: javascript
+
+    {
+        "name": "Arduino-OneWire",
+        "keywords": "onewire, 1-wire, bus, sensor, temperature, ibutton",
+        "description": "Control devices (from Dallas Semiconductor) that use the One Wire protocol (DS18S20, DS18B20, DS2408 and etc)",
+        "author":
+        {
+            "name": "Paul Stoffregen",
+            "url": "http://www.pjrc.com/teensy/td_libs_OneWire.html"
+        },
+        "version": "2.2",
+        "downloadUrl": "http://www.pjrc.com/teensy/arduino_libraries/OneWire.zip",
+        "include": "OneWire"
+    }
+
+
+Register
+--------
+
+The registration requirements:
+
+* A library must adhere to the :ref:`library_config` specification.
+* There must be public *HTTP* access to the library :ref:`library_config` file.
+
+Now, you can :ref:`register <cmd_lib_register>` your library and allow others
+to :ref:`install <cmd_lib_install>` it.

docs/librarymanager/index.rst

@@ -0,0 +1,24 @@
+.. _librarymanager:
+
+Library Manager
+===============
+
+..
+
+    *"The missing library manager for embedded platforms"* [#]_
+
+*PlatformIO Library Manager* allows you to organize external embedded libraries.
+You can search for new libraries via :ref:`Command Line <cmd_lib_search>`
+or `WebSite <http://platformio.ikravets.com>`_ interfaces.
+
+You don't need to bother for finding the latest version of library. Due to
+:ref:`cmd_lib_update` command you will have up-to-date external libraries.
+
+.. toctree::
+    :maxdepth: 2
+
+    creating
+    config
+
+.. [#] Inspired by `npm <https://www.npmjs.org>`_ and `bower
+    <http://bower.io>`_ package managers for web.

docs/make.bat

@@ -0,0 +1,242 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PlatformIO.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PlatformIO.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

docs/platforms/atmelavr.rst

@@ -0,0 +1,323 @@
+.. _platform_atmelavr:
+
+Platform ``atmelavr``
+=====================
+
+`Atmel AVR® 8- and 32-bit MCUs <http://www.atmel.com/products/microcontrollers/avr/default.aspx>`_
+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 industry's most code-efficient architecture for
+C and assembly programming.
+
+.. contents::
+
+Packages
+--------
+
+.. list-table::
+    :header-rows:  1
+
+    * - Name
+      - Alias
+      - Contents
+    * - ``toolchain-atmelavr``
+      - toolchain
+      - `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/>`_
+    * - ``tool-avrdude``
+      - uploader
+      - `AVRDUDE <http://www.nongnu.org/avrdude/>`_
+    * - ``framework-arduinoavr``
+      -
+      - See below in :ref:`atmelavr_frameworks`
+
+
+.. note::
+    You can install ``atmelavr`` platform with these packages
+    via :ref:`cmd_install` command.
+
+
+.. _atmelavr_frameworks:
+
+Frameworks
+----------
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``framework``
+      - Name
+      - Reference
+    * - ``arduino``
+      - Arduino Wiring-based Framework (AVR Core, 1.5.x branch)
+      - `Documentation <http://arduino.cc/en/Reference/HomePage>`_
+
+
+Boards
+------
+
+.. note::
+   For more detailed ``board`` information please scroll tables below by
+   horizontal.
+
+Arduino
+~~~~~~~
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``board``
+      - Name
+      - Microcontroller ``board_mcu``
+      - Frequency ``board_f_cpu``
+      - Flash
+      - RAM
+    * - ``diecimilaatmega168``
+      - `Arduino Diecimila or Duemilanove (ATmega168)
+        <http://arduino.cc/en/Main/ArduinoBoardDiecimila>`_
+      - ATmega168 ``atmega168``
+      - 16 MHz ``16000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``diecimilaatmega328``
+      - `Arduino Diecimila or Duemilanove (ATmega328)
+        <http://arduino.cc/en/Main/ArduinoBoardDiecimila>`_
+      - ATmega328 ``atmega328``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``fio``
+      - `Arduino Fio
+        <http://arduino.cc/en/Main/ArduinoBoardFio>`_
+      - ATmega328P ``atmega328p``
+      - 8 MHz ``8000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``leonardo``
+      - `Arduino Leonardo <http://arduino.cc/en/Main/arduinoBoardLeonardo>`_
+      - ATmega32u4 ``atmega32u4``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2.5 Kb
+    * - ``LilyPadUSB``
+      - `Arduino LilyPad USB
+        <http://arduino.cc/en/Main/ArduinoBoardLilyPadUSB>`_
+      - ATmega32u4 ``atmega32u4``
+      - 8 MHz ``8000000L``
+      - 32 Kb
+      - 2.5 Kb
+    * - ``lilypadatmega168``
+      - `Arduino LilyPad (ATmega168)
+        <http://arduino.cc/en/Main/ArduinoBoardLilyPad>`_
+      - ATmega168 ``atmega168``
+      - 8 MHz ``8000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``lilypadatmega328``
+      - `Arduino LilyPad (ATmega328)
+        <http://arduino.cc/en/Main/ArduinoBoardLilyPad>`_
+      - ATmega328P ``atmega328p``
+      - 8 MHz ``8000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``megaatmega1280``
+      - `Arduino Mega (ATmega1280)
+        <http://arduino.cc/en/Main/arduinoBoardMega>`_
+      - ATmega1280 ``atmega1280``
+      - 16 MHz ``16000000L``
+      - 128 Kb
+      - 8 Kb
+    * - ``megaatmega2560``
+      - `Arduino Mega (ATmega2560)
+        <http://arduino.cc/en/Main/arduinoBoardMega2560>`_
+      - ATmega2560 ``atmega2560``
+      - 16 MHz ``16000000L``
+      - 256 Kb
+      - 8 Kb
+    * - ``megaADK``
+      - `Arduino Mega ADK
+        <http://arduino.cc/en/Main/ArduinoBoardMegaADK>`_
+      - ATmega2560 ``atmega2560``
+      - 16 MHz ``16000000L``
+      - 256 Kb
+      - 8 Kb
+    * - ``micro``
+      - `Arduino Micro
+        <http://arduino.cc/en/Main/ArduinoBoardMicro>`_
+      - ATmega32u4 ``atmega32u4``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2.5 Kb
+    * - ``miniatmega168``
+      - `Arduino Mini (ATmega168)
+        <http://arduino.cc/en/Main/ArduinoBoardMini>`_
+      - ATmega168 ``atmega168``
+      - 16 MHz ``16000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``miniatmega328``
+      - `Arduino Mini (ATmega328P)
+        <http://arduino.cc/en/Main/ArduinoBoardMini>`_
+      - ATmega328P ``atmega328p``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``nanoatmega168``
+      - `Arduino Nano (ATmega168)
+        <http://arduino.cc/en/Main/ArduinoBoardNano>`_
+      - ATmega168 ``atmega168``
+      - 16 MHz ``16000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``nanoatmega328``
+      - `Arduino Nano (ATmega328P)
+        <http://arduino.cc/en/Main/ArduinoBoardNano>`_
+      - ATmega328P ``atmega328p``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``pro8MHzatmega168``
+      - `Arduino Pro or Pro Mini (ATmega168, 3.3V)
+        <http://arduino.cc/en/Main/ArduinoBoardProMini>`_
+      - ATmega168 ``atmega168``
+      - 8 MHz ``8000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``pro16MHzatmega168``
+      - `Arduino Pro or Pro Mini (ATmega168, 5V)
+        <http://arduino.cc/en/Main/ArduinoBoardProMini>`_
+      - ATmega168 ``atmega168``
+      - 16 MHz ``16000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``pro8MHzatmega328``
+      - `Arduino Pro or Pro Mini (ATmega328P, 3.3V)
+        <http://arduino.cc/en/Main/ArduinoBoardProMini>`_
+      - ATmega328P ``atmega328p``
+      - 8 MHz ``8000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``pro16MHzatmega328``
+      - `Arduino Pro or Pro Mini (ATmega328P, 5V)
+        <http://arduino.cc/en/Main/ArduinoBoardProMini>`_
+      - ATmega328P ``atmega328p``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``uno``
+      - `Arduino Uno
+        <http://arduino.cc/en/Main/ArduinoBoardUno>`_
+      - ATmega328P ``atmega328p``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2 Kb
+
+More detailed information you can find here
+`Arduino boards <http://arduino.cc/en/Main/Products>`_.
+
+
+Microduino
+~~~~~~~~~~
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``board``
+      - Name
+      - Microcontroller ``board_mcu``
+      - Frequency ``board_f_cpu``
+      - Flash
+      - RAM
+    * - ``168pa8m``
+      - `Microduino Core (ATmega168P, 3.3V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core>`_
+      - ATmega168P ``atmega168p``
+      - 8 MHz ``8000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``168pa16m``
+      - `Microduino Core (ATmega168P, 5V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core>`_
+      - ATmega168P ``atmega168p``
+      - 16 MHz ``16000000L``
+      - 16 Kb
+      - 1 Kb
+    * - ``328p8m``
+      - `Microduino Core (ATmega328P, 3.3V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core>`_
+      - ATmega328P ``atmega328p``
+      - 8 MHz ``8000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``328p16m``
+      - `Microduino Core (ATmega328P, 5V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core>`_
+      - ATmega328P ``atmega328p``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2 Kb
+    * - ``644pa8m``
+      - `Microduino Core+ (ATmega644PA, 3.3V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core%2B>`_
+      - ATmega644PA ``atmega644p``
+      - 8 MHz ``8000000L``
+      - 64 Kb
+      - 4 Kb
+    * - ``644pa16m``
+      - `Microduino Core+ (ATmega644PA, 5V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core%2B>`_
+      - ATmega644PA ``atmega644p``
+      - 16 MHz ``16000000L``
+      - 64 Kb
+      - 4 Kb
+    * - ``1284p8m``
+      - `Microduino Core+ (Atmega1284P, 3.3V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core%2B>`_
+      - Atmega1284P ``atmega1284p``
+      - 8 MHz ``8000000L``
+      - 128 Kb
+      - 16 Kb
+    * - ``1284p16m``
+      - `Microduino Core+ (Atmega1284P, 5V)
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-Core%2B>`_
+      - Atmega1284P ``atmega1284p``
+      - 16 MHz ``16000000L``
+      - 128 Kb
+      - 16 Kb
+    * - ``32u416m``
+      - `Microduino-Core USB
+        <http://www.microduino.cc/wiki/index.php?title=Microduino-CoreUSB>`_
+      - ATmega32u4 ``atmega32u4``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2.5 Kb
+
+
+More detailed information you can find here
+`Microduino boards <http://www.microduino.cc/wiki/index.php?title=Main_Page>`_.
+
+
+Raspduino
+~~~~~~~~~
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``board``
+      - Name
+      - Microcontroller ``board_mcu``
+      - Frequency ``board_f_cpu``
+      - Flash
+      - RAM
+    * - ``raspduino``
+      - `Raspduino
+        <http://www.bitwizard.nl/wiki/index.php/Raspduino>`_
+      - ATmega328P ``atmega328p``
+      - 16 MHz ``16000000L``
+      - 32 Kb
+      - 2 Kb
+
+More detailed information you can find in
+`Wiki <http://www.bitwizard.nl/wiki/index.php/Raspduino>`_.

docs/platforms/index.rst

@@ -0,0 +1,19 @@
+.. _platforms:
+
+Platforms & Embedded Boards
+===========================
+
+*PlatformIO* has pre-built different development platforms for popular OS (Mac,
+Linux 32/64/ARM and Windows). Each of them include compiler, debugger, uploader
+(for embedded) and many other useful tools.
+
+Also it has pre-configured settings for most popular **Embedded Platform
+Boards**. You have no need to specify in :ref:`projectconf` type or frequency of
+MCU, upload protocol or etc. Please use ``board`` option.
+
+.. toctree::
+    :maxdepth: 2
+
+    atmelavr
+    timsp430
+    titiva

docs/platforms/timsp430.rst

@@ -0,0 +1,119 @@
+.. _platform_timsp430:
+
+Platform ``timsp430``
+=====================
+
+`MSP430 microcontrollers (MCUs) from Texas Instruments (TI) <http://www.ti.com/lsds/ti/microcontrollers_16-bit_32-bit/msp/overview.page>`_
+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.
+
+.. contents::
+
+Packages
+--------
+
+.. list-table::
+    :header-rows:  1
+
+    * - Name
+      - Alias
+      - Contents
+    * - ``toolchain-timsp430``
+      - toolchain
+      - `msp-gcc <http://sourceforge.net/projects/mspgcc/>`_,
+        `GDB <http://www.gnu.org/software/gdb/>`_
+    * - ``tool-mspdebug``
+      - uploader
+      - `MSPDebug <http://mspdebug.sourceforge.net>`_
+    * - ``framework-energiamsp430``
+      -
+      - See below in :ref:`timsp430_frameworks`
+
+
+.. note::
+    You can install ``atmelavr`` platform with these packages
+    via :ref:`cmd_install` command.
+
+
+.. _timsp430_frameworks:
+
+Frameworks
+----------
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``framework``
+      - Name
+      - Reference
+    * - ``energia``
+      - Energia Wiring-based Framework (MSP430 Core)
+      - `Documentation <http://energia.nu/reference/>`_
+
+
+Boards
+------
+
+.. note::
+   For more detailed ``board`` information please scroll table below by
+   horizontal.
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``board``
+      - Name
+      - Microcontroller ``board_mcu``
+      - Frequency ``board_f_cpu``
+      - Flash
+      - RAM
+    * - ``lpmsp430g2231``
+      - `MSP430G2231 LaunchPad <http://www.ti.com/ww/en/launchpad/launchpads-msp430-msp-exp430g2.html>`_
+      - MSP430G2231 ``msp430g2231``
+      - 16 MHz ``16000000L``
+      - 2 Kb
+      - 128 B
+    * - ``lpmsp430g2452``
+      - `MSP430G2452 LaunchPad <http://www.ti.com/ww/en/launchpad/launchpads-msp430-msp-exp430g2.html>`_
+      - MSP430G2452 ``msp430g2452``
+      - 16 MHz ``16000000L``
+      - 8 Kb
+      - 256 B
+    * - ``lpmsp430g2553``
+      - `MSP430G2553 LaunchPad <http://www.ti.com/ww/en/launchpad/launchpads-msp430-msp-exp430g2.html>`_
+      - MSP430G2553 ``msp430g2553``
+      - 16 MHz ``16000000L``
+      - 16 Kb
+      - 512 B
+    * - ``lpmsp430f5529``
+      - `MSP430F5529 LaunchPad (16 Mhz) <http://www.ti.com/ww/en/launchpad/launchpads-msp430-msp-exp430f5529lp.html>`_
+      - MSP430F5529 ``msp430f5529``
+      - 16 MHz ``16000000L``
+      - 128 Kb
+      - 8 KB
+    * - ``lpmsp430f5529_25``
+      - `MSP430F5529 LaunchPad (25 Mhz) <http://www.ti.com/ww/en/launchpad/launchpads-msp430-msp-exp430f5529lp.html>`_
+      - MSP430F5529 ``msp430f5529``
+      - 25 MHz ``25000000L``
+      - 128 Kb
+      - 8 KB
+    * - ``lpmsp430fr5739``
+      - `MSP430FR5739 Experimenter Board <http://www.ti.com/tool/msp-exp430fr5739>`_
+      - MSP430FR5739 ``msp430fr5739``
+      - 16 MHz ``16000000L``
+      - 16 Kb
+      - 1 KB
+    * - ``lpmsp430fr5969``
+      - `MSP430FR5969 LaunchPad <http://www.ti.com/ww/en/launchpad/launchpads-msp430-msp-exp430fr5969.html>`_
+      - MSP430FR5969 ``msp430fr5969``
+      - 16 MHz ``16000000L``
+      - 64 Kb
+      - 2 KB
+
+
+More detailed information you can find here
+`MSP430 LaunchPads <http://www.ti.com/ww/en/launchpad/launchpads-msp430.html>`_.
+
+
+

docs/platforms/titiva.rst

@@ -0,0 +1,93 @@
+.. _platform_titiva:
+
+Platform ``titiva``
+===================
+
+`Texas Instruments TM4C12x MCUs <http://www.ti.com/lsds/ti/microcontrollers_16-bit_32-bit/c2000_performance/control_automation/tm4c12x/overview.page>`_
+offer the industry’s 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.
+
+.. contents::
+
+Packages
+--------
+
+.. list-table::
+    :header-rows:  1
+
+    * - Name
+      - Alias
+      - Contents
+    * - ``toolchain-gccarmnoneeabi``
+      - toolchain
+      - `gcc-arm-embedded <https://launchpad.net/gcc-arm-embedded/>`_,
+        `GDB <http://www.gnu.org/software/gdb/>`_
+    * - ``tool-lm4flash``
+      - uploader
+      - `Flash Programmer <http://www.ti.com/tool/lmflashprogrammer>`_
+    * - ``framework-energiativa``
+      -
+      - See below in :ref:`titiva_frameworks`
+
+.. note::
+    You can install ``titiva`` platform with these packages
+    via :ref:`cmd_install` command.
+
+
+.. _titiva_frameworks:
+
+Frameworks
+----------
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``framework``
+      - Name
+      - Reference
+    * - ``energia``
+      - Energia Wiring-based Framework (LM4F Core)
+      - `Documentation <http://energia.nu/reference/>`_
+
+
+Boards
+------
+
+.. note::
+   For more detailed ``board`` information please scroll table below by
+   horizontal.
+
+.. list-table::
+    :header-rows:  1
+
+    * - Type ``board``
+      - Name
+      - Microcontroller ``board_mcu``
+      - Frequency ``board_f_cpu``
+      - Flash
+      - RAM
+    * - ``lplm4f120h5qr``
+      - `Stellaris LM4F120 LaunchPad <http://www.ti.com/tool/ek-lm4f120xl>`_
+      - LM4F120H5QR ``cortex-m4``
+      - 80 MHz ``80000000L``
+      - 256 Kb
+      - 32 Kb
+    * - ``lptm4c1230c3pm``
+      - `Tiva C Series TM4C123G LaunchPad
+        <http://www.ti.com/ww/en/launchpad/launchpads-connected-ek-tm4c123gxl.html>`_
+      - TM4C123GH6PM ``cortex-m4``
+      - 80 MHz ``80000000L``
+      - 256 Kb
+      - 32 Kb
+    * - ``lptm4c1294ncpdt``
+      - `Tiva C Series TM4C1294 Connected LaunchPad
+        <http://www.ti.com/ww/en/launchpad/launchpads-connected-ek-tm4c1294xl.html>`_
+      - TM4C1294NCPDT ``cortex-m4``
+      - 120 Mhz ``120000000L``
+      - 1 Mb
+      - 256 Kb
+
+More detailed information you can find here
+`TIVA C Series LaunchPads <http://www.ti.com/ww/en/launchpad/launchpads-connected.html>`_.

docs/projectconf.rst

@@ -0,0 +1,350 @@
+.. _projectconf:
+
+Project Configuration File
+==========================
+
+The Project configuration file is named ``platformio.ini``. This is a
+`INI-style <http://en.wikipedia.org/wiki/INI_file>`_ file.
+
+``platformio.ini`` has sections (each denoted by a ``[header]``) and
+key / value pairs within the sections. A sign ``#`` at the beginning of the
+line indicate a comment. Comment lines are ignored.
+
+The sections and their allowable values are described below.
+
+.. contents::
+
+[platformio]
+------------
+
+A ``platformio`` section is used for overriding default configuration options
+
+Options
+~~~~~~~
+
+``home_dir``
+^^^^^^^^^^^^
+
+A ``$PIO_HOME_DIR`` is used to store platform tool chains, frameworks,
+external libraries, service data and etc.
+
+A default value is user's home directory: *Unix* - ``~/.platformio``,
+Windows - ``%HOMEPATH%\.platformio``.
+
+
+``lib_dir``
+^^^^^^^^^^^^
+
+This directory is used to store external libraries downloaded by
+:ref:`librarymanager`.
+
+A default value is ``$PIO_HOME_DIR/lib``.
+
+[env:NAME]
+----------
+
+A section with ``env:`` prefix is used to define virtual environment with
+specific options that will be processed with :ref:`cmd_run` command. You can
+define unlimited numbers of environments.
+
+Each environment must have unique ``NAME``. The valid chars for ``NAME`` are
+
+* letters ``a-z``
+* numbers ``0-9``
+* special char ``_`` (underscore)
+
+For example, ``[env:hello_world]``.
+
+Options
+~~~~~~~
+
+``platform``
+^^^^^^^^^^^^
+
+:ref:`Platform <platforms>` type
+
+
+``framework``
+^^^^^^^^^^^^^
+
+See ``framework`` type in *Frameworks* section of :ref:`platforms`
+
+
+``board``
+^^^^^^^^^
+
+*PlatformIO* has pre-configured settings for most popular boards. You don't
+need to specify ``board_mcu``, ``board_f_cpu``, ``upload_protocol`` or
+``upload_speed`` options. Just define a ``board`` type and *PlatformIO* will
+pre-fill options described above with appropriate values.
+
+You can find the ``board`` type in *Boards* section of each :ref:`platforms`.
+
+
+``board_mcu``
+^^^^^^^^^^^^^
+
+``board_mcu`` is a microcontroller(MCU) type that is used by compiler to
+recognize MCU architecture. The correct type of ``board_mcu`` depends on
+platform library. For example, the list of ``board_mcu`` for "megaAVR Devices"
+is described `here <http://www.nongnu.org/avr-libc/user-manual/>`_.
+
+The full list of ``board_mcu`` for popular embedded platforms you can find in
+*Boards* section of :ref:`platforms`. See "Microcontroller" column.
+
+
+``board_f_cpu``
+^^^^^^^^^^^^^^^
+
+An option ``board_f_cpu`` is used to define MCU frequency (Hertz, Clock). A
+format of this option is ``C-like long integer`` value with ``L`` suffix. The
+1 Hertz is equal to ``1L``, then 16 Mhz (Mega Hertz) is equal to ``16000000L``.
+
+The full list of ``board_f_cpu`` for popular embedded platforms you can find in
+*Boards* section of :ref:`platforms`. See "Frequency" column.
+
+
+``upload_port``
+^^^^^^^^^^^^^^^
+
+This option is used by "uploader" tool to send firmware to the board via
+``upload_port``. For example,
+
+* ``/dev/ttyUSB0`` - Unix-based OS
+* ``COM3`` - Windows OS
+
+To print all available serial ports use :ref:`cmd_serialports` command.
+
+
+``upload_protocol``
+^^^^^^^^^^^^^^^^^^^
+
+A protocol that "uploader" tool uses to talk to the board.
+
+
+``upload_speed``
+^^^^^^^^^^^^^^^^
+
+A connection speed (`baud rate <http://en.wikipedia.org/wiki/Baud>`_)
+which "uploader" tool uses when sending firmware to the board.
+
+
+``targets``
+^^^^^^^^^^^
+
+A list with targets which will be processed by :ref:`cmd_run` command by
+default. You can enter more then one target separated with "space".
+
+When no targets are defined, *PlatformIO* will build only sources by default.
+
+.. note::
+    This option is useful to enable "auto-uploading" after building operation
+    (``targets = upload``).
+
+
+``build_flags``
+^^^^^^^^^^^^^^^
+
+These flags/options control preprocessing, compilation, assembly and linking
+processes:
+
+.. list-table::
+    :header-rows:  1
+
+    * - Format
+      - Scope
+      - Description
+    * - ``Wp,option``
+      - CPPFLAGS
+      - Bypass the compiler driver and pass *option* directly  through to the
+        preprocessor
+    * - ``-D name``
+      - CPPDEFINES
+      - Predefine *name* as a macro, with definition 1.
+    * - ``-D name=definition``
+      - CPPDEFINES
+      - The contents of *definition* are tokenized and processed as if they
+        appeared during translation phase three in a ``#define`` directive.
+    * - ``-U name``
+      - CPPDEFINES
+      - Cancel any previous definition of *name*, either built in or provided
+        with a ``-D`` option.
+    * - ``-Wall``
+      - CCFLAGS
+      - Turns on all optional warnings which are desirable for normal code.
+    * - ``-Werror``
+      - CCFLAGS
+      - Make all warnings into hard errors. Source code which triggers warnings will be rejected.
+    * - ``-w``
+      - CCFLAGS
+      - Suppress all warnings, including those which GNU CPP issues by default.
+    * - ``-include file``
+      - CCFLAGS
+      - Process *file* as if ``#include "file"`` appeared as the first line of
+        the primary source file.
+    * - ``-Wa,option``
+      - ASFLAGS, CCFLAGS
+      - Pass *option* as an option to the assembler. If *option* contains
+        commas, it is split into multiple options at the commas.
+    * - ``-llibrary``
+      - LIBS
+      - Search the *library* named library when linking
+    * - ``-Ldir``
+      - LIBPATH
+      - Add directory *dir* to the list of directories to be searched for
+        ``-l``.
+    * - ``-Idir``
+      - CPPPATH
+      - Add the directory *dir* to the list of directories to be searched
+        for header files.
+
+Example:
+
+.. code-block::   ini
+
+    [env:specific_defines]
+    build_flags = -O2 -Dfoo -Dbar=1
+
+    [env:specific_inclibs]
+    build_flags = -I/opt/include -L/opt/lib -lfoo
+
+
+For more detailed information about available flags/options go to:
+
+* `Options to Request or Suppress Warnings
+  <https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html>`_
+* `Options for Debugging Your Program
+  <https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html>`_
+* `Options That Control Optimization
+  <https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html>`_
+* `Options Controlling the Preprocessor
+  <https://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html>`_
+* `Passing Options to the Assembler
+  <https://gcc.gnu.org/onlinedocs/gcc/Assembler-Options.html>`_
+* `Options for Linking <https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html>`_
+* `Options for Directory Search
+  <https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_
+
+
+``srcbuild_flags``
+^^^^^^^^^^^^^^^^^^
+
+This is option ``srcbuild_flags`` has the same behaviour like ``build_flags``
+but will be applied only for project source code from ``src`` directory.
+
+Examples
+--------
+
+1. :ref:`platform_atmelavr`: Arduino UNO board with auto pre-configured
+   ``board_*`` and ``upload_*`` options (use only ``board`` option) and Arduino
+   Wiring-based Framework
+
+.. code-block::   ini
+
+    [env:atmelavr_arduino_uno_board]
+    platform = atmelavr
+    framework = arduino
+    board = uno
+
+    upload_port = /dev/ttyUSB0
+    # for Windows OS
+    # upload_port = COM3
+
+    # enable auto-uploading
+    targets = upload
+
+
+2. :ref:`platform_atmelavr`: Microduino Core (ATmega168P, 3.3V) board with
+   auto pre-configured ``board_*`` and ``upload_*`` options (use only
+   ``board`` option) and Arduino Wiring-based Framework
+
+.. code-block::   ini
+
+    [env:atmelavr_microduino_core_board]
+    platform = atmelavr
+    framework = arduino
+    board = 168pa8m
+
+    upload_port = /dev/ttyUSB0
+    # for Windows OS
+    # upload_port = COM3
+
+    # enable auto-uploading
+    targets = upload
+
+
+3. :ref:`platform_atmelavr`: Raspduino board with
+   auto pre-configured ``board_*`` and ``upload_*`` options (use only
+   ``board`` option) and Arduino Wiring-based Framework
+
+.. code-block::   ini
+
+    [env:atmelavr_raspduino_board]
+    platform = atmelavr
+    framework = arduino
+    board = raspduino
+
+    upload_port = /dev/ttyS0
+
+    # enable auto-uploading
+    targets = upload
+
+
+4. :ref:`platform_atmelavr`: Embedded board that is based on ATmega168 MCU with
+   "arduino" bootloader
+
+.. code-block::   ini
+
+    [env:atmelavr_atmega168_board]
+    platform = atmelavr
+    board_mcu = atmega168
+    board_f_cpu = 16000000L
+
+    upload_port = /dev/ttyUSB0
+    # for Windows OS
+    # upload_port = COM3
+    upload_protocol = arduino
+    upload_speed = 19200
+
+    # enable auto-uploading
+    targets = upload
+
+
+5. :ref:`platform_timsp430`: TI MSP430G2553 LaunchPad with auto pre-configured
+   ``board_*`` and ``upload_*`` options (use only ``board`` option) and Energia
+   Wiring-based Framework
+
+.. code-block::   ini
+
+    [env:timsp430_g2553_launchpad]
+    platform = timsp430
+    framework = energia
+    board = lpmsp430g2553
+
+
+6. :ref:`platform_timsp430`: Embedded board that is based on MSP430G2553 MCU
+
+.. code-block::   ini
+
+    [env:timsp430_g2553_board]
+    platform = timsp430
+    board_mcu = msp430g2553
+    board_f_cpu = 16000000L
+
+    upload_protocol = rf2500
+
+    # enable auto-uploading
+    targets = upload
+
+
+5. :ref:`platform_titiva`: TI Tiva C ARM Series TM4C123G LaunchPad with auto
+   pre-configured ``board_*`` and ``upload_*`` options (use only ``board``
+   option) and Energia Wiring-based Framework
+
+.. code-block::   ini
+
+    [env:titiva_tm4c1230c3pm_launchpad]
+    platform = titiva
+    framework = energia
+    board = lptm4c1230c3pm
+

docs/quickstart.rst

@@ -0,0 +1,67 @@
+.. _quickstart:
+
+Quickstart
+==========
+
+First, :ref:`Install PlatformIO <installation>`.
+
+Print all available development platforms for installing
+
+.. code-block:: bash
+
+    $ platformio search all
+    [ ... ]
+
+
+Install new development platform
+
+.. code-block:: bash
+
+    $ platformio install PLATFORM
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    Installing .....
+    [ ... ]
+    The platform 'PLATFORM' has been successfully installed!
+
+
+Initialize new PlatformIO based project
+
+.. code-block:: bash
+
+    $ cd /path/to/empty/directory
+    $ platformio init
+    Project has been initialized!
+    Please put your source code to `src` directory, external libraries to `lib`
+    and setup environments in `platformio.ini` file.
+    Then process project with `platformio run` command.
+
+
+Setup environments in ``platformio.ini``. For more examples go to
+:ref:`projectconf`
+
+.. code-block:: ini
+
+    # Simple and base environment
+    [env:mybaseenv]
+    platform = %INSTALLED_PLATFORM_NAME_HERE%
+
+
+Process the project's environments
+
+.. code-block:: bash
+
+    $ platformio run
+
+    # if embedded project then upload firmware
+    $ platformio run --target upload
+
+    # clean project
+    $ platformio run --target clean
+
+
+Further examples can be found in the ``examples/`` directory in the source
+distribution or `on the web <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
+
+Also, for more detailed information as for commands please go to
+:ref:`userguide` sections.

docs/userguide/cmd_init.rst

@@ -0,0 +1,42 @@
+.. _cmd_init:
+
+platformio init
+===============
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio init
+
+
+Description
+-----------
+
+Initialize new PlatformIO based project.
+
+
+This command will create:
+
+* ``.pioenvs`` - a temporary working directory.
+* ``lib`` - a directory for project specific libraries. PlatformIO will
+  compile them to static libraries and link to executable file
+* ``src`` - a source directory. Put your source code here.
+* :ref:`projectconf`
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    # Change directory to the future project
+    $ cd /path/to/empty/directory
+    $ platformio init
+    Project has been initialized!
+    Please put your source code to `src` directory, external libraries to `lib`
+    and setup environments in `platformio.ini` file.
+    Then process project with `platformio run` command.

docs/userguide/cmd_install.rst

@@ -0,0 +1,76 @@
+.. _cmd_install:
+
+platformio install
+==================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio install [OPTIONS] [PLATFORMS]
+
+
+Description
+-----------
+
+Install pre-built development :ref:`Platforms <platforms>` with related
+packages.
+
+There are several predefined aliases for packages, such as:
+
+* ``toolchain``
+* ``uploader``
+
+
+Options
+-------
+
+.. option::
+    --with-package
+
+Install specified package (or alias)
+
+
+.. option::
+    --without-package
+
+Do not install specified package (or alias)
+
+.. option::
+    --skip-default
+
+Skip default packages
+
+Examples
+--------
+
+1. Install :ref:`platform_timsp430` with default packages
+
+.. code-block:: bash
+
+    $ platformio install timsp430
+    Installing toolchain-timsp430 package:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    Installing tool-mspdebug package:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    Installing framework-energiamsp430 package:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    The platform 'timsp430' has been successfully installed!
+
+
+2. Install :ref:`platform_timsp430` with ``uploader`` utility only and skip
+   default packages
+
+.. code-block:: bash
+
+    $ platformio install timsp430 --skip-default-package --with-package=uploader
+    Installing tool-mspdebug package:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    The platform 'timsp430' has been successfully installed!

docs/userguide/cmd_list.rst

@@ -0,0 +1,30 @@
+.. _cmd_list:
+
+platformio list
+===============
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio list
+
+
+Description
+-----------
+
+List installed :ref:`Platforms <platforms>`
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio list
+    timsp430    with packages: toolchain-timsp430, tool-mspdebug, framework-energiamsp430
+    atmelavr    with packages: toolchain-atmelavr, tool-avrdude, framework-arduinoavr
+    titiva      with packages: toolchain-gccarmnoneeabi, tool-lm4flash, framework-energiativa

docs/userguide/cmd_run.rst

@@ -0,0 +1,130 @@
+.. _cmd_run:
+
+platformio run
+==============
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio run [OPTIONS]
+
+
+Description
+-----------
+
+Process environments which are defined in :ref:`projectconf` file
+
+
+Options
+-------
+
+.. option::
+    -e, --environment
+
+Process specified environments
+
+
+.. option::
+    -t, --target
+
+Process specified targets
+
+.. option::
+    --upload-port
+
+Upload port of embedded board. To print all available ports use
+:ref:`cmd_serialports` command
+
+Examples
+--------
+
+1. Process `Wiring Blink Example <https://github.com/ivankravets/platformio/tree/develop/examples/wiring-blink>`_
+
+.. code-block::   bash
+
+    $ platformio run
+    Processing arduino_pro5v environment:
+    scons: `.pioenvs/arduino_pro5v/firmware.elf' is up to date.
+    scons: `.pioenvs/arduino_pro5v/firmware.hex' is up to date.
+
+    Processing launchpad_msp430g2 environment:
+    scons: `.pioenvs/launchpad_msp430g2/firmware.elf' is up to date.
+    scons: `.pioenvs/launchpad_msp430g2/firmware.hex' is up to date.
+
+    Processing launchpad_lm4f120 environment:
+    scons: `.pioenvs/launchpad_lm4f120/firmware.elf' is up to date.
+    scons: `.pioenvs/launchpad_lm4f120/firmware.hex' is up to   date
+
+
+2. Process specific environment
+
+.. code-block:: bash
+
+    $ platformio run -e arduino_pro5v -e launchpad_lm4f120
+    Processing arduino_pro5v environment:
+    scons: `.pioenvs/arduino_pro5v/firmware.elf' is up to date.
+    scons: `.pioenvs/arduino_pro5v/firmware.hex' is up to date.
+
+    Processing launchpad_lm4f120 environment:
+    scons: `.pioenvs/launchpad_lm4f120/firmware.elf' is up to date.
+    scons: `.pioenvs/launchpad_lm4f120/firmware.hex' is up to date.
+
+
+3. Process specific target
+
+.. code-block:: bash
+
+    $ platformio run -t clean
+    Processing arduino_pro5v environment:
+    Removed .pioenvs/arduino_pro5v/src/main.o
+    ...
+    Removed .pioenvs/arduino_pro5v/firmware.hex
+
+    Processing launchpad_msp430g2 environment:
+    Removed .pioenvs/launchpad_msp430g2/src/main.o
+    ...
+    Removed .pioenvs/launchpad_msp430g2/firmware.hex
+
+    Processing launchpad_lm4f120 environment:
+    Removed .pioenvs/launchpad_lm4f120/src/main.o
+    ...
+    Removed .pioenvs/launchpad_lm4f120/firmware.hex
+
+
+4. Mix environments and targets
+
+.. code-block:: bash
+
+    $ platformio run -e launchpad_msp430g2 -t upload
+    Processing launchpad_msp430g2 environment:
+    /Users/ikravets/.platformio/timsp430/tools/mspdebug/mspdebug rf2500 --force-reset "prog .pioenvs/launchpad_msp430g2/firmware.hex"
+    MSPDebug version 0.20 - debugging tool for MSP430 MCUs
+    Copyright (C) 2009-2012 Daniel Beer <dlbeer@gmail.com>
+    This is free software; see the source for copying conditions.  There is NO
+    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+    Trying to open interface 1 on 009
+    Initializing FET...
+    FET protocol version is 30394216
+    Configured for Spy-Bi-Wire
+    Sending reset...
+    Set Vcc: 3000 mV
+    Device ID: 0x2553
+      Code start address: 0xc000
+      Code size         : 16384 byte = 16 kb
+      RAM  start address: 0x200
+      RAM  end   address: 0x3ff
+      RAM  size         : 512 byte = 0 kb
+    Device: MSP430G2553/G2403
+    Code memory starts at 0xc000
+    Number of breakpoints: 2
+    Chip ID data: 25 53
+    Erasing...
+    Programming...
+    Writing  646 bytes at c000...
+    Writing   32 bytes at ffe0...
+    Done, 678 bytes total

docs/userguide/cmd_search.rst

@@ -0,0 +1,42 @@
+.. _cmd_search:
+
+platformio search
+=================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    # Print all available development platforms
+    platformio search all
+
+    # Filter platforms by "Query"
+    platformio search QUERY
+
+
+Description
+-----------
+
+Search for development :ref:`Platforms <platforms>`
+
+
+Examples
+--------
+
+1. Search for TI development platforms
+
+.. code-block:: bash
+
+    $ platformio search ti
+    timsp430 - An embedded platform for TI MSP430 microcontrollers (with Energia Framework)
+    titiva   - An embedded platform for TI TIVA C ARM microcontrollers (with Energia Framework)
+
+2. Search for development platforms which support "Arduino Framework"
+
+.. code-block:: bash
+
+    $ platformio search arduino
+    atmelavr - An embedded platform for Atmel AVR microcontrollers (with Arduino Framework)

docs/userguide/cmd_serialports.rst

@@ -0,0 +1,243 @@
+.. _cmd_serialports:
+
+platformio serialports
+======================
+
+.. contents::
+
+platformio serialports list
+---------------------------
+
+Usage
+~~~~~
+
+.. code-block:: bash
+
+    platformio serialports list
+
+
+Description
+~~~~~~~~~~~
+
+List available `Serial Ports <http://en.wikipedia.org/wiki/Serial_port>`_
+
+
+Examples
+~~~~~~~~
+
+1. Unix OS
+
+.. code-block:: bash
+
+    $ platformio serialports list
+    /dev/cu.SLAB_USBtoUART
+    ----------
+    Hardware ID: USB VID:PID=10c4:ea60 SNR=0001
+    Description: CP2102 USB to UART Bridge Controller
+
+    /dev/cu.uart-1CFF4676258F4543
+    ----------
+    Hardware ID: USB VID:PID=451:f432 SNR=1CFF4676258F4543
+    Description: Texas Instruments MSP-FET430UIF
+
+
+2. Windows OS
+
+.. code-block:: bash
+
+    $ platformio serialports list
+    COM4
+    ----------
+    Hardware ID: USB VID:PID=0451:F432
+    Description: MSP430 Application UART (COM4)
+
+    COM3
+    ----------
+    Hardware ID: USB VID:PID=10C4:EA60 SNR=0001
+    Description: Silicon Labs CP210x USB to UART Bridge (COM3)
+
+
+platformio serialports monitor
+------------------------------
+
+Usage
+~~~~~
+
+.. code-block:: bash
+
+    platformio serialports monitor [OPTIONS]
+
+
+Description
+~~~~~~~~~~~
+
+This is a console application that provides a small terminal
+application. It is based on `Miniterm <http://pyserial.sourceforge.net/examples.html#miniterm>`_
+and itself does not implement any terminal features such
+as *VT102* compatibility. However it inherits these features from the terminal
+it is run. For example on GNU/Linux running from an *xterm* it will support the
+escape sequences of the *xterm*. On *Windows* the typical console window is dumb
+and does not support any escapes. When *ANSI.sys* is loaded it supports some
+escapes.
+
+To control *monitor* please use these "hot keys":
+
+* ``Ctrl+]`` Quit
+* ``Ctrl+T`` Menu
+* ``Ctrl+T followed by Ctrl+H`` Help
+
+Options
+~~~~~~~
+
+.. option::
+    -p, --port
+
+Port, a number or a device name
+
+.. option::
+    -b, --baud
+
+Set baud rate, default ``9600``
+
+.. option::
+    --parity
+
+Set parity (*None, Even, Odd, Space, Mark*), one of
+[``N``, ``E``, ``O``, ``S``, ``M``], default ``N``
+
+.. option::
+    --rtscts
+
+Enable ``RTS/CTS`` flow control, default ``Off``
+
+.. option::
+    --xonxoff
+
+Enable software flow control, default ``Off``
+
+.. option::
+    --rts
+
+Set initial ``RTS`` line state, default ``0``
+
+.. option::
+    --dtr
+
+Set initial ``DTR`` line state, default ``0``
+
+.. option::
+    --echo
+
+Enable local echo, default ``Off``
+
+.. option::
+    --cr
+
+Do not send ``CR+LF``, send ``R`` only, default ``Off``
+
+.. option::
+    --lf
+
+Do not send ``CR+LF``, send ``LF`` only, default ``Off``
+
+.. option::
+    -d, --debug
+
+Debug received data (escape non-printable chars). ``--debug`` can be given
+multiple times:
+
+0. just print what is received
+1. escape non-printable characters, do newlines as unusual
+2. escape non-printable characters, newlines too
+3. hex dump everything
+
+.. option::
+    --exit-char
+
+ASCII code of special character that is used to exit the application,
+default ``0x1d``
+
+.. option::
+    --menu-char
+
+ASCII code of special character that is used to control miniterm (menu),
+default ``0x14``
+
+.. option::
+    ---quiet
+
+Diagnostics: suppress non-error messages, default ``Off``
+
+Examples
+~~~~~~~~
+
+1. Show available options for *monitor*
+
+.. code-block:: bash
+
+    $ platformio serialports monitor --help
+    Usage: platformio serialports monitor [OPTIONS]
+
+    Options:
+      -p, --port TEXT       Port, a number or a device name
+      -b, --baud INTEGER    Set baud rate, default=9600
+      --parity [N|E|O|S|M]  Set parity, default=N
+      --rtscts              Enable RTS/CTS flow control, default=Off
+      --xonxoff             Enable software flow control, default=Off
+      --rts [0|1]           Set initial RTS line state, default=0
+      --dtr [0|1]           Set initial DTR line state, default=0
+      --echo                Enable local echo, default=Off
+      --cr                  Do not send CR+LF, send CR only, default=Off
+      --lf                  Do not send CR+LF, send LF only, default=Off
+      -d, --debug           Debug received data (escape non-printable chars)
+                            --debug can be given multiple times:
+                            0: just print what is received
+                            1: escape non-printable characters, do newlines as
+                               unusual
+                            2: escape non-printable characters, newlines too
+                            3: hex dump everything
+      --exit-char INTEGER   ASCII code of special character that is used to exit
+                            the application, default=0x1d
+      --menu-char INTEGER   ASCII code of special character that is used to
+                            control miniterm (menu), default=0x14
+      --quiet               Diagnostics: suppress non-error messages, default=Off
+      --help                Show this message and exit.
+
+2. Communicate with serial device and print help inside terminal
+
+.. code-block:: bash
+
+    $ platformio serialports monitor
+
+    --- Available ports:
+    --- /dev/cu.Bluetooth-Incoming-Port n/a
+    --- /dev/cu.Bluetooth-Modem n/a
+    --- /dev/cu.SLAB_USBtoUART CP2102 USB to UART Bridge Controller
+    --- /dev/cu.obd2ecu-SPPDev n/a
+    Enter port name:/dev/cu.SLAB_USBtoUART
+    --- Miniterm on /dev/cu.SLAB_USBtoUART: 9600,8,N,1 ---
+    --- Quit: Ctrl+]  |  Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
+    Hello PlatformIO!
+    --- pySerial (2.7) - miniterm - help
+    ---
+    --- Ctrl+]   Exit program
+    --- Ctrl+T   Menu escape key, followed by:
+    --- Menu keys:
+    ---    Ctrl+T  Send the menu character itself to remote
+    ---    Ctrl+]  Send the exit character itself to remote
+    ---    Ctrl+I  Show info
+    ---    Ctrl+U  Upload file (prompt will be shown)
+    --- Toggles:
+    ---    Ctrl+R  RTS          Ctrl+E  local echo
+    ---    Ctrl+D  DTR          Ctrl+B  BREAK
+    ---    Ctrl+L  line feed    Ctrl+A  Cycle repr mode
+    ---
+    --- Port settings (Ctrl+T followed by the following):
+    ---    p          change port
+    ---    7 8        set data bits
+    ---    n e o s m  change parity (None, Even, Odd, Space, Mark)
+    ---    1 2 3      set stop bits (1, 2, 1.5)
+    ---    b          change baud rate
+    ---    x X        disable/enable software flow control
+    ---    r R        disable/enable hardware flow control
+    --- exit ---

docs/userguide/cmd_show.rst

@@ -0,0 +1,42 @@
+.. _cmd_show:
+
+platformio show
+===============
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio show PLATFORM
+
+
+Description
+-----------
+
+Show details about the installed :ref:`Platforms <platforms>`
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio show atmelavr
+    atmelavr    - An embedded platform for Atmel AVR microcontrollers (with Arduino Framework)
+    ----------
+    Package: toolchain-atmelavr
+    Alias: toolchain
+    Location: /Users/ikravets/.platformio/atmelavr/tools/toolchain
+    Version: 1
+    ----------
+    Package: tool-avrdude
+    Alias: uploader
+    Location: /Users/ikravets/.platformio/atmelavr/tools/avrdude
+    Version: 1
+    ----------
+    Package: framework-arduinoavr
+    Location: /Users/ikravets/.platformio/atmelavr/frameworks/arduino
+    Version: 1

docs/userguide/cmd_uninstall.rst

@@ -0,0 +1,31 @@
+.. _cmd_uninstall:
+
+platformio uninstall
+====================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio uninstall PLATFORM
+
+
+Description
+-----------
+
+Uninstall specified :ref:`Platforms <platforms>`
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio uninstall timsp430
+    Uninstalling toolchain-timsp430 package:        [OK]
+    Uninstalling tool-mspdebug package:             [OK]
+    Uninstalling framework-energiamsp430 package:   [OK]
+    The platform 'timsp430' has been successfully uninstalled!

docs/userguide/cmd_update.rst

@@ -0,0 +1,54 @@
+.. _cmd_update:
+
+platformio update
+=================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio update
+
+
+Description
+-----------
+
+Check or update installed :ref:`Platforms <platforms>`
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio update
+
+    Platform atmelavr
+    --------
+    Updating toolchain-atmelavr package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+    Updating framework-arduinoavr package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+    Updating tool-avrdude package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+
+    Platform timsp430
+    --------
+    Updating toolchain-timsp430 package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+    Updating tool-mspdebug package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+    Updating framework-energiamsp430 package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+
+    Platform titiva
+    --------
+    Updating toolchain-gccarmnoneeabi package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+    Updating tool-lm4flash package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]
+    Updating framework-energiativa package:
+    Versions: Current=1, Latest=1 	 [Up-to-date]

docs/userguide/cmd_upgrade.rst

@@ -0,0 +1,32 @@
+.. _cmd_upgrade:
+
+platformio upgrade
+==================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio upgrade
+
+
+Description
+-----------
+
+Check or upgrade PlatformIO to the latest version
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio upgrade
+    You're up-to-date!
+    PlatformIO x.x.x is currently the newest version available.
+
+    # If you have problem with permissions try:
+    $ sudo platformio upgrade

docs/userguide/index.rst

@@ -0,0 +1,27 @@
+.. _userguide:
+
+User Guide
+==========
+
+To print all available commands and options use:
+
+.. code-block:: bash
+
+    $ platformio --help
+    $ platformio COMMAND --help
+
+
+.. toctree::
+    :maxdepth: 2
+
+    cmd_init
+    cmd_install
+    platformio lib <lib/index>
+    cmd_list
+    cmd_run
+    cmd_search
+    cmd_serialports
+    cmd_show
+    cmd_uninstall
+    cmd_update
+    cmd_upgrade

docs/userguide/lib/cmd_install.rst

@@ -0,0 +1,68 @@
+.. _cmd_lib_install:
+
+platformio lib install
+======================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio lib install [OPTIONS] [NAMES]
+
+
+Description
+-----------
+
+Install new library
+
+Options
+-------
+
+.. option::
+    -v, --version
+
+Install specified version of library
+
+
+Examples
+--------
+
+1. Install the latest version of library
+
+.. code-block:: bash
+
+    $ platformio lib install Arduino-IRremote
+    Installing Arduino-IRremote library:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    The library 'Arduino-IRremote' has been successfully installed!
+
+
+2. Install specified version of library
+
+.. code-block:: bash
+
+    $ platformio lib install Arduino-XBee --version=0.5
+    Installing Arduino-XBee library:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    The library 'Arduino-XBee' has been successfully installed!
+
+
+3. Install library with dependencies
+
+.. code-block:: bash
+
+    $ platformio lib install Adafruit-Arduino-ST7735
+    Installing Adafruit-Arduino-ST7735 library:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    The library 'Adafruit-Arduino-ST7735' has been successfully installed!
+    Installing dependencies:
+    Installing Adafruit-Arduino-GFX library:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    The library 'Adafruit-Arduino-GFX' has been successfully installed!

docs/userguide/lib/cmd_list.rst

@@ -0,0 +1,31 @@
+.. _cmd_lib_list:
+
+platformio lib list
+===================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio lib list
+
+
+Description
+-----------
+
+List installed libraries
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio lib list
+    Arduino-IRremote      Send and receive infrared signals with multiple protocols
+    ...
+    Arduino-Webduino      An extensible web server library (for use with the Arduino Ethernet Shield)
+    Arduino-XBee          Arduino library for communicating with XBees in API mode

docs/userguide/lib/cmd_register.rst

@@ -0,0 +1,26 @@
+.. _cmd_lib_register:
+
+platformio lib register
+=======================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio lib regiter [HTTP_URL_TO_LIBRARY.JSON]
+
+
+Description
+-----------
+
+Register new library and allow others to install it.
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio lib register http://my.example.com/library.json

docs/userguide/lib/cmd_search.rst

@@ -0,0 +1,136 @@
+.. _cmd_lib_search:
+
+platformio lib search
+=====================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio lib search [OPTIONS] [QUERY]
+
+
+Description
+-----------
+
+Search for library over ``name``, ``description`` and ``keywords`` fields from
+the :ref:`library_config` file in the boolean mode.
+
+The boolean search capability supports the following operators:
+
+.. list-table::
+    :header-rows:  1
+
+    * - Operator
+      - Description
+    * - ``+``
+      - A leading or trailing plus sign indicates that this word must be present
+        in library fields (see above) that is returned.
+    * - ``-``
+      - A leading or trailing minus sign indicates that this word must not be
+        present in any of the libraries that are returned.
+    * - ``(no operator)``
+      - By default (when neither ``+`` nor ``-`` is specified), the
+        word is optional, but the libraries that contain it are rated higher.
+    * - ``> <``
+      - These two operators are used to change a word's contribution to the
+        relevance value that is assigned to a library. The ``>`` operator
+        increases the contribution and the ``<`` operator decreases it.
+    * - ``( )``
+      - Parentheses group words into subexpressions. Parenthesized groups can
+        be nested.
+    * - ``~``
+      - A leading tilde acts as a negation operator, causing the word's
+        contribution to the library's relevance to be negative. This is useful for
+        marking "noise" words. A library containing such a word is rated lower than
+        others, but is not excluded altogether, as it would be with the ``-`` operator.
+    * - ``*``
+      - The asterisk serves as the truncation (or wildcard) operator. Unlike the
+        other operators, it is appended to the word to be affected. Words match if
+        they begin with the word preceding the ``*`` operator.
+    * - ``"``
+      - A phrase that is enclosed within double quote (``"``) characters matches
+        only libraries that contain the phrase literally, as it was typed.
+
+For more detail information please go to
+`MySQL Boolean Full-Text Searches <http://dev.mysql.com/doc/refman/5.6/en/fulltext-boolean.html>`_.
+
+Options
+-------
+
+.. option::
+    -a, --author
+
+Filter libraries by specified author
+
+.. option::
+    -k, --keyword
+
+Filter libraries by specified keyword
+
+Examples
+--------
+
+1. Search for "1-Wire" library
+
+.. code-block:: bash
+
+    $ platformio lib search 1-wire
+    Found N libraries:
+    Arduino-OneWire       Control devices (from Dallas Semiconductor) that use the One Wire protocol
+    ...
+
+2. Search for Arduino-based "I2C" libraries. The ``+`` sign is here like ``AND``
+   operator.
+
+.. code-block:: bash
+
+    $ platformio lib search "+i2c +arduino"
+    Found N libraries:
+    i2cdevlib-Arduino-i2cdev The I2C Device Library (i2cdevlib) is a collection of uniform and well-documented classes to provide simple and intuitive interfaces to I2C devices.
+    i2cdevlib-Arduino-AK8975 AK8975 is 3-axis electronic compass IC with high sensitive Hall sensor technology
+    ...
+
+3. Search for libraries by "web" and "http" keywords. The ``""`` here is for
+   "empty" query argument.
+
+.. code-block:: bash
+
+    $ platformio lib search "" --keyword web --keyword http
+    Found N libraries:
+    Arduino-Webduino      An extensible web server library (for use with the Arduino Ethernet Shield)
+    Arduino-aJson         An Arduino library to enable JSON processing with Arduino
+    ...
+
+4. Search for libraries from "Adafruit Industries" author.
+
+.. code-block:: bash
+
+    $ platformio lib search "" --author "Adafruit Industries"
+    Found N libraries:
+    Adafruit-Arduino-ST7735 A library for the Adafruit 1.8" SPI display
+    Adafruit-Arduino-GFX  A core graphics library for all our displays, providing a common set of graphics primitives (points, lines, circles, etc.)
+    ...
+
+5. Search for libraries that are compatible with Dallas temperature sensors
+   like DS18B20, DS18S20 and etc.
+
+.. code-block:: bash
+
+    $ platformio lib search "DS*"
+    Found N libraries:
+    Arduino-OneWire       Control devices (from Dallas Semiconductor) that use the One Wire protocol
+    ...
+
+6. Search for Arduino-based *X10* or *XBee* libraries. The search query that is
+   described below can be interpreted like ``arduino x10 OR arduino xbee``.
+
+.. code-block:: bash
+
+    $ platformio lib search "+arduino +(x10 xbee)"
+    Found 2 libraries:
+    Arduino-X10           Sending X10 signals over AC power lines
+    Arduino-XBee          Arduino library for communicating with XBees in API mode

docs/userguide/lib/cmd_show.rst

@@ -0,0 +1,34 @@
+.. _cmd_lib_show:
+
+platformio lib show
+===================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio lib show NAME
+
+
+Description
+-----------
+
+Show details about the installed library
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio lib show Arduino-XBee
+    Arduino-XBee
+    ------------
+    Author: Andrew Rapp <andrew.rapp@gmail.com>
+    Keywords: xbee, protocol, radio
+    Version: 0.5
+
+    Arduino library for communicating with XBees in API mode

docs/userguide/lib/cmd_uninstall.rst

@@ -0,0 +1,31 @@
+.. _cmd_lib_uninstall:
+
+platformio lib uninstall
+========================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio lib uninstall NAME
+
+
+Description
+-----------
+
+Uninstall specified library
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio lib install Arduino-IRremote
+    Installing Arduino-IRremote library:
+    Downloading  [####################################]  100%
+    Unpacking  [####################################]  100%
+    The library 'Arduino-IRremote' has been successfully installed!

docs/userguide/lib/cmd_update.rst

@@ -0,0 +1,33 @@
+.. _cmd_lib_update:
+
+platformio lib update
+=====================
+
+.. contents::
+
+Usage
+-----
+
+.. code-block:: bash
+
+    platformio lib update
+
+
+Description
+-----------
+
+Check or update installed libraries
+
+
+Examples
+--------
+
+.. code-block:: bash
+
+    $ platformio lib update
+    Updating Arduino-IRremote library:
+    Versions: Current=24ba950f5c, Latest=24ba950f5c     [Up-to-date]
+    Updating Arduino-Webduino library:
+    Versions: Current=3631af8e02, Latest=3631af8e02     [Up-to-date]
+    Updating Arduino-XBee library:
+    Versions: Current=0.5, Latest=0.5                   [Up-to-date]

docs/userguide/lib/index.rst

@@ -0,0 +1,23 @@
+.. _userguide_lib:
+
+Library Manager
+===============
+
+To print all available commands and options use:
+
+.. code-block:: bash
+
+    $ platformio lib --help
+    $ platformio lib COMMAND --help
+
+
+.. toctree::
+    :maxdepth: 2
+
+    cmd_install
+    cmd_list
+    cmd_register
+    cmd_search
+    cmd_show
+    cmd_uninstall
+    cmd_update

platformio/__init__.py

@@ -1,17 +1,18 @@
 # Copyright (C) Ivan Kravets <me@ikravets.com>
 # See LICENSE for details.
 
-VERSION = (0, 5, 0)
+VERSION = (0, 7, 0)
 __version__ = ".".join([str(s) for s in VERSION])
 
 __title__ = "platformio"
 __description__ = ("A cross-platform code builder and library manager")
-__url__ = "https://github.com/ivankravets/platformio"
+__url__ = "http://platformio.ikravets.com"
 
 __author__ = "Ivan Kravets"
 __email__ = "me@ikravets.com"
 
-__license__ = "MIT Licence"
+__license__ = "MIT License"
 __copyright__ = "Copyright (C) 2014 Ivan Kravets"
 
-__pkgmanifesturl__ = "http://platformio.ikravets.com/packages/manifest.json"
+__apiurl__ = "http://api.platformio.ikravets.com"
+__pkgmanifesturl__ = "http://dl.platformio.ikravets.com/packages/manifest.json"

platformio/__main__.py

@@ -15,7 +15,7 @@ from platformio.exception import PlatformioException, UnknownCLICommand
 from platformio.util import get_home_dir, get_source_dir
 
 
-class PlatformioCLI(MultiCommand):
+class PlatformioCLI(MultiCommand):  # pylint: disable=R0904
 
     def list_commands(self, ctx):
         cmds = []

platformio/builder/main.py

@@ -1,12 +1,22 @@
 # Copyright (C) Ivan Kravets <me@ikravets.com>
 # See LICENSE for details.
 
+try:
+    from platformio.util import get_home_dir
+except ImportError:
+    import sys
+    for _path in sys.path:
+        if "platformio" in _path:
+            sys.path.insert(0, _path[:_path.rfind("platformio")-1])
+            break
+    from platformio.util import get_home_dir
+
 from os.path import isdir, join
 
 from SCons.Script import (DefaultEnvironment, Exit, SConscript,
                           SConscriptChdir, Variables)
 
-from platformio.util import (get_home_dir, get_pioenvs_dir, get_project_dir,
+from platformio.util import (get_lib_dir, get_pioenvs_dir, get_project_dir,
                              get_source_dir)
 
 # AllowSubstExceptions()
@@ -48,6 +58,7 @@ DefaultEnvironment(
     BUILD_DIR=join("$PIOENVS_DIR", "$PIOENV"),
     LIBSOURCE_DIRS=[
         join("$PROJECT_DIR", "lib"),
+        get_lib_dir(),
         join("$PLATFORMFW_DIR", "libraries"),
     ]
 )

platformio/builder/tools/platformio.py

@@ -165,8 +165,9 @@ def ConvertInotoCpp(env):
             remove(f)
 
     tmpcpp = []
-
-    for item in env.Glob(join("$PROJECT_DIR", "src", "*.ino")):
+    items = (env.Glob(join("$PROJECT_DIR", "src", "*.ino")) +
+             env.Glob(join("$PROJECT_DIR", "src", "*.pde")))
+    for item in items:
         cppfile = item.get_path()[:-3] + "cpp"
         if isfile(cppfile):
             continue
@@ -177,7 +178,7 @@ def ConvertInotoCpp(env):
             r"""^(
             (?:\s*[a-z_\d]+){1,2}       # return type
             \s+[a-z_\d]+\s*             # name of prototype
-            \([a-z_,\.\*\&\s\d]+\)      # args
+            \([a-z_,\.\*\&\[\]\s\d]*\)  # args
             )\s*\{                      # must end with {
             """,
             re.X | re.M | re.I

platformio/commands/lib.py

@@ -0,0 +1,173 @@
+# Copyright (C) Ivan Kravets <me@ikravets.com>
+# See LICENSE for details.
+
+import click
+
+from platformio.exception import LibAlreadyInstalledError
+from platformio.libmanager import LibraryManager
+from platformio.util import get_api_result, get_lib_dir
+
+
+@click.group(short_help="Library Manager")
+def cli():
+    pass
+
+
+@cli.command("search", short_help="Search for library")
+@click.option("-a", "--author", multiple=True)
+@click.option("-k", "--keyword", multiple=True)
+@click.argument("query")
+def lib_search(query, author, keyword):
+    for key, values in dict(author=author, keyword=keyword).iteritems():
+        for value in values:
+            query += ' %s:"%s"' % (key, value)
+
+    result = get_api_result("/lib/search", dict(query=query))
+    click.secho("Found %d libraries:" % result['total'],
+                fg="green" if result['total'] else "yellow")
+
+    while True:
+        for item in result['items']:
+            click.echo("{name:<30} {description}".format(
+                name=click.style(item['name'], fg="cyan"),
+                description=item['description']
+            ))
+
+        if int(result['page'])*int(result['perpage']) >= int(result['total']):
+            break
+
+        if click.confirm("Show next libraries?"):
+            result = get_api_result(
+                "/lib/search",
+                dict(query=query, page=str(int(result['page']) + 1))
+            )
+        else:
+            break
+
+
+@cli.command("install", short_help="Install library")
+@click.argument("names", nargs=-1)
+@click.option("-v", "--version")
+def lib_install_cli(names, version):
+    lib_install(names, version)
+
+
+def lib_install(names, version=None):
+    lm = LibraryManager(get_lib_dir())
+    for name in names:
+        click.echo("Installing %s library:" % click.style(name, fg="cyan"))
+        try:
+            if lm.install(name, version):
+                click.secho(
+                    "The library '%s' has been successfully installed!" %
+                    name, fg="green")
+                info = lm.get_info(name)
+                if "dependencies" in info:
+                    click.secho("Installing dependencies:", fg="yellow")
+                    lib_install(info['dependencies'])
+
+        except LibAlreadyInstalledError:
+            click.secho("Already installed", fg="yellow")
+
+
+@cli.command("uninstall", short_help="Uninstall libraries")
+@click.argument("names", nargs=-1)
+def lib_uninstall_cli(names):
+    lib_uninstall(names)
+
+
+def lib_uninstall_dependency(dependency):
+    lm = LibraryManager(get_lib_dir())
+
+    for name in lm.get_installed():
+        info = lm.get_info(name)
+        if dependency in info.get("dependencies", []):
+            return
+
+    lib_uninstall([dependency])
+
+
+def lib_uninstall(names):
+    lm = LibraryManager(get_lib_dir())
+    for name in names:
+        info = lm.get_info(name)
+        if lm.uninstall(name):
+            # find dependencies
+            if "dependencies" in info:
+                for d in info['dependencies']:
+                    lib_uninstall_dependency(d)
+
+            click.secho("The library '%s' has been successfully "
+                        "uninstalled!" % name, fg="green")
+
+
+@cli.command("list", short_help="List installed libraries")
+def lib_list():
+    lm = LibraryManager(get_lib_dir())
+    for name in lm.get_installed():
+        info = lm.get_info(name)
+        click.echo("{name:<30} {description}".format(
+            name=click.style(info['name'], fg="cyan"),
+            description=info['description']
+        ))
+
+
+@cli.command("show", short_help="Show details about installed libraries")
+@click.argument("name")
+def lib_show(name):
+    lm = LibraryManager(get_lib_dir())
+    info = lm.get_info(name)
+    click.secho(info['name'], fg="cyan")
+    click.echo("-" * len(info['name']))
+
+    if "author" in info:
+        _data = []
+        for k in ("name", "email"):
+            if k in info['author'] and info['author'][k] is not None:
+                _value = info['author'][k]
+                if k == "email":
+                    _value = "<%s>" % _value
+                _data.append(_value)
+        click.echo("Author: %s" % " ".join(_data))
+
+    click.echo("Keywords: %s" % info['keywords'])
+    click.echo("Version: %s" % info['version'])
+    click.echo()
+    click.echo(info['description'])
+    click.echo()
+
+
+@cli.command("update", short_help="Update installed libraries")
+def lib_update():
+    lm = LibraryManager(get_lib_dir())
+    lib_names = lm.get_installed()
+    versions = get_api_result("/lib/version/" + ",".join(lib_names))
+
+    for name in lib_names:
+        info = lm.get_info(name)
+
+        click.echo("Updating %s library:" % click.style(name, fg="yellow"))
+
+        current_version = info['version']
+        latest_version = versions[name]
+
+        click.echo("Versions: Current=%s, Latest=%s \t " % (
+            current_version, latest_version), nl=False)
+
+        if current_version == latest_version:
+            click.echo("[%s]" % (click.style("Up-to-date", fg="green")))
+            continue
+        else:
+            click.echo("[%s]" % (click.style("Out-of-date", fg="red")))
+
+        lib_uninstall([name])
+        lib_install([name])
+
+
+@cli.command("register", short_help="Register new library")
+@click.argument("config_url")
+def lib_register(config_url):
+    result = get_api_result("/lib/register", data=dict(config_url=config_url))
+    if "message" in result and result['message']:
+        click.secho(result['message'], fg="green" if "successed" in result and
+                    result['successed'] else "red")

platformio/commands/serialports.py

@@ -1,13 +1,21 @@
 # Copyright (C) Ivan Kravets <me@ikravets.com>
 # See LICENSE for details.
 
-from click import command, echo, secho
+import sys
+
+from click import Choice, echo, group, option, secho
+from serial.tools import miniterm
 
 from platformio.util import get_serialports
 
 
-@command("serialports", short_help="List Serial ports")
+@group(short_help="List or Monitor Serial ports")
 def cli():
+    pass
+
+
+@cli.command("list", short_help="List Serial ports")
+def serialports_list():
 
     for item in get_serialports():
         secho(item['port'], fg="cyan")
@@ -15,3 +23,46 @@ def cli():
         echo("Hardware ID: %s" % item['hwid'])
         echo("Description: %s" % item['description'])
         echo("")
+
+
+@cli.command("monitor", short_help="Monitor Serial port")
+@option("--port", "-p", help="Port, a number or a device name")
+@option("--baud", "-b", type=int, default=9600,
+        help="Set baud rate, default=9600")
+@option("--parity", default="N", type=Choice(["N", "E", "O", "S", "M"]),
+        help="Set parity, default=N")
+@option("--rtscts", is_flag=True,
+        help="Enable RTS/CTS flow control, default=Off")
+@option("--xonxoff", is_flag=True,
+        help="Enable software flow control, default=Off")
+@option("--rts", default="0", type=Choice(["0", "1"]),
+        help="Set initial RTS line state, default=0")
+@option("--dtr", default="0", type=Choice(["0", "1"]),
+        help="Set initial DTR line state, default=0")
+@option("--echo", is_flag=True,
+        help="Enable local echo, default=Off")
+@option("--cr", is_flag=True,
+        help="Do not send CR+LF, send CR only, default=Off")
+@option("--lf", is_flag=True,
+        help="Do not send CR+LF, send LF only, default=Off")
+@option("--debug", "-d", count=True,
+        help="""Debug received data (escape non-printable chars)
+# --debug can be given multiple times:
+# 0: just print what is received
+# 1: escape non-printable characters, do newlines as unusual
+# 2: escape non-printable characters, newlines too
+# 3: hex dump everything""")
+@option("--exit-char", type=int, default=0x1d,
+        help="ASCII code of special character that is used to exit the "
+        "application, default=0x1d")
+@option("--menu-char", type=int, default=0x14,
+        help="ASCII code of special character that is used to control "
+        "miniterm (menu), default=0x14")
+@option("--quiet", is_flag=True,
+        help="Diagnostics: suppress non-error messages, default=Off")
+def serialports_monitor(**_):
+    sys.argv = sys.argv[3:]
+    try:
+        miniterm.main()
+    except:  # pylint: disable=W0702
+        pass

platformio/commands/show.py

@@ -10,7 +10,7 @@ from platformio.pkgmanager import PackageManager
 from platformio.platforms.base import PlatformFactory
 
 
-@command("show", short_help="Show details about an installed platforms")
+@command("show", short_help="Show details about installed platforms")
 @argument("platform")
 def cli(platform):
     p = PlatformFactory().newPlatform(platform)

platformio/exception.py

@@ -105,3 +105,17 @@ class GetSerialPortsError(PlatformioException):
 class GetLatestVersionError(PlatformioException):
 
     MESSAGE = "Can't retrieve latest PlatformIO version"
+
+
+class APIRequestError(PlatformioException):
+
+    MESSAGE = "[API] %s"
+
+
+class LibAlreadyInstalledError(PlatformioException):
+    pass
+
+
+class LibNotInstalledError(PlatformioException):
+
+    MESSAGE = "Library '%s' has not been installed yet"

platformio/libmanager.py

@@ -0,0 +1,75 @@
+# Copyright (C) Ivan Kravets <me@ikravets.com>
+# See LICENSE for details.
+
+import json
+from os import listdir, makedirs, remove
+from os.path import isdir, isfile, join
+from shutil import rmtree
+from tempfile import gettempdir
+
+from platformio.downloader import FileDownloader
+from platformio.exception import LibAlreadyInstalledError, LibNotInstalledError
+from platformio.unpacker import FileUnpacker
+from platformio.util import get_api_result
+
+
+class LibraryManager(object):
+
+    CONFIG_NAME = "library.json"
+
+    def __init__(self, lib_dir):
+        self.lib_dir = lib_dir
+
+    @staticmethod
+    def download(url, dest_dir):
+        fd = FileDownloader(url, dest_dir)
+        fd.start()
+        return fd.get_filepath()
+
+    @staticmethod
+    def unpack(pkgpath, dest_dir):
+        fu = FileUnpacker(pkgpath, dest_dir)
+        return fu.start()
+
+    def get_installed(self):
+        items = []
+        for item in listdir(self.lib_dir):
+            conf_path = join(self.lib_dir, item, self.CONFIG_NAME)
+            if isfile(conf_path):
+                items.append(item)
+        return items
+
+    def get_info(self, name):
+        conf_path = join(self.lib_dir, name, self.CONFIG_NAME)
+        if not isfile(conf_path):
+            raise LibNotInstalledError(name)
+        with open(conf_path, "r") as f:
+            return json.load(f)
+
+    def is_installed(self, name):
+        return isfile(join(self.lib_dir, name, self.CONFIG_NAME))
+
+    def install(self, name, version=None):
+        if self.is_installed(name):
+            raise LibAlreadyInstalledError()
+
+        _lib_dir = join(self.lib_dir, name)
+        if not isdir(_lib_dir):
+            makedirs(_lib_dir)
+
+        dlinfo = get_api_result("/lib/download/" + name, dict(version=version)
+                                if version else None)
+        try:
+            dlpath = self.download(dlinfo['url'], gettempdir())
+            self.unpack(dlpath, _lib_dir)
+        finally:
+            remove(dlpath)
+
+        return self.is_installed(name)
+
+    def uninstall(self, name):
+        if self.is_installed(name):
+            rmtree(join(self.lib_dir, name))
+            return True
+        else:
+            raise LibNotInstalledError(name)

platformio/pkgmanager.py

@@ -8,8 +8,9 @@ from shutil import rmtree
 
 from click import echo, secho, style
 from requests import get
+from requests.utils import default_user_agent
 
-from platformio import __pkgmanifesturl__
+from platformio import __pkgmanifesturl__, __version__
 from platformio.downloader import FileDownloader
 from platformio.exception import (InvalidPackageVersion, NonSystemPackage,
                                   UnknownPackage)
@@ -29,7 +30,10 @@ class PackageManager(object):
         try:
             return PackageManager._cached_manifest
         except AttributeError:
-            PackageManager._cached_manifest = get(__pkgmanifesturl__).json()
+            headers = {"User-Agent": "PlatformIO/%s %s" % (
+                __version__, default_user_agent())}
+            PackageManager._cached_manifest = get(__pkgmanifesturl__,
+                                                  headers=headers).json()
         return PackageManager._cached_manifest
 
     @staticmethod

platformio/projectconftpl.ini

@@ -1,71 +1,13 @@
 # Copyright (C) Ivan Kravets <me@ikravets.com>
 # See LICENSE for details.
 
-# Please uncomment (remove "#" sign from the beginning of the line)
-# some of the environments which fit to your project.
 #
-# And replace all values that match with "%..._HERE%" by real data.
-
+# Project Configuration File
+#
+# A detailed documentation with EXAMPLES is located here:
+# http://docs.platformio.ikravets.com/en/latest/projectconf.html
+#
 
 # Simple and base environment
 #[env:mybaseenv]
 #platform = %INSTALLED_PLATFORM_NAME_HERE%
-
-# Environment with specific build flags
-#[env:specbuildflags]
-#platform = %INSTALLED_PLATFORM_NAME_HERE%
-#build_flags = "-I/opt/include -L/opt/lib -lfoo"
-#srcbuild_flags = "-DSPECIAL_DEFINE_FOR_MY_SRC_FILES=13"
-
-#
-# Atmel AVR based board
-#
-#[env:myatmelavr_board]
-#platform = atmelavr
-#board_mcu = %MICROCONTROLLER_TYPE_HERE%     # for example -> atmega168
-#board_f_cpu = %PROCESSOR_FREQUENCY_HERE%    # for example -> 16000000L
-#upload_port = %UPLOAD_PORT_HERE%    # for example (Mac/Linux) -> /dev/ttyUSB0
-#upload_port = %UPLOAD_PORT_HERE%    # for example (Windows) -> COM3
-#upload_protocol = %UPLOAD_PROTOCOL_HERE%    # for example -> arduino
-#upload_speed = %UPLOAD_PROTOCOL_HERE%       # for example -> 19200
-#targets = %DEFAULT_TARGETS_HERE%            # for auto-upload use -> upload
-
-#
-# Atmel AVR based board + Arduino Wiring Framework
-#
-#[env:myarduino_board]
-#platform = atmelavr
-#framework = arduino
-#board = %BOARD_HERE%               # for example -> pro16MHzatmega168
-#upload_port = %UPLOAD_PORT_HERE%   # for example (Mac/Linux) -> /dev/ttyUSB0
-#upload_port = %UPLOAD_PORT_HERE%   # for example (Windows) -> COM3
-#targets = %DEFAULT_TARGETS_HERE%   # for auto-upload use -> upload
-
-#
-# TI MSP430 based board
-#
-#[env:mytimso430_board]
-#platform = timsp430
-#board_mcu = %MICROCONTROLLER_TYPE_HERE%     # for example -> msp430g2553
-#board_f_cpu = %PROCESSOR_FREQUENCY_HERE%    # for example -> 16000000L
-#upload_protocol = %UPLOAD_PROTOCOL_HERE%    # for example -> rf2500
-#targets = %DEFAULT_TARGETS_HERE%   # for auto-upload use -> upload
-
-#
-# TI MSP430  based board + Energia Wiring Framework
-#
-#[env:myarduino_board]
-#platform = timsp430
-#framework = energia
-#board = %BOARD_HERE%                        # for example -> lpmsp430g2553
-#upload_protocol = %UPLOAD_PROTOCOL_HERE%    # for example -> rf2500
-#targets = %DEFAULT_TARGETS_HERE%            # for auto-upload use -> upload
-
-#
-# TI TIVA C ARM based board  + Energia Wiring Framework
-#
-#[env:mytitiva_board]
-#platform = titiva
-#framework = energia
-#board = %BOARD_HERE%                        # for example -> lplm4f120h5qr
-#targets = %DEFAULT_TARGETS_HERE%            # for auto-upload use -> upload

platformio/util.py

@@ -8,9 +8,14 @@ from platform import system, uname
 from subprocess import PIPE, Popen
 from time import sleep
 
+from requests import get, post
+from requests.exceptions import ConnectionError, HTTPError
+from requests.utils import default_user_agent
 from serial import Serial
 
-from platformio.exception import GetSerialPortsError, NotPlatformProject
+from platformio import __apiurl__, __version__
+from platformio.exception import (APIRequestError, GetSerialPortsError,
+                                  NotPlatformProject)
 
 try:
     from configparser import ConfigParser
@@ -26,9 +31,27 @@ def get_systype():
 
 
 def get_home_dir():
+    try:
+        config = get_project_config()
+        if (config.has_section("platformio") and
+                config.has_option("platformio", "home_dir")):
+            return config.get("platformio", "home_dir")
+    except NotPlatformProject:
+        pass
     return expanduser("~/.platformio")
 
 
+def get_lib_dir():
+    try:
+        config = get_project_config()
+        if (config.has_section("platformio") and
+                config.has_option("platformio", "lib_dir")):
+            return config.get("platformio", "lib_dir")
+    except NotPlatformProject:
+        pass
+    return join(get_home_dir(), "lib")
+
+
 def get_source_dir():
     return dirname(realpath(__file__))
 
@@ -89,3 +112,31 @@ def get_serialports():
     else:
         raise GetSerialPortsError(os_name)
     return[{"port": p, "description": d, "hwid": h} for p, d, h in comports()]
+
+
+def get_api_result(path, params=None, data=None):
+    result = None
+    r = None
+    try:
+        headers = {"User-Agent": "PlatformIO/%s %s" % (
+            __version__, default_user_agent())}
+        if data:
+            r = post(__apiurl__ + path, params=params, data=data,
+                     headers=headers)
+        else:
+            r = get(__apiurl__ + path, params=params, headers=headers)
+        result = r.json()
+        r.raise_for_status()
+    except HTTPError as e:
+        if result and "errors" in result:
+            raise APIRequestError(result['errors'][0]['title'])
+        else:
+            raise APIRequestError(e)
+    except ConnectionError:
+        raise APIRequestError("Could not connect to PlatformIO API Service")
+    except ValueError:
+        raise APIRequestError("Invalid response: %s" % r.text)
+    finally:
+        if r:
+            r.close()
+    return result

requirements.txt

@@ -1,5 +1,5 @@
-click==2.5
+click==3.3
 colorama==0.3.1
 pyserial==2.7
-requests==2.3.0
+requests==2.4.1
 scons==2.3.0

tox.ini

@@ -1,7 +1,7 @@
 [tox]
 # toxworkdir = /tmp/.tox
 # toxworkdir = C:\Users\User\Downloads\.tox
-envlist = lint
+envlist = docs, lint
 
 [testenv]
 envlogdir = /tmp/toxlogdir
@@ -17,6 +17,15 @@ deps =
 commands =
     pip install --egg scons
 
+[testenv:docs]
+deps =
+    sphinx
+    sphinx_rtd_theme
+commands =
+    sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
+    sphinx-build -W -b latex -d {envtmpdir}/doctrees docs docs/_build/latex    
+    /bin/bash -c "if [[ $CI != \\"true\\" ]]; then sphinx-build -W -b linkcheck docs docs/_build/html; fi"    
+
 [testenv:lint]
 deps =
     flake8