diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 00000000..25064996 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1 @@ +.. include:: ../HISTORY.rst diff --git a/docs/ide.rst b/docs/ide.rst new file mode 100644 index 00000000..d25d65a4 --- /dev/null +++ b/docs/ide.rst @@ -0,0 +1,33 @@ +.. _ide: + +IDE Integration +=============== + +Eclipse +------- +`Building and debugging Atmel AVR (Arduino-based) project using Eclipse IDE+PlatformIO `_ + + +VIM +--- + +Recommended bundles: + +* Syntax highlight - `Arduino-syntax-file `_ +* Code Completion - `YouCompleteMe `_ +* Syntax checking - `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. diff --git a/docs/index.rst b/docs/index.rst index 3dec1cae..d082ae73 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 `_ | +`Source Code `_ | +`Bugs/Questions `_ | +`Blog `_ | +`Twitter `_ + +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 `_) -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 `_ - (including `Arduino `_ based boards) -* ``timsp430`` `TI MSP430 `_ - (including `MSP430 LaunchPads `_) -* ``titiva`` `TI TIVA C `_ - (including `TIVA C Series LaunchPads `_) +Contents +-------- .. toctree:: - :maxdepth: 2 - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + :maxdepth: 2 + quickstart + installation + projectconf + platforms/index + userguide/index + ide + history diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..c4b4d0d3 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,92 @@ +.. _installation: + +Installation +============ + +*PlatformIO* is written in `Python `_ 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 `_ +application in your *OS*: + +* *Unix/Linux/OS X* this is *Terminal* application. +* *Windows* this is + `Command Prompt `_ (``cmd.exe``) + application. + + +Super-Quick +----------- + +To install or upgrade *PlatformIO*, download +`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 `_ 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 + `_. + + +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 `_. + +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 + + diff --git a/docs/platforms/atmelavr.rst b/docs/platforms/atmelavr.rst new file mode 100644 index 00000000..a5f979d2 --- /dev/null +++ b/docs/platforms/atmelavr.rst @@ -0,0 +1,320 @@ +.. _platform_atmelavr: + +Platform ``atmelavr`` +===================== + +`Atmel AVR® 8- and 32-bit MCUs `_ +deliver a unique combination of performance, power efficiency and design +flexibility. Optimized to speed time to market—and easily adapt to new +ones—they are based on the 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 `_, + `GDB `_, + `AVaRICE `_, + `SimulAVR `_ + * - ``tool-avrdude`` + - uploader + - `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 `_ + + +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) + `_ + - ATmega168 ``atmega168`` + - 16 MHz ``16000000L`` + - 16 Kb + - 1 Kb + * - ``diecimilaatmega328`` + - `Arduino Diecimila or Duemilanove (ATmega328) + `_ + - ATmega328 ``atmega328`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2 Kb + * - ``fio`` + - `Arduino Fio + `_ + - ATmega328P ``atmega328p`` + - 8 MHz ``8000000L`` + - 32 Kb + - 2 Kb + * - ``leonardo`` + - `Arduino Leonardo `_ + - ATmega32u4 ``atmega32u4`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2.5 Kb + * - ``LilyPadUSB`` + - `Arduino LilyPad USB + `_ + - ATmega32u4 ``atmega32u4`` + - 8 MHz ``8000000L`` + - 32 Kb + - 2.5 Kb + * - ``lilypadatmega168`` + - `Arduino LilyPad (ATmega168) + `_ + - ATmega168 ``atmega168`` + - 8 MHz ``8000000L`` + - 16 Kb + - 1 Kb + * - ``lilypadatmega328`` + - `Arduino LilyPad (ATmega328) + `_ + - ATmega328P ``atmega328p`` + - 8 MHz ``8000000L`` + - 32 Kb + - 2 Kb + * - ``megaatmega1280`` + - `Arduino Mega (ATmega1280) + `_ + - ATmega1280 ``atmega1280`` + - 16 MHz ``16000000L`` + - 128 Kb + - 8 Kb + * - ``megaatmega2560`` + - `Arduino Mega (ATmega2560) + `_ + - ATmega2560 ``atmega2560`` + - 16 MHz ``16000000L`` + - 256 Kb + - 8 Kb + * - ``megaADK`` + - `Arduino Mega ADK + `_ + - ATmega2560 ``atmega2560`` + - 16 MHz ``16000000L`` + - 256 Kb + - 8 Kb + * - ``micro`` + - `Arduino Micro + `_ + - ATmega32u4 ``atmega32u4`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2.5 Kb + * - ``miniatmega168`` + - `Arduino Mini (ATmega168) + `_ + - ATmega168 ``atmega168`` + - 16 MHz ``16000000L`` + - 16 Kb + - 1 Kb + * - ``miniatmega328`` + - `Arduino Mini (ATmega328P) + `_ + - ATmega328P ``atmega328p`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2 Kb + * - ``nanoatmega168`` + - `Arduino Nano (ATmega168) + `_ + - ATmega168 ``atmega168`` + - 16 MHz ``16000000L`` + - 16 Kb + - 1 Kb + * - ``nanoatmega328`` + - `Arduino Nano (ATmega328P) + `_ + - ATmega328P ``atmega328p`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2 Kb + * - ``pro8MHzatmega168`` + - `Arduino Pro or Pro Mini (ATmega168, 3.3V) + `_ + - ATmega168 ``atmega168`` + - 8 MHz ``8000000L`` + - 16 Kb + - 1 Kb + * - ``pro16MHzatmega168`` + - `Arduino Pro or Pro Mini (ATmega168, 5V) + `_ + - ATmega168 ``atmega168`` + - 16 MHz ``16000000L`` + - 16 Kb + - 1 Kb + * - ``pro8MHzatmega328`` + - `Arduino Pro or Pro Mini (ATmega328P, 3.3V) + `_ + - ATmega328P ``atmega328p`` + - 8 MHz ``8000000L`` + - 32 Kb + - 2 Kb + * - ``pro16MHzatmega328`` + - `Arduino Pro or Pro Mini (ATmega328P, 5V) + `_ + - ATmega328P ``atmega328p`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2 Kb + * - ``uno`` + - `Arduino Uno + `_ + - ATmega328P ``atmega328p`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2 Kb + +More detailed information you can find here +`Arduino boards `_. + + +Microduino +~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Type ``board`` + - Name + - Microcontroller ``board_mcu`` + - Frequency ``board_f_cpu`` + - Flash + - RAM + * - ``168pa8m`` + - `Microduino Core (ATmega168P, 3.3V) + `_ + - ATmega168P ``atmega168p`` + - 8 MHz ``8000000L`` + - 16 Kb + - 1 Kb + * - ``168pa16m`` + - `Microduino Core (ATmega168P, 5V) + `_ + - ATmega168P ``atmega168p`` + - 16 MHz ``16000000L`` + - 16 Kb + - 1 Kb + * - ``328p8m`` + - `Microduino Core (ATmega328P, 3.3V) + `_ + - ATmega328P ``atmega328p`` + - 8 MHz ``8000000L`` + - 32 Kb + - 2 Kb + * - ``328p16m`` + - `Microduino Core (ATmega328P, 5V) + `_ + - ATmega328P ``atmega328p`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2 Kb + * - ``644pa8m`` + - `Microduino Core+ (ATmega644PA, 3.3V) + `_ + - ATmega644PA ``atmega644p`` + - 8 MHz ``8000000L`` + - 64 Kb + - 4 Kb + * - ``644pa16m`` + - `Microduino Core+ (ATmega644PA, 5V) + `_ + - ATmega644PA ``atmega644p`` + - 16 MHz ``16000000L`` + - 64 Kb + - 4 Kb + * - ``1284p8m`` + - `Microduino Core+ (Atmega1284P, 3.3V) + `_ + - Atmega1284P ``atmega1284p`` + - 8 MHz ``8000000L`` + - 128 Kb + - 16 Kb + * - ``1284p16m`` + - `Microduino Core+ (Atmega1284P, 5V) + `_ + - Atmega1284P ``atmega1284p`` + - 16 MHz ``16000000L`` + - 128 Kb + - 16 Kb + * - ``32u416m`` + - `Microduino-Core USB + `_ + - ATmega32u4 ``atmega32u4`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2.5 Kb + + +More detailed information you can find here +`Microduino boards `_. + + +Miscellaneous +~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Type ``board`` + - Name + - Microcontroller ``board_mcu`` + - Frequency ``board_f_cpu`` + - Flash + - RAM + * - ``raspduino`` + - `Raspduino + `_ + - ATmega328P ``atmega328p`` + - 16 MHz ``16000000L`` + - 32 Kb + - 2 Kb diff --git a/docs/platforms/index.rst b/docs/platforms/index.rst new file mode 100644 index 00000000..7e82f934 --- /dev/null +++ b/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 diff --git a/docs/platforms/timsp430.rst b/docs/platforms/timsp430.rst new file mode 100644 index 00000000..b1b9c017 --- /dev/null +++ b/docs/platforms/timsp430.rst @@ -0,0 +1,119 @@ +.. _platform_timsp430: + +Platform ``timsp430`` +===================== + +`MSP430 microcontrollers (MCUs) from Texas Instruments (TI) `_ +are 16-bit, RISC-based, mixed-signal processors designed for ultra-low power. +These MCUs offer the lowest power consumption and the perfect mix of integrated +peripherals for thousands of applications. + +.. contents:: + +Packages +-------- + +.. list-table:: + :header-rows: 1 + + * - Name + - Alias + - Contents + * - ``toolchain-timsp430`` + - toolchain + - `msp-gcc `_, + `GDB `_ + * - ``tool-mspdebug`` + - uploader + - `MSPDebug `_ + * - ``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 `_ + + +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 `_ + - MSP430G2231 ``msp430g2231`` + - 16 MHz ``16000000L`` + - 2 Kb + - 128 B + * - ``lpmsp430g2452`` + - `MSP430G2452 LaunchPad `_ + - MSP430G2452 ``msp430g2452`` + - 16 MHz ``16000000L`` + - 8 Kb + - 256 B + * - ``lpmsp430g2553`` + - `MSP430G2553 LaunchPad `_ + - MSP430G2553 ``msp430g2553`` + - 16 MHz ``16000000L`` + - 16 Kb + - 512 B + * - ``lpmsp430f5529`` + - `MSP430F5529 LaunchPad (16 Mhz) `_ + - MSP430F5529 ``msp430f5529`` + - 16 MHz ``16000000L`` + - 128 Kb + - 8 KB + * - ``lpmsp430f5529_25`` + - `MSP430F5529 LaunchPad (25 Mhz) `_ + - MSP430F5529 ``msp430f5529`` + - 25 MHz ``25000000L`` + - 128 Kb + - 8 KB + * - ``lpmsp430fr5739`` + - `MSP430FR5739 Experimenter Board `_ + - MSP430FR5739 ``msp430fr5739`` + - 16 MHz ``16000000L`` + - 16 Kb + - 1 KB + * - ``lpmsp430fr5969`` + - `MSP430FR5969 LaunchPad `_ + - MSP430FR5969 ``msp430fr5969`` + - 16 MHz ``16000000L`` + - 64 Kb + - 2 KB + + +More detailed information you can find here +`MSP430 LaunchPads `_. + + + diff --git a/docs/platforms/titiva.rst b/docs/platforms/titiva.rst new file mode 100644 index 00000000..54145d98 --- /dev/null +++ b/docs/platforms/titiva.rst @@ -0,0 +1,93 @@ +.. _platform_titiva: + +Platform ``titiva`` +=================== + +`Texas Instruments TM4C12x MCUs `_ +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 `_, + `GDB `_ + * - ``tool-lm4flash`` + - uploader + - `Flash Programmer `_ + * - ``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 `_ + + +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 `_ + - LM4F120H5QR ``cortex-m4`` + - 80 MHz ``80000000L`` + - 256 Kb + - 32 Kb + * - ``lptm4c1230c3pm`` + - `Tiva C Series TM4C123G LaunchPad + `_ + - TM4C123GH6PM ``cortex-m4`` + - 80 MHz ``80000000L`` + - 256 Kb + - 32 Kb + * - ``lptm4c1294ncpdt`` + - `Tiva C Series TM4C1294 Connected LaunchPad + `_ + - TM4C1294NCPDT ``cortex-m4`` + - 120 Mhz ``120000000L`` + - 1 Mb + - 256 Kb + +More detailed information you can find here +`TIVA C Series LaunchPads `_. diff --git a/docs/projectconf.rst b/docs/projectconf.rst new file mode 100644 index 00000000..3a1ab0bb --- /dev/null +++ b/docs/projectconf.rst @@ -0,0 +1,286 @@ +.. _projectconf: + +Project Configuration File +========================== + +The Project configuration file is named ``platformio.ini``. This is a +`INI-style `_ 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 ` 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 `_. + +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 `_) +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 + `_ +* `Options for Debugging Your Program + `_ +* `Options That Control Optimization + `_ +* `Options Controlling the Preprocessor + `_ +* `Passing Options to the Assembler + `_ +* `Options for Linking `_ +* `Options for Directory Search + `_ + + +``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 + diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 00000000..9c947c99 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,52 @@ +.. _quickstart: + +Quickstart +========== + +First, :ref:`Install PlatformIO `. + +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. diff --git a/docs/userguide/cmd_init.rst b/docs/userguide/cmd_init.rst new file mode 100644 index 00000000..78ef1164 --- /dev/null +++ b/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. diff --git a/docs/userguide/cmd_install.rst b/docs/userguide/cmd_install.rst new file mode 100644 index 00000000..bd533b1a --- /dev/null +++ b/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 ` 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! diff --git a/docs/userguide/cmd_list.rst b/docs/userguide/cmd_list.rst new file mode 100644 index 00000000..91ccf3d4 --- /dev/null +++ b/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 ` + + +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 diff --git a/docs/userguide/cmd_run.rst b/docs/userguide/cmd_run.rst new file mode 100644 index 00000000..2f7345f0 --- /dev/null +++ b/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 `_ + +.. 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 + 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 diff --git a/docs/userguide/cmd_search.rst b/docs/userguide/cmd_search.rst new file mode 100644 index 00000000..7edd9568 --- /dev/null +++ b/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 ` + + +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) diff --git a/docs/userguide/cmd_serialports.rst b/docs/userguide/cmd_serialports.rst new file mode 100644 index 00000000..50b0cc73 --- /dev/null +++ b/docs/userguide/cmd_serialports.rst @@ -0,0 +1,54 @@ +.. _cmd_serialports: + +platformio serialports +====================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio serialports + + +Description +----------- + +List available `Serial Ports `_ + + +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) diff --git a/docs/userguide/cmd_show.rst b/docs/userguide/cmd_show.rst new file mode 100644 index 00000000..3c48efee --- /dev/null +++ b/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 ` + + +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 diff --git a/docs/userguide/cmd_uninstall.rst b/docs/userguide/cmd_uninstall.rst new file mode 100644 index 00000000..ef6348f1 --- /dev/null +++ b/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 ` + + +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! diff --git a/docs/userguide/cmd_update.rst b/docs/userguide/cmd_update.rst new file mode 100644 index 00000000..66734508 --- /dev/null +++ b/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 ` + + +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] diff --git a/docs/userguide/cmd_upgrade.rst b/docs/userguide/cmd_upgrade.rst new file mode 100644 index 00000000..a41099de --- /dev/null +++ b/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 diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst new file mode 100644 index 00000000..5779209a --- /dev/null +++ b/docs/userguide/index.rst @@ -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