platformio/platformio-core
1
0
Fork 1
mirror of https://github.com/platformio/platformio-core.git synced 2025-07-29 17:47:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Initial version of docs

Browse Source
This commit is contained in:
Ivan Kravets
2014-08-09 16:31:20 +03:00
parent f006561113
commit 9a99409ae1
21 changed files with 1597 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/history.rst Normal file
View File

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

33
docs/ide.rst Normal file
View File

@ -0,0 +1,33 @@
.. _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
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.

51
docs/index.rst
View File

@ -1,24 +1,26 @@
..
PlatformIO: A cross-platform code builder and library manager
=============================================================
You have no need to install any *IDE* or compile any toolchains. *PlatformIO*
`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,
flasher (for embedded) and many other useful tools.
uploader (for embedded) 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.
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 ``platformio update`` command you will have up-to-date development
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
@ -29,24 +31,17 @@ instruments.
* Extract *EEPROM* data
* Upload firmware to your device
It has support for many popular embedded platforms like these:
* ``atmelavr`` `Atmel AVR <http://en.wikipedia.org/wiki/Atmel_AVR>`_
(including `Arduino <http://www.arduino.cc>`_ based boards)
* ``timsp430`` `TI MSP430 <http://www.ti.com/lsds/ti/microcontroller/16-bit_msp430/overview.page>`_
(including `MSP430 LaunchPads <http://www.ti.com/ww/en/launchpad/launchpads-msp430.html>`_)
* ``titiva`` `TI TIVA C <http://www.ti.com/lsds/ti/microcontroller/tiva_arm_cortex/c_series/overview.page>`_
(including `TIVA C Series LaunchPads <http://www.ti.com/ww/en/launchpad/launchpads-connected.html>`_)
Contents
--------
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
:maxdepth: 2
quickstart
installation
projectconf
platforms/index
userguide/index
ide
history

92
docs/installation.rst Normal file
View File

@ -0,0 +1,92 @@
.. _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
$ 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
.. warning::
If you have an error ``pkg_resources.DistributionNotFound`` try to
uninstall *PlatformIO* ``$ pip uninstall platformio``, then install it via
``$ easy_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

320
docs/platforms/atmelavr.rst Normal file
View File

@ -0,0 +1,320 @@
.. _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>`_.
Miscellaneous
~~~~~~~~~~~~~
.. 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

19
docs/platforms/index.rst Normal file
View File

@ -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

119
docs/platforms/timsp430.rst Normal file
View File

@ -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>`_.

93
docs/platforms/titiva.rst Normal file
View File

@ -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>`_.

286
docs/projectconf.rst Normal file
View File

@ -0,0 +1,286 @@
.. _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::
[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
# upload_port = COM3 # for Windows OS
# enable auto-uploading
targets = upload
2. :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
# upload_port = COM3 # for Windows OS
upload_protocol = arduino
upload_speed = 19200
# enable auto-uploading
targets = upload
3. :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
4. :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

52
docs/quickstart.rst Normal file
View File

@ -0,0 +1,52 @@
.. _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.
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
For more detailed information please go to :ref:`userguide` sections.

42
docs/userguide/cmd_init.rst Normal file
View File

@ -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.

76
docs/userguide/cmd_install.rst Normal file
View File

@ -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!

30
docs/userguide/cmd_list.rst Normal file
View File

@ -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

130
docs/userguide/cmd_run.rst Normal file
View File

@ -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

42
docs/userguide/cmd_search.rst Normal file
View File

@ -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)

54
docs/userguide/cmd_serialports.rst Normal file
View File

@ -0,0 +1,54 @@
.. _cmd_serialports:
platformio serialports
======================
.. contents::
Usage
-----
.. code-block:: bash
platformio serialports
Description
-----------
List available `Serial Ports <http://en.wikipedia.org/wiki/Serial_port>`_
Examples
--------
1. Unix OS
.. code-block:: bash
$ 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
2. Windows OS
.. code-block:: bash
$ 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)

42
docs/userguide/cmd_show.rst Normal file
View File

@ -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

31
docs/userguide/cmd_uninstall.rst Normal file
View File

@ -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!

54
docs/userguide/cmd_update.rst Normal file
View File

@ -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]

32
docs/userguide/cmd_upgrade.rst Normal file
View File

@ -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

26
docs/userguide/index.rst Normal file
View File

@ -0,0 +1,26 @@
.. _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
cmd_list
cmd_run
cmd_search
cmd_serialports
cmd_show
cmd_uninstall
cmd_update
cmd_upgrade