diff --git a/README.rst b/README.rst index e9564b8e..d0f02299 100644 --- a/README.rst +++ b/README.rst @@ -4,18 +4,18 @@ PlatformIO **Platformio** is a console tool to build code with different development platforms. -You do not need to install any *IDE* or to compile any toolchains. *Platformio* -has pre-built different development platforms for your favorite *OS* that -including: compiler, debugger, flasher (for embedded) and many others useful -tools. +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 single sources with different -platforms with only one command ``platformio run``. This is due to -``platformio.ini`` project's file where you can setup different environments -with specific settings (platform, compiler or firmware uploading options, -include pre-built framework and many more) +**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. -Each platform consists of packages that are located in own repository. +Each platform consists of packages which are located in own repository. Due to ``platformio update`` command you will have up-to-date development instruments. @@ -37,13 +37,13 @@ It has support for many popular embedded platforms like these: (including `TIVA C Series LaunchPads `_) -See project `examples `_ +See project `examples with screenshots `_. Python & OS Support ------------------- -**Platformio** written in `Python `_ and works with +**Platformio** is written in `Python `_ and works with versions 2.6 and 2.7 on Unix/Linux, OS X, and Windows. @@ -68,8 +68,8 @@ Quickstart # Process the project's environments $ platformio run -For more detailed information please follow to "Installation" and "User Guide" -sections. +For more detailed information please follow to `Installation <#installation>`_ +and `User Guide <#user-guide>`_ sections. Installation @@ -133,6 +133,24 @@ To print all available commands and options: $ 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 + show Show details about an installed platforms + uninstall Uninstall the platforms + update Update installed platforms + ``platformio search`` ~~~~~~~~~~~~~~~~~~~~~ @@ -147,6 +165,14 @@ Search for development platforms: # 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 install`` ~~~~~~~~~~~~~~~~~~~~~~ @@ -160,6 +186,19 @@ can install one of them: $ platformio install SomePlatform --with-package=PackageName $ platformio install SomePlatform --without-package=PackageName + # Example + $ platformio install timsp430 --with-package=framework-energiamsp430 + 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! + ``platformio list`` ~~~~~~~~~~~~~~~~~~~ @@ -170,6 +209,10 @@ To list installed platforms: $ platformio list + # Example + $ platformio list + timsp430 with packages: toolchain-timsp430, tool-mspdebug, framework-energiamsp430 + ``platformio show`` ~~~~~~~~~~~~~~~~~~~ @@ -180,6 +223,22 @@ To show details about an installed platform: $ platformio show SomePlatform + # Example + $ platformio show timsp430 + timsp430 - An embedded platform for TI MSP430 microcontrollers (with Energia Framework) + ---------- + Package: toolchain-timsp430 + Location: /Users/ikravets/.platformio/timsp430/tools/toolchain + Version: 1 + ---------- + Package: tool-mspdebug + Location: /Users/ikravets/.platformio/timsp430/tools/mspdebug + Version: 1 + ---------- + Package: framework-energiamsp430 + Location: /Users/ikravets/.platformio/timsp430/frameworks/energia + Version: 1 + ``platformio uninstall`` ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -190,6 +249,13 @@ To uninstall platform: $ 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 init`` ~~~~~~~~~~~~~~~~~~~ @@ -202,6 +268,13 @@ Initialize new platformio based project. $ cd /path/to/empty/directory $ platformio init + # Example + $ platformio init + Project successfully initialized. + Please put your source code to `src` directory, external libraries to `libs` + 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. @@ -220,12 +293,37 @@ Process the project's environments defined in ``platformio.ini`` file: $ 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. + + Skipped launchpad_msp430g2 environment + 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 @@ -233,12 +331,103 @@ Process specific target: $ platformio run -t clean $ platformio run -t upload + # 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 + Skipped arduino_pro5v environment + 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 + + Skipped launchpad_lm4f120 environment + + +``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] + Questions & Bugs ----------------