Merge branch 'release/v2.3.2'

platformio · Sep 10, 2015 · 12d6df6 · 12d6df6
2 parents 74ac9ff + 2c5db64
commit 12d6df6
Show file tree

Hide file tree

Showing 52 changed files with 1,450 additions and 135 deletions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -4,6 +4,20 @@ Release History
 PlatformIO 2.0
 --------------
 
+2.3.2 (2015-09-10)
+~~~~~~~~~~~~~~~~~~
+
+* Allowed to use ST-Link uploader for mbed-based projects
+* Explained how to use ``lib`` directory from the PlatformIO based project in
+  ``readme.txt`` which will be automatically generated using
+  `platformio init <http://docs.platformio.org/en/latest/userguide/cmd_init.html>`__
+  command
+  (`issue #273 <https://github.com/platformio/platformio/issues/273>`_)
+* Found solution for "pip/scons error: option --single-version-externally-managed not
+  recognized" when install PlatformIO using ``pip`` package manager
+  (`issue #279 <https://github.com/platformio/platformio/issues/279>`_)
+* Fixed `SConsNotInstalled` error for Linux Debian-based distributives
+
 2.3.1 (2015-09-06)
 ~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -75,6 +75,27 @@ There are a few options:
 - masking under Continuous Integration system via environment variable
   :envvar:`CI=true <CI>`.
 
+PlatformIO and ``scons`` aren't installed properly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Try these solutions:
+
+1. Upgrade SCons via `pip <https://pip.pypa.io>`_
+
+.. code-block:: bash
+
+    [sudo] pip uninstall scons
+    [sudo] pip install scons
+
+2. Install PlatformIO using :ref:`installation_installer_script`.
+
+.. _faq_troubleshooting_sconssingverextmanaged:
+
+PIP & SCons Error: option --single-version-externally-managed not recognized
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Answered in `issue #279 <https://github.com/platformio/platformio/issues/279>`_.
+
 .. _faq_troubleshooting_pionotfoundinpath:
 
 Program ``platformio`` not found in PATH
@@ -100,8 +121,8 @@ should contain ``/usr/local/bin`` directory.
 programs to the ``bin`` directory which is included in ``$PATH``. For example,
 see `issue #272 <https://github.com/platformio/platformio/issues/272#issuecomment-133626112>`_.
 
-Windows: ``UnicodeDecodeError: 'ascii' codec can't decode byte``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Windows UnicodeDecodeError: 'ascii' codec can't decode byte
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Answered in `issue #143 <https://github.com/platformio/platformio/issues/143#issuecomment-88060906>`_.
 
@@ -118,20 +139,20 @@ Please upgrade *SetupTools* package:
 
 .. code-block:: bash
 
-    $ [sudo] pip uninstall setuptools
-    $ [sudo] pip install setuptools
+    [sudo] pip uninstall setuptools
+    [sudo] pip install setuptools
 
     # Then re-install PlatformIO
-    $ [sudo] pip uninstall platformio
-    $ [sudo] pip install platformio
+    [sudo] pip uninstall platformio
+    [sudo] pip install platformio
 
-Windows: ``AttributeError: 'module' object has no attribute 'packages'``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Windows AttributeError: 'module' object has no attribute 'packages'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Answered in `issue #252 <https://github.com/platformio/platformio/issues/252#issuecomment-127072039>`_.
 
-ARM toolchain: ``cc1plus: error while loading shared libraries``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ARM toolchain: cc1plus: error while loading shared libraries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 See related answers for
 `error while loading shared libraries <https://github.com/platformio/platformio/issues?utf8=✓&q=error+while+loading+shared+libraries>`_.
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -49,9 +49,12 @@ The latest stable version of PlatformIO may be done via
     # update dependent packages to the latest versions
     pip install -U pip setuptools
 
-    # install the latest version of PlatformIO
+    # install/upgrade the latest version of PlatformIO
     pip install -U platformio
 
+.. warning::
+    Known Issue: :ref:`faq_troubleshooting_sconssingverextmanaged`
+
 Note that you may run into permissions issues running these commands. You have
 a few options here:
 
@@ -61,6 +64,8 @@ a few options here:
 * Run the command in a `virtualenv <https://virtualenv.pypa.io>`_ local to a
   specific project working set.
 
+.. _installation_installer_script:
+
 Installer Script
 ~~~~~~~~~~~~~~~~
 
@@ -134,9 +139,6 @@ For upgrading ``platformio`` to the latest version:
 Development Version
 ~~~~~~~~~~~~~~~~~~~
 
-.. warning::
-    We don't recommend to use ``develop`` version in production.
-
 Install the latest PlatformIO from the ``develop`` branch:
 
 .. code-block:: bash
@@ -163,4 +165,5 @@ Troubleshooting
     **Windows OS**: Please check that you have correctly installed USB driver
     from board manufacturer
 
-For further details, frequently questions, please refer to :ref:`faq`.
+For further details, frequently questions, known issues, please
+refer to :ref:`faq`.
diff --git a/docs/projectconf.rst b/docs/projectconf.rst
@@ -475,39 +475,7 @@ Examples
     targets = upload
 
 
-2. :ref:`platform_atmelavr`: Microduino Core (ATmega168P, 3.3V) board with
-   auto pre-configured ``board_*`` and ``upload_*`` options (use only
-   ``board`` option) and Arduino Wiring-based Framework
-
-.. code-block:: ini
-
-    [env:atmelavr_microduino_core_board]
-    platform = atmelavr
-    framework = arduino
-    board = 168pa8m
-
-    # enable auto-uploading
-    targets = upload
-
-
-3. :ref:`platform_atmelavr`: Raspduino board with
-   auto pre-configured ``board_*`` and ``upload_*`` options (use only
-   ``board`` option) and Arduino Wiring-based Framework
-
-.. code-block:: ini
-
-    [env:atmelavr_raspduino_board]
-    platform = atmelavr
-    framework = arduino
-    board = raspduino
-
-    upload_port = /dev/ttyS0
-
-    # enable auto-uploading
-    targets = upload
-
-
-4. :ref:`platform_atmelavr`: Embedded board that is based on ATmega168 MCU with
+2. :ref:`platform_atmelavr`: Embedded board that is based on ATmega168 MCU with
    "arduino" bootloader
 
 .. code-block:: ini
@@ -527,7 +495,7 @@ Examples
     targets = upload
 
 
-5. Upload firmware via USB programmer (USBasp) to :ref:`platform_atmelavr`
+3. Upload firmware via USB programmer (USBasp) to :ref:`platform_atmelavr`
    microcontrollers
 
 .. code-block:: ini
@@ -536,44 +504,25 @@ Examples
     platform = atmelavr
     framework = arduino
     board = pro8MHzatmega328
-    upload_protocol = usbasp -B5
+    upload_protocol = usbasp -  B5
 
 
-6. :ref:`platform_timsp430`: TI MSP430G2553 LaunchPad with auto pre-configured
-   ``board_*`` and ``upload_*`` options (use only ``board`` option) and Energia
-   Wiring-based Framework
+4. :ref:`platform_ststm32`: Upload firmware using GDB script ``upload.gdb``,
+   `issue #175 <https://github.com/platformio/platformio/issues/175>`_
 
 .. code-block:: ini
 
-    [env:timsp430_g2553_launchpad]
-    platform = timsp430
-    framework = energia
-    board = lpmsp430g2553
+    [env:st_via_gdb]
+    platform = ststm32
+    board = armstrap_eagle512
+    upload_protocol = gdb
 
-
-7. :ref:`platform_timsp430`: Embedded board that is based on MSP430G2553 MCU
+5. :ref:`platform_ststm32`: Upload firmware using ST-Link instead mbed's media
+   disk
 
 .. code-block:: ini
 
-    [env:timsp430_g2553_board]
-    platform = timsp430
-    board_mcu = msp430g2553
-    board_f_cpu = 16000000L
-
-    upload_protocol = rf2500
-
-    # enable auto-uploading
-    targets = upload
-
-
-8. :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
-
+    [env:stlink_for_mbed]
+    platform = ststm32
+    board = disco_f100rb
+    upload_protocol = stlink
diff --git a/examples/atmelavr-and-arduino/adafruit-blink/lib/readme.txt b/examples/atmelavr-and-arduino/adafruit-blink/lib/readme.txt
@@ -0,0 +1,38 @@
+
+This directory is intended for the project specific (private) libraries.
+PlatformIO will compile them to static libraries and link to executable file.
+
+The source code of each library should be placed in separate directory, like
+"lib/private_lib/[here are source files]".
+
+For example, see how can be organised `Foo` and `Bar` libraries:
+
+|--lib
+|  |--Bar
+|  |  |--docs
+|  |  |--examples
+|  |  |--src
+|  |     |- Bar.c
+|  |     |- Bar.h
+|  |--Foo
+|  |  |- Foo.c
+|  |  |- Foo.h
+|  |- readme.txt --> THIS FILE
+|- platformio.ini
+|--src
+   |- main.c
+
+Then in `src/main.c` you should use:
+
+#include <Foo.h>
+#include <Bar.h>
+
+// rest H/C/CPP code
+
+PlatformIO will find your libraries automatically, configure preprocessor's
+include paths and build them.
+
+See additional options for PlatformIO Library Dependency Finder `lib_*`:
+
+http://docs.platformio.org/en/latest/projectconf.html#lib-install
+
diff --git a/examples/atmelavr-and-arduino/arduino-external-libs/lib/readme.txt b/examples/atmelavr-and-arduino/arduino-external-libs/lib/readme.txt
@@ -0,0 +1,38 @@
+
+This directory is intended for the project specific (private) libraries.
+PlatformIO will compile them to static libraries and link to executable file.
+
+The source code of each library should be placed in separate directory, like
+"lib/private_lib/[here are source files]".
+
+For example, see how can be organised `Foo` and `Bar` libraries:
+
+|--lib
+|  |--Bar
+|  |  |--docs
+|  |  |--examples
+|  |  |--src
+|  |     |- Bar.c
+|  |     |- Bar.h
+|  |--Foo
+|  |  |- Foo.c
+|  |  |- Foo.h
+|  |- readme.txt --> THIS FILE
+|- platformio.ini
+|--src
+   |- main.c
+
+Then in `src/main.c` you should use:
+
+#include <Foo.h>
+#include <Bar.h>
+
+// rest H/C/CPP code
+
+PlatformIO will find your libraries automatically, configure preprocessor's
+include paths and build them.
+
+See additional options for PlatformIO Library Dependency Finder `lib_*`:
+
+http://docs.platformio.org/en/latest/projectconf.html#lib-install
+
diff --git a/examples/atmelavr-and-arduino/arduino-internal-libs/lib/readme.txt b/examples/atmelavr-and-arduino/arduino-internal-libs/lib/readme.txt
@@ -0,0 +1,38 @@
+
+This directory is intended for the project specific (private) libraries.
+PlatformIO will compile them to static libraries and link to executable file.
+
+The source code of each library should be placed in separate directory, like
+"lib/private_lib/[here are source files]".
+
+For example, see how can be organised `Foo` and `Bar` libraries:
+
+|--lib
+|  |--Bar
+|  |  |--docs
+|  |  |--examples
+|  |  |--src
+|  |     |- Bar.c
+|  |     |- Bar.h
+|  |--Foo
+|  |  |- Foo.c
+|  |  |- Foo.h
+|  |- readme.txt --> THIS FILE
+|- platformio.ini
+|--src
+   |- main.c
+
+Then in `src/main.c` you should use:
+
+#include <Foo.h>
+#include <Bar.h>
+
+// rest H/C/CPP code
+
+PlatformIO will find your libraries automatically, configure preprocessor's
+include paths and build them.
+
+See additional options for PlatformIO Library Dependency Finder `lib_*`:
+
+http://docs.platformio.org/en/latest/projectconf.html#lib-install
+
diff --git a/examples/atmelavr-and-arduino/arduino-own-src_dir/lib/readme.txt b/examples/atmelavr-and-arduino/arduino-own-src_dir/lib/readme.txt
@@ -0,0 +1,38 @@
+
+This directory is intended for the project specific (private) libraries.
+PlatformIO will compile them to static libraries and link to executable file.
+
+The source code of each library should be placed in separate directory, like
+"lib/private_lib/[here are source files]".
+
+For example, see how can be organised `Foo` and `Bar` libraries:
+
+|--lib
+|  |--Bar
+|  |  |--docs
+|  |  |--examples
+|  |  |--src
+|  |     |- Bar.c
+|  |     |- Bar.h
+|  |--Foo
+|  |  |- Foo.c
+|  |  |- Foo.h
+|  |- readme.txt --> THIS FILE
+|- platformio.ini
+|--src
+   |- main.c
+
+Then in `src/main.c` you should use:
+
+#include <Foo.h>
+#include <Bar.h>
+
+// rest H/C/CPP code
+
+PlatformIO will find your libraries automatically, configure preprocessor's
+include paths and build them.
+
+See additional options for PlatformIO Library Dependency Finder `lib_*`:
+
+http://docs.platformio.org/en/latest/projectconf.html#lib-install
+