feedc0de/platformio-core
1
0
Fork 0
forked from platformio/platformio-core
Code Pull Requests Activity

Initial version of docs

Browse Source
This commit is contained in:
Ivan Kravets
2014-08-09 16:39:00 +03:00
parent 8961c2fad4 7af95ab897
commit f83e052ea2
25 changed files with 2326 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
docs/Makefile Normal file
View File

@ -0,0 +1,177 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PlatformIO.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PlatformIO.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/PlatformIO"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PlatformIO"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

277
docs/conf.py Normal file
View File

@ -0,0 +1,277 @@
# -*- coding: utf-8 -*-
#
# PlatformIO documentation build configuration file, created by
# sphinx-quickstart on Sun Aug 3 19:13:49 2014.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
import sys
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath(os.pardir))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'PlatformIO'
copyright = u'2014, Ivan Kravets'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
import platformio
# The short X.Y version.
version = '.'.join(map(str, platformio.VERSION[0:2]))
# The full version, including alpha/beta/rc tags.
release = platformio.__version__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'PlatformIOdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'PlatformIO.tex', u'PlatformIO Documentation',
u'Ivan Kravets', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'platformio', u'PlatformIO Documentation',
[u'Ivan Kravets'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'PlatformIO', u'PlatformIO Documentation',
u'Ivan Kravets', 'PlatformIO', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None}
# Read the Docs Sphinx Theme patch
# on_rtd is whether we are on readthedocs.org,
# this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# A timeout value, in seconds, for the linkcheck builder
# http://sphinx-doc.org/config.html#confval-linkcheck_timeout
linkcheck_timeout = 30

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.

47
docs/index.rst Normal file
View File

@ -0,0 +1,47 @@
PlatformIO: A cross-platform code builder and library manager
=============================================================
`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,
uploader (for embedded) and many other useful tools.
**PlatformIO** allows developer to compile the same code with different
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 :ref:`cmd_update` command you will have up-to-date development
instruments.
**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
Contents
--------
.. toctree::
: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

242
docs/make.bat Normal file
View File

@ -0,0 +1,242 @@
@ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. xml to make Docutils-native XML files
echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
%SPHINXBUILD% 2> nul
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PlatformIO.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PlatformIO.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdfja" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf-ja
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
if "%1" == "xml" (
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The XML files are in %BUILDDIR%/xml.
goto end
)
if "%1" == "pseudoxml" (
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
goto end
)
:end

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

9
tox.ini
View File

@ -17,6 +17,15 @@ deps =
commands =
pip install --egg scons
[testenv:docs]
deps =
sphinx
sphinx_rtd_theme
commands =
sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
sphinx-build -W -b latex -d {envtmpdir}/doctrees docs docs/_build/latex
/bin/bash -c "if [[ $CI != \\"true\\" ]]; then sphinx-build -W -b linkcheck docs docs/_build/html; fi"
[testenv:lint]
deps =
flake8