platformio/platformio-core
1
0
Fork 1
mirror of https://github.com/platformio/platformio-core.git synced 2025-10-04 09:30:55 +02:00
Code Issues Packages Projects Releases Wiki Activity
103 Commits 8 Branches 135 Tags
8b056efe64cc2ef1614aa56a98dbef98f23f9e9d
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.rst 

PlatformIO
==========

.. image:: https://travis-ci.org/ivankravets/platformio.svg?branch=develop
    :target: https://travis-ci.org/ivankravets/platformio
    :alt: Build Status
.. image:: https://gemnasium.com/ivankravets/platformio.png
    :target: https://gemnasium.com/ivankravets/platformio
    :alt: Dependency Status
.. image:: https://pypip.in/version/platformio/badge.png
    :target: https://pypi.python.org/pypi/platformio/
    :alt: Latest Version
.. image:: https://pypip.in/download/platformio/badge.png
    :target: https://pypi.python.org/pypi/platformio/
    :alt: Downloads
.. image:: https://pypip.in/license/platformio/badge.png
    :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>`_


**PlatformIO** is a console tool to build code with different development
platforms.

You have no need to install any *IDE* or compile any toolchains. *PlatformIO*
has pre-built different development platforms including: compiler, debugger,
flasher (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.

Each platform consists of packages which are located in own repository.
Due to ``platformio update`` command you will have up-to-date development
instruments.

.. image:: examples/platformio-examples.png
    :target: https://github.com/ivankravets/platformio/raw/develop/examples/platformio-examples.png
    :alt:  Examples
    :width: 730px

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

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>`_)


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.
Description
Your Gateway to Embedded Software Development Excellence 👽
arduinoarmavrbuild-systemcmsisdebuggingembeddedesp32esp8266firmwareideiotlibrariesmicrocontrollerpackage-managerplatformiorisc-vrtosunit-testingzephyr-rtos
Readme 41 MiB
Languages
Python 98%
Smarty 1.8%
C++ 0.1%