From 35b0ddcfa6e2043c4c235e2135dcc0ee161b6eb8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 7 Oct 2010 06:47:57 -0400 Subject: added skeleton sphinx docs --- Makefile | 130 +++++++++++++++++++++++++ make.bat | 155 ++++++++++++++++++++++++++++++ source/_static/.gitignore | 0 source/_templates/.gitignore | 0 source/conf.py | 220 +++++++++++++++++++++++++++++++++++++++++++ source/index.rst | 20 ++++ 6 files changed, 525 insertions(+) create mode 100644 Makefile create mode 100644 make.bat create mode 100644 source/_static/.gitignore create mode 100644 source/_templates/.gitignore create mode 100644 source/conf.py create mode 100644 source/index.rst diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..ffa91c5 --- /dev/null +++ b/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where 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 " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @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/libmaple.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/libmaple.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/libmaple" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/libmaple" + @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." + +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." + +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." diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..1833a4b --- /dev/null +++ b/make.bat @@ -0,0 +1,155 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ 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. changes to make an overview over all changed/added/deprecated items + 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 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "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. + goto end +) + +if "%1" == "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\libmaple.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\libmaple.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "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. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/source/_static/.gitignore b/source/_static/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/source/_templates/.gitignore b/source/_templates/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 0000000..7eb6782 --- /dev/null +++ b/source/conf.py @@ -0,0 +1,220 @@ +# -*- coding: utf-8 -*- +# +# libmaple documentation build configuration file, created by +# sphinx-quickstart on Thu Oct 7 06:42:30 2010. +# +# 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 sys, os + +# 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('.')) + +# -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage'] + +# 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'libmaple' +copyright = u'2010, Marti Bolivar, Perry Hung, Andrew Meyer, Brian Newbold' + +# 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. +# +# The short X.Y version. +version = '0.0' +# The full version, including alpha/beta/rc tags. +release = '0.0.7' + +# 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 = [] + +# 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 = [] + + +# -- 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 +# " v 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'] + +# 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 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 = 'libmapledoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'libmaple.tex', u'libmaple Documentation', + u'Marti Bolivar, Perry Hung, Andrew Meyer, Brian Newbold', '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 + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# 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', 'libmaple', u'libmaple Documentation', + [u'Marti Bolivar, Perry Hung, Andrew Meyer, Brian Newbold'], 1) +] + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/source/index.rst b/source/index.rst new file mode 100644 index 0000000..0bf6b5a --- /dev/null +++ b/source/index.rst @@ -0,0 +1,20 @@ +.. libmaple documentation master file, created by + sphinx-quickstart on Thu Oct 7 06:42:30 2010. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to libmaple's documentation! +==================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + -- cgit v1.2.3 From 36f3ce1c5fb977e69e4cfbcef896748aafa14fcd Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 7 Oct 2010 07:06:22 -0400 Subject: added docs readme file --- README | 28 ++++++++++++++++++++++++++++ source/conf.py | 25 +++++++++++++++---------- 2 files changed, 43 insertions(+), 10 deletions(-) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..8556dd2 --- /dev/null +++ b/README @@ -0,0 +1,28 @@ +This directory contains the Sphinx documentation for libmaple. You +can generate HTML documentation using the Makefile if you have make, +or using make.bat from Windows. + +For the impatient, you can build the HTML docs with (on Unix): + + $ sudo easy_install -U Sphinx + $ make html + +Which will produce HTML documentation in build/html. + +All of the documentation itself lives in source/. The directory +source/_static is for static content like style sheets; +source/_templates contains Sphinx templates. + +The documentation is written in reStructuredText (reST); it's a Python +thing that they use to produce the docs at python.org (which are +beautiful, if you've never seen them). You can read more about Sphinx +here: + + http://sphinx.pocoo.org/tutorial.html + +Specific information on documenting C and C++ is available here: + + http://sphinx.pocoo.org/domains.html + +The file source/conf.py is an autogenerated configuration file; you +can read it yourself. diff --git a/source/conf.py b/source/conf.py index 7eb6782..c12ebb9 100644 --- a/source/conf.py +++ b/source/conf.py @@ -3,7 +3,8 @@ # libmaple documentation build configuration file, created by # sphinx-quickstart on Thu Oct 7 06:42:30 2010. # -# This file is execfile()d with the current directory set to its containing dir. +# 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. @@ -18,14 +19,17 @@ import sys, os # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.insert(0, os.path.abspath('.')) -# -- General configuration ----------------------------------------------------- +# -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage'] +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.todo', + 'sphinx.ext.coverage'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -66,7 +70,8 @@ release = '0.0.7' # directories to ignore when looking for source files. exclude_patterns = [] -# The reST default role (used for this markup: `text`) to use for all documents. +# 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. @@ -87,7 +92,7 @@ pygments_style = 'sphinx' #modindex_common_prefix = [] -# -- Options for HTML output --------------------------------------------------- +# -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. @@ -167,7 +172,7 @@ html_static_path = ['_static'] htmlhelp_basename = 'libmapledoc' -# -- Options for LaTeX output -------------------------------------------------- +# -- Options for LaTeX output ------------------------------------------------- # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' @@ -176,7 +181,7 @@ htmlhelp_basename = 'libmapledoc' #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). +# (source start file, target file, title, author, documentclass [howto/manual]) latex_documents = [ ('index', 'libmaple.tex', u'libmaple Documentation', u'Marti Bolivar, Perry Hung, Andrew Meyer, Brian Newbold', 'manual'), @@ -206,7 +211,7 @@ latex_documents = [ #latex_domain_indices = True -# -- Options for manual page output -------------------------------------------- +# -- Options for manual page output ------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -- cgit v1.2.3 From ae8c93c4923d8a3e522757f6f81b5a63138e7bdd Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 7 Oct 2010 08:55:35 -0400 Subject: some comment stubs --- source/bootloader.rst | 5 +++ source/conf.py | 6 ++-- source/index.rst | 19 ++++++++--- source/language.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++++ source/libmaple.rst | 5 +++ source/libraries.rst | 5 +++ source/unix-toolchain.rst | 5 +++ 7 files changed, 124 insertions(+), 7 deletions(-) create mode 100644 source/bootloader.rst create mode 100644 source/language.rst create mode 100644 source/libmaple.rst create mode 100644 source/libraries.rst create mode 100644 source/unix-toolchain.rst diff --git a/source/bootloader.rst b/source/bootloader.rst new file mode 100644 index 0000000..f893e1e --- /dev/null +++ b/source/bootloader.rst @@ -0,0 +1,5 @@ +================== + Maple Bootloader +================== + +stub diff --git a/source/conf.py b/source/conf.py index c12ebb9..e9c55b2 100644 --- a/source/conf.py +++ b/source/conf.py @@ -45,7 +45,7 @@ master_doc = 'index' # General information about the project. project = u'libmaple' -copyright = u'2010, Marti Bolivar, Perry Hung, Andrew Meyer, Brian Newbold' +copyright = u'2010, LeafLabs, LLC' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -184,7 +184,7 @@ htmlhelp_basename = 'libmapledoc' # (source start file, target file, title, author, documentclass [howto/manual]) latex_documents = [ ('index', 'libmaple.tex', u'libmaple Documentation', - u'Marti Bolivar, Perry Hung, Andrew Meyer, Brian Newbold', 'manual'), + u'LeafLabs, LLC', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -217,7 +217,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'libmaple', u'libmaple Documentation', - [u'Marti Bolivar, Perry Hung, Andrew Meyer, Brian Newbold'], 1) + [u'LeafLabs, LLC'], 1) ] diff --git a/source/index.rst b/source/index.rst index 0bf6b5a..92b2d5d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,18 +3,29 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to libmaple's documentation! -==================================== +Maple Documentation Index +========================= -Contents: +Welcome! This is the documentation index for programming your Maple. +It contains technical documentation, as well as some getting started +guides and example projects. + +.. TODO add projects + +Parts of the documentation: .. toctree:: :maxdepth: 2 + Language reference + Library reference + Unix toolchain + libmaple (C library) API + Maple bootloader + Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/source/language.rst b/source/language.rst new file mode 100644 index 0000000..edc027d --- /dev/null +++ b/source/language.rst @@ -0,0 +1,86 @@ +.. _language: + +========================== + Maple Language Reference +========================== + +The Maple can be programmed in a mostly-complete subset of the the +`Wiring `_ language, which is the +same language used to program the `Arduino `_ +boards. The entire language will be supported in a future release. +Please see the extensive `language reference +`_ on the Arduino webpage for +more information, or follow a direct link below. + +Unique Maple Additions +---------------------- + +``ASSERT(...)`` + The ``ASSERT()`` function can be very useful for basic program + debugging. The function accepts a boolean; for example: + + ``ASSERT(state == WAIT);`` + + zero is false and any other number is true. If the boolean is true + the assertion passes and the program continues as usual. If it is + false, the assertion fails: the program is halted, debug + information is printed to USART2, and the status LED begins to + throb in intensity (it's noticeably different from blinking). The + debug information is printed at 9600 baud and consists of the + filename and line number where the particular assertion failed. + + Including assertions in a program increases the program size. When + using libmaple from the command line, they can be silently + disabled by setting the ``DEBUG_LEVEL`` variable to ``DEBUG_NONE`` + in `libmaple.h <>`; in this case all assertions pass without any + lost clock cycles. + +Arduino Documentation Links +--------------------------- + +.. .. list-table:: Frozen Delights! +.. :widths: 15 10 30 +.. :header-rows: 1 + +.. * - Treat +.. - Quantity +.. - Description +.. * - Albatross +.. - 2.99 +.. - On a stick! +.. * - Crunchy Frog +.. - 1.49 +.. - If we took the bones out, it wouldn't be +.. crunchy, now would it? +.. * - Gannet Ripple +.. - 1.99 +.. - On a stick! + +.. ===== ===== ======= +.. A B A and B +.. ===== ===== ======= +.. False False False +.. True False False +.. False True False +.. True True True +.. ===== ===== ======= + +.. +------------------------+------------+----------+----------+ +.. | Header row, column 1 | Header 2 | Header 3 | Header 4 | +.. | (header rows optional) | | | | +.. +========================+============+==========+==========+ +.. | body row 1, column 1 | column 2 | column 3 | column 4 | +.. +------------------------+------------+----------+----------+ +.. | body row 2 | ... | ... | | +.. +------------------------+------------+----------+----------+ + +Recommended Reading +------------------- + +* `newlib Documentation `_ +* STMicro documentation for STM32F103RB microcontroller: + + * `All documents `_ + * `Datasheet (pdf) `_ + * `Reference Manual (pdf) `_ + * `Programming Manual (pdf) `_ (assembly language and register reference) diff --git a/source/libmaple.rst b/source/libmaple.rst new file mode 100644 index 0000000..c7e5c83 --- /dev/null +++ b/source/libmaple.rst @@ -0,0 +1,5 @@ +==================== + libmaple Reference +==================== + +Stub. diff --git a/source/libraries.rst b/source/libraries.rst new file mode 100644 index 0000000..0189e53 --- /dev/null +++ b/source/libraries.rst @@ -0,0 +1,5 @@ +========================= + Maple Library Reference +========================= + +Stub diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst new file mode 100644 index 0000000..8f7ce7c --- /dev/null +++ b/source/unix-toolchain.rst @@ -0,0 +1,5 @@ +================ + Unix Toolchain +================ + +Stub -- cgit v1.2.3 From 7fd798f71d7283245b1b43e38134c6d233861775 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 7 Oct 2010 12:40:02 -0400 Subject: language reference --- source/language.rst | 329 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 290 insertions(+), 39 deletions(-) diff --git a/source/language.rst b/source/language.rst index edc027d..eee4fe5 100644 --- a/source/language.rst +++ b/source/language.rst @@ -30,49 +30,300 @@ Unique Maple Additions filename and line number where the particular assertion failed. Including assertions in a program increases the program size. When - using libmaple from the command line, they can be silently - disabled by setting the ``DEBUG_LEVEL`` variable to ``DEBUG_NONE`` - in `libmaple.h <>`; in this case all assertions pass without any - lost clock cycles. + using libmaple **from the command line only**, they can be + disabled by making the definition + + ``#define DEBUG_LEVEL DEBUG_NONE`` + + before including either wirish or libmaple. In this case, all + assertions will pass without any lost clock cycles. Note that + this will **not work in the IDE**; even with this definition, + assertions will still be enabled. Arduino Documentation Links --------------------------- -.. .. list-table:: Frozen Delights! -.. :widths: 15 10 30 -.. :header-rows: 1 - -.. * - Treat -.. - Quantity -.. - Description -.. * - Albatross -.. - 2.99 -.. - On a stick! -.. * - Crunchy Frog -.. - 1.49 -.. - If we took the bones out, it wouldn't be -.. crunchy, now would it? -.. * - Gannet Ripple -.. - 1.99 -.. - On a stick! - -.. ===== ===== ======= -.. A B A and B -.. ===== ===== ======= -.. False False False -.. True False False -.. False True False -.. True True True -.. ===== ===== ======= - -.. +------------------------+------------+----------+----------+ -.. | Header row, column 1 | Header 2 | Header 3 | Header 4 | -.. | (header rows optional) | | | | -.. +========================+============+==========+==========+ -.. | body row 1, column 1 | column 2 | column 3 | column 4 | -.. +------------------------+------------+----------+----------+ -.. | body row 2 | ... | ... | | -.. +------------------------+------------+----------+----------+ +(This table was copied from http://arduino.cc/en/Reference/Extended). + ++------------------------------------+------------------------------------+-----------------------------------------+ +| Structure | Variables | Functions | +| | | | ++====================================+====================================+=========================================+ +| |**Constants** |**Digital I/O** | +|* `setup()`_ | | | +| |* `HIGH`_ | `LOW`_ |* `pinMode()`_ | +|* `loop()`_ | | | +| |* `INPUT`_ | `OUTPUT`_ |* `digitalWrite()`_ | +| | | | +|**Control Structures** |* `true`_ | `false`_ |* `digitalRead()`_ | +| | | | +|* `if`_ |* `integer constants`_ | | +| | |**Analog I/O** | +|* `if...else`_ |* `floating point constants`_ | | +| | |* `analogReference()`_ | +|* `for`_ | | | +| |**Data Types** |* `analogRead()`_ | +|* `switch/case`_ | | | +| |* `void`_ |* `analogWrite()`_ - PWM | +|* `while`_ | | | +| |* `boolean`_ | | +|* `do...while`_ | |**Advanced I/O** | +| |* `char`_ | | +|* `break`_ | |* `tone()`_ | +| |* `unsigned char`_ | | +|* `continue`_ | |* `noTone()`_ | +| |* `byte`_ | | +|* `return`_ | |* `shiftOut()`_ | +| |* `int`_ | | +|* `goto`_ | |* `pulseIn()`_ | +| |* `unsigned int`_ | | +| | | | +|**Further syntax** |* `word`_ |**Time** | +| | | | +|* `;`_ (semicolon) |* `long`_ |* `millis()`_ | +| | | | +|* `{}`_ (curly braces) |* `unsigned long`_ |* `micros()`_ | +| | | | +|* `//`_ (single line comment) |* `float`_ |* `delay()`_ | +| | | | +|* `/\* \*/`_ (multi-line comment) |* `double`_ |* `delayMicroseconds()`_ | +| | | | +|* `#define`_ |* `string`_ | | +| | |**Math** | +|* `#include`_ |* `array`_ | | +| | |* `min()`_ | +| | | | +|**Arithmetic Operators** |**Conversion** |* `max()`_ | +| | | | +|* `=`_ (assignment operator) |* `char()`_ |* `abs()`_ | +| | | | +|* `+`_ (addition) |* `byte()`_ |* `constrain()`_ | +| | | | +|* `-`_ (subtraction) |* `int()`_ |* `map()`_ | +| | | | +|* `*`_ (multiplication) |* `word()`_ |* `pow()`_ | +| | | | +|* `/`_ (division) |* `long()`_ |* `sqrt()`_ | +| | | | +|* `%`_ (modulo) |* `float()`_ | | +| | |**Trigonometry** | +| | | | +|**Comparison Operators** |**Variable Scope & Qualifiers** |* `sin()`_ | +| | | | +|* `==`_ (equal to) |* `variable scope`_ |* `cos()`_ | +| | | | +|* `!=`_ (not equal to) |* `static`_ |* `tan()`_ | +| | | | +|* `<`_ (less than) |* `volatile`_ | | +| | |**Random Numbers** | +|* `>`_ (greater than) |* `const`_ | | +| | |* `randomSeed()`_ | +|* `<=`_ (less than or equal to) | | | +| |**Utilities** |* `random()`_ | +|* `>=`_ (greater than or equal to) | | | +| |* `sizeof()`_ (sizeof operator) | | +| | |**Bits and Bytes** | +|**Boolean Operators** | | | +| | |* `lowByte()`_ | +|* `&&`_ (and) | | | +| | |* `highByte()`_ | +|* `||`_ (or) | | | +| | |* `bitRead()`_ | +|* `!`_ (not) | | | +| | |* `bitWrite()`_ | +| | | | +|**Pointer Access Operators** | |* `bitSet()`_ | +| | | | +|* `* dereference operator`_ | |* `bitClear()`_ | +| | | | +|* `& reference operator`_ | |* `bit()`_ | +| | | | +| | | | +|**Bitwise Operators** | |**External Interrupts** | +| | | | +|* `&`_ (bitwise and) | |For more information on external | +| | |interrupts on Maple, see | +|* `|`_ (bitwise or) | |`our reference page`_. | +| | | | +|* `^`_ (bitwise xor) | | | +| | |* `attachInterrupt()`_ | +|* `~`_ (bitwise not) | | | +| | |* `detachInterrupt()`_ | +|* `<<`_ (shift left) | | | +| | | | +|* `>>`_ (shift right) | |**Interrupts** | +| | | | +| | |* `interrupts()`_ | +|**Compound Operators** | | | +| | |* `noInterrupts()`_ | +|* `++`_ (increment) | | | +| | | | +|* `- -`_ (decrement) | |**Communication** | +| | | | +|* `+=`_ (compound addition) | |* `Serial`_ | +| | | | +|* `-=`_ (compound subtraction) | |Looking for something else? Try the list | +| | |of `community-contributed code`_. | +|* `*=`_ (compound multiplication) | | | +| | | | +|* `/=`_ (compound division) | | | +| | | | +|* `&=`_ (compound bitwise and) | | | +| | | | +|* `|=`_ (compound bitwise or) | | | +| | | | ++------------------------------------+------------------------------------+-----------------------------------------+ + +.. _setup(): http://arduino.cc/en/Reference/Setup +.. _loop(): http://arduino.cc/en/Reference/Loop +.. _if: http://arduino.cc/en/Reference/If +.. _if...else: http://arduino.cc/en/Reference/Else +.. _for: http://arduino.cc/en/Reference/For +.. _switch/case: http://arduino.cc/en/Reference/SwitchCase +.. _while: http://arduino.cc/en/Reference/While +.. _do...while: http://arduino.cc/en/Reference/DoWhile +.. _break: http://arduino.cc/en/Reference/Break +.. _continue: http://arduino.cc/en/Reference/Continue +.. _return: http://arduino.cc/en/Reference/Return +.. _goto: http://arduino.cc/en/Reference/Goto + +.. _;: http://arduino.cc/en/Reference/SemiColon +.. _{}: http://arduino.cc/en/Reference/Braces +.. _//: http://arduino.cc/en/Reference/Comments +.. _/\* \*/: http://arduino.cc/en/Reference/Comments +.. _#define: http://arduino.cc/en/Reference/Define +.. _#include: http://arduino.cc/en/Reference/Include + +.. _=: http://arduino.cc/en/Reference/Assignment +.. _+: http://arduino.cc/en/Reference/Arithmetic +.. _-: http://arduino.cc/en/Reference/Arithmetic +.. _*: http://arduino.cc/en/Reference/Arithmetic +.. _/: http://arduino.cc/en/Reference/Arithmetic +.. _%: http://arduino.cc/en/Reference/Modulo + +.. _==: http://arduino.cc/en/Reference/If +.. _!=: http://arduino.cc/en/Reference/If +.. _<: http://arduino.cc/en/Reference/If +.. _>: http://arduino.cc/en/Reference/If +.. _<=: http://arduino.cc/en/Reference/If +.. _>=: http://arduino.cc/en/Reference/If + +.. _&&: http://arduino.cc/en/Reference/Boolean +.. _||: http://arduino.cc/en/Reference/Boolean +.. _!: http://arduino.cc/en/Reference/Boolean + +.. _* dereference operator: http://arduino.cc/en/Reference/Pointer +.. _& reference operator: http://arduino.cc/en/Reference/Pointer + +.. _&: http://arduino.cc/en/Reference/BitwiseAnd +.. _|: http://arduino.cc/en/Reference/BitwiseAnd +.. _^: http://arduino.cc/en/Reference/BitwiseAnd +.. _~: http://arduino.cc/en/Reference/BitwiseXorNot +.. _<<: http://arduino.cc/en/Reference/Bitshift +.. _>>: http://arduino.cc/en/Reference/Bitshift + +.. _++: http://arduino.cc/en/Reference/Increment +.. FIXME can't freaking get two hyphens to show up! sphinx turns "--" +.. into an endash, whatever, fine, try to escape like "\-\-", that +.. ALSO becomes endash (!@#$), damn, well, maybe someone else is +.. eating my slash, try "\\-\\-", nope, that turns into a motherfing +.. \-\-. i hate everything. +.. _- -: http://arduino.cc/en/Reference/Increment +.. _+=: http://arduino.cc/en/Reference/IncrementCompound +.. _-=: http://arduino.cc/en/Reference/IncrementCompound +.. _*=: http://arduino.cc/en/Reference/IncrementCompound +.. _/=: http://arduino.cc/en/Reference/IncrementCompound +.. _&=: http://arduino.cc/en/Reference/BitwiseCompound +.. _|=: http://arduino.cc/en/Reference/BitwiseCompound + +.. _HIGH: http://arduino.cc/en/Reference/Constants +.. _LOW: http://arduino.cc/en/Reference/Constants +.. _INPUT: http://arduino.cc/en/Reference/Constants +.. _OUTPUT: http://arduino.cc/en/Reference/Constants +.. _true: http://arduino.cc/en/Reference/Constants +.. _false: http://arduino.cc/en/Reference/Constants +.. _integer constants: http://arduino.cc/en/Reference/IntegerConstants +.. _floating point constants: http://arduino.cc/en/Reference/Fpconstants + +.. _void: http://arduino.cc/en/Reference/Void +.. _boolean: http://arduino.cc/en/Reference/BooleanVariables +.. _char: http://arduino.cc/en/Reference/Char +.. _unsigned char: http://arduino.cc/en/Reference/UnsignedChar +.. _byte: http://arduino.cc/en/Reference/Byte +.. _int: http://arduino.cc/en/Reference/Int +.. _unsigned int: http://arduino.cc/en/Reference/UnsignedInt +.. _word: http://arduino.cc/en/Reference/Word +.. _long: http://arduino.cc/en/Reference/Long +.. _unsigned long: http://arduino.cc/en/Reference/UnsignedLong +.. _float: http://arduino.cc/en/Reference/Float +.. _double: http://arduino.cc/en/Reference/Double +.. _string: http://arduino.cc/en/Reference/String +.. _array: http://arduino.cc/en/Reference/Array + +.. _char(): http://arduino.cc/en/Reference/CharCast +.. _byte(): http://arduino.cc/en/Reference/ByteCast +.. _int(): http://arduino.cc/en/Reference/IntCast +.. _word(): http://arduino.cc/en/Reference/WordCast +.. _long(): http://arduino.cc/en/Reference/LongCast +.. _float(): http://arduino.cc/en/Reference/FloatCast + +.. _variable scope: http://arduino.cc/en/Reference/Scope +.. _static: http://arduino.cc/en/Reference/Static +.. _volatile: http://arduino.cc/en/Reference/Volatile +.. _const: http://arduino.cc/en/Reference/Const +.. _sizeof(): http://arduino.cc/en/Reference/Sizeof + +.. _pinMode(): http://arduino.cc/en/Reference/PinMode +.. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite +.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead + +.. _analogReference(): http://arduino.cc/en/Reference/AnalogReference +.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead +.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite + +.. _tone(): http://arduino.cc/en/Reference/Tone +.. _noTone(): http://arduino.cc/en/Reference/NoTone +.. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut +.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn + +.. _millis(): http://arduino.cc/en/Reference/Millis +.. _micros(): http://arduino.cc/en/Reference/Micros +.. _delay(): http://arduino.cc/en/Reference/Delay +.. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds + +.. _min(): http://arduino.cc/en/Reference/Min +.. _max(): http://arduino.cc/en/Reference/Max +.. _abs(): http://arduino.cc/en/Reference/Abs +.. _constrain(): http://arduino.cc/en/Reference/Constrain + +.. _map(): http://arduino.cc/en/Reference/Map +.. _pow(): http://arduino.cc/en/Reference/Pow +.. _sqrt(): http://arduino.cc/en/Reference/Sqrt + +.. _sin(): http://arduino.cc/en/Reference/Sin +.. _cos(): http://arduino.cc/en/Reference/Cos +.. _tan(): http://arduino.cc/en/Reference/Tan + +.. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed +.. _random(): http://arduino.cc/en/Reference/Random + +.. _lowByte(): http://arduino.cc/en/Reference/LowByte +.. _highByte(): http://arduino.cc/en/Reference/HighByte +.. _bitRead(): http://arduino.cc/en/Reference/BitRead +.. _bitWrite(): http://arduino.cc/en/Reference/BitWrite +.. _bitSet(): http://arduino.cc/en/Reference/BitSet +.. _bitClear(): http://arduino.cc/en/Reference/BitClear +.. _bit(): http://arduino.cc/en/Reference/Bit + +.. _our reference page: http://leaflabs.com/docs/external-interrupts/ +.. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt +.. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt + +.. _interrupts(): http://arduino.cc/en/Reference/Interrupts +.. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts + +.. _Serial: http://arduino.cc/en/Reference/Serial +.. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary Recommended Reading ------------------- -- cgit v1.2.3 From 255befff0f23f9d25b99e7a11499843eb7857e52 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 7 Oct 2010 12:44:43 -0400 Subject: language reference --- source/language.rst | 17 +++++++++-------- source/libraries.rst | 2 ++ 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/source/language.rst b/source/language.rst index eee4fe5..c5026c2 100644 --- a/source/language.rst +++ b/source/language.rst @@ -162,14 +162,14 @@ Arduino Documentation Links | | | | |* `+=`_ (compound addition) | |* `Serial`_ | | | | | -|* `-=`_ (compound subtraction) | |Looking for something else? Try the list | -| | |of `community-contributed code`_. | -|* `*=`_ (compound multiplication) | | | -| | | | -|* `/=`_ (compound division) | | | -| | | | -|* `&=`_ (compound bitwise and) | | | -| | | | +|* `-=`_ (compound subtraction) | |Looking for something else? See the | +| | |:ref:`libraries` page for interfacing | +|* `*=`_ (compound multiplication) | |with particular types of hardware. Try | +| | |the list of `community-contributed | +|* `/=`_ (compound division) | |code`_. Maple links against `newlib`_ | +| | |and allows the use of any of its | +|* `&=`_ (compound bitwise and) | |functions; see its documentation for more| +| | |details. | |* `|=`_ (compound bitwise or) | | | | | | | +------------------------------------+------------------------------------+-----------------------------------------+ @@ -324,6 +324,7 @@ Arduino Documentation Links .. _Serial: http://arduino.cc/en/Reference/Serial .. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary +.. _newlib: http://sourceware.org/newlib/ Recommended Reading ------------------- diff --git a/source/libraries.rst b/source/libraries.rst index 0189e53..374b71c 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -1,3 +1,5 @@ +.. _libraries: + ========================= Maple Library Reference ========================= -- cgit v1.2.3 From eea59af14296be010b920992a7383f67aab59b1b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 7 Oct 2010 12:45:46 -0400 Subject: language reference --- source/language.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/language.rst b/source/language.rst index c5026c2..3772872 100644 --- a/source/language.rst +++ b/source/language.rst @@ -162,15 +162,15 @@ Arduino Documentation Links | | | | |* `+=`_ (compound addition) | |* `Serial`_ | | | | | -|* `-=`_ (compound subtraction) | |Looking for something else? See the | -| | |:ref:`libraries` page for interfacing | -|* `*=`_ (compound multiplication) | |with particular types of hardware. Try | -| | |the list of `community-contributed | -|* `/=`_ (compound division) | |code`_. Maple links against `newlib`_ | -| | |and allows the use of any of its | -|* `&=`_ (compound bitwise and) | |functions; see its documentation for more| -| | |details. | -|* `|=`_ (compound bitwise or) | | | +|* `-=`_ (compound subtraction) | |**Looking for something else?** | +| | | | +|* `*=`_ (compound multiplication) | |See the :ref:`libraries` page for | +| | |interfacing with particular types of | +|* `/=`_ (compound division) | |hardware. Try the list of | +| | |`community-contributed code`_. Maple | +|* `&=`_ (compound bitwise and) | |links against `newlib`_ and allows the | +| | |use of any of its functions; see its | +|* `|=`_ (compound bitwise or) | |documentation for more details. | | | | | +------------------------------------+------------------------------------+-----------------------------------------+ -- cgit v1.2.3 From 2eb7dee002654d645a84cbb5c1e88aad7c45528d Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 7 Oct 2010 20:12:29 -0400 Subject: lots more docs --- source/_static/img/blinky-to-flash.png | Bin 0 -> 22657 bytes source/_static/img/blinky.png | Bin 0 -> 21042 bytes source/_static/img/codeblocks_build.png | Bin 0 -> 112088 bytes source/_static/img/codeblocks_makefile.png | Bin 0 -> 75653 bytes source/_static/img/codeblocks_maketargets.png | Bin 0 -> 56250 bytes source/_static/img/codeblocks_newproject.png | Bin 0 -> 45930 bytes source/_static/img/libmaple-screenshot-small.png | Bin 0 -> 38023 bytes source/_static/img/verify-success.png | Bin 0 -> 26460 bytes source/_static/img/verify_button.png | Bin 0 -> 1800 bytes source/conf.py | 8 +- source/index.rst | 20 +- source/language.rst | 181 ++++++++- source/libmaple-api.rst | 7 + source/libmaple.rst | 34 +- source/libraries.rst | 114 +++++- source/maple-ide-install.rst | 10 + source/maple-quickstart.rst | 256 ++++++++++++ source/troubleshooting.rst | 9 + source/unix-toolchain.rst | 497 ++++++++++++++++++++++- 19 files changed, 1109 insertions(+), 27 deletions(-) create mode 100755 source/_static/img/blinky-to-flash.png create mode 100755 source/_static/img/blinky.png create mode 100644 source/_static/img/codeblocks_build.png create mode 100644 source/_static/img/codeblocks_makefile.png create mode 100644 source/_static/img/codeblocks_maketargets.png create mode 100644 source/_static/img/codeblocks_newproject.png create mode 100644 source/_static/img/libmaple-screenshot-small.png create mode 100755 source/_static/img/verify-success.png create mode 100644 source/_static/img/verify_button.png create mode 100644 source/libmaple-api.rst create mode 100644 source/maple-ide-install.rst create mode 100644 source/maple-quickstart.rst create mode 100644 source/troubleshooting.rst diff --git a/source/_static/img/blinky-to-flash.png b/source/_static/img/blinky-to-flash.png new file mode 100755 index 0000000..0320c5b Binary files /dev/null and b/source/_static/img/blinky-to-flash.png differ diff --git a/source/_static/img/blinky.png b/source/_static/img/blinky.png new file mode 100755 index 0000000..bda4cee Binary files /dev/null and b/source/_static/img/blinky.png differ diff --git a/source/_static/img/codeblocks_build.png b/source/_static/img/codeblocks_build.png new file mode 100644 index 0000000..c98bcdc Binary files /dev/null and b/source/_static/img/codeblocks_build.png differ diff --git a/source/_static/img/codeblocks_makefile.png b/source/_static/img/codeblocks_makefile.png new file mode 100644 index 0000000..a0ef21f Binary files /dev/null and b/source/_static/img/codeblocks_makefile.png differ diff --git a/source/_static/img/codeblocks_maketargets.png b/source/_static/img/codeblocks_maketargets.png new file mode 100644 index 0000000..bbb68cb Binary files /dev/null and b/source/_static/img/codeblocks_maketargets.png differ diff --git a/source/_static/img/codeblocks_newproject.png b/source/_static/img/codeblocks_newproject.png new file mode 100644 index 0000000..8d08d1f Binary files /dev/null and b/source/_static/img/codeblocks_newproject.png differ diff --git a/source/_static/img/libmaple-screenshot-small.png b/source/_static/img/libmaple-screenshot-small.png new file mode 100644 index 0000000..f2be783 Binary files /dev/null and b/source/_static/img/libmaple-screenshot-small.png differ diff --git a/source/_static/img/verify-success.png b/source/_static/img/verify-success.png new file mode 100755 index 0000000..6928674 Binary files /dev/null and b/source/_static/img/verify-success.png differ diff --git a/source/_static/img/verify_button.png b/source/_static/img/verify_button.png new file mode 100644 index 0000000..37100db Binary files /dev/null and b/source/_static/img/verify_button.png differ diff --git a/source/conf.py b/source/conf.py index e9c55b2..7f2b3b4 100644 --- a/source/conf.py +++ b/source/conf.py @@ -44,7 +44,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'libmaple' +project = u'Maple' copyright = u'2010, LeafLabs, LLC' # The version info for the project you're documenting, acts as replacement for @@ -169,7 +169,7 @@ html_static_path = ['_static'] #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'libmapledoc' +htmlhelp_basename = 'mapledoc' # -- Options for LaTeX output ------------------------------------------------- @@ -183,7 +183,7 @@ htmlhelp_basename = 'libmapledoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target file, title, author, documentclass [howto/manual]) latex_documents = [ - ('index', 'libmaple.tex', u'libmaple Documentation', + ('index', 'maple.tex', u'Maple Documentation', u'LeafLabs, LLC', 'manual'), ] @@ -216,7 +216,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'libmaple', u'libmaple Documentation', + ('index', 'maple', u'Maple Documentation', [u'LeafLabs, LLC'], 1) ] diff --git a/source/index.rst b/source/index.rst index 92b2d5d..ec7313d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,25 +3,29 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. _index: + Maple Documentation Index ========================= Welcome! This is the documentation index for programming your Maple. -It contains technical documentation, as well as some getting started -guides and example projects. +It contains tutorials, quickstarts, and technical documentation. -.. TODO add projects +If you just got a new Maple, you probably want the :ref:`Maple +quickstart `. -Parts of the documentation: +Table of contents: .. toctree:: :maxdepth: 2 - Language reference - Library reference - Unix toolchain - libmaple (C library) API + Maple Quickstart Guide + Maple IDE Installation Guide + Wiring/Arduino Language Reference + Wiring/Arduino Library Reference + libmaple Documentation and APIs Maple bootloader + Troubleshooting Indices and tables ================== diff --git a/source/language.rst b/source/language.rst index 3772872..6634f9d 100644 --- a/source/language.rst +++ b/source/language.rst @@ -1,25 +1,31 @@ +.. highlight:: c++ + .. _language: ========================== Maple Language Reference ========================== -The Maple can be programmed in a mostly-complete subset of the the -`Wiring `_ language, which is the -same language used to program the `Arduino `_ -boards. The entire language will be supported in a future release. -Please see the extensive `language reference +The Maple can be programmed in the `Wiring +`_ language, which is the same +language used to program the `Arduino `_ boards. +The entire language will be supported in a future release. Please see +the extensive `language reference `_ on the Arduino webpage for more information, or follow a direct link below. +C or C++ programmers curious about the differences between the Wiring +language and C++ may wish to skip to the +:ref:`arduino_c_for_c_hackers`. + Unique Maple Additions ---------------------- ``ASSERT(...)`` The ``ASSERT()`` function can be very useful for basic program - debugging. The function accepts a boolean; for example: + debugging. The function accepts a boolean; for example:: - ``ASSERT(state == WAIT);`` + ASSERT(state == WAIT); zero is false and any other number is true. If the boolean is true the assertion passes and the program continues as usual. If it is @@ -31,9 +37,9 @@ Unique Maple Additions Including assertions in a program increases the program size. When using libmaple **from the command line only**, they can be - disabled by making the definition + disabled by making the definition :: - ``#define DEBUG_LEVEL DEBUG_NONE`` + #define DEBUG_LEVEL DEBUG_NONE before including either wirish or libmaple. In this case, all assertions will pass without any lost clock cycles. Note that @@ -326,6 +332,163 @@ Arduino Documentation Links .. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary .. _newlib: http://sourceware.org/newlib/ +.. _arduino_c_for_c_hackers: + +Note for C/C++ Programmers +-------------------------- + +This is a note for programmers comfortable with C or C++ (although, +you C programmers should remember that `C++ is not a superset of C +`_) who +want a better understanding of the differences between C++ and the +Wiring language. The good news is that the differences are relatively +few. + +A *sketch* is the IDE's notion of a project; it consists of one or +more files written in the Wiring language, which is mostly the same as +C++. The major difference between the two is that in Wiring, it's not +necessary to declare global functions before they are used. That is, +the following is valid Wiring, and ``f()`` returns ``5``:: + + int f() { + return g(); + } + + int g() { + return 5; + } + +All of the files in a sketch share the same (global) namespace. That +is, the behavior is as if all of a sketch's files were part of the +same translation unit, so they don't have to include one another in +order to access each other's definitions. The only other major +difference between Wiring and C++ is that Wiring doesn't support +dynamically allocated memory -- that is, ``new`` and ``delete`` won't +work. As of |today|, Maple only has 20 KB RAM, anyway, so it's +doubtful that static allocation is not what you want. + +The Wiring language also does not require you to define your own +``main`` method (in fact, it forbids you from doing so). Instead, you +are required to define two functions, ``setup`` and ``loop``, with +type signatures :: + + void setup(void) + void loop(void) + +Once a sketch is uploaded to a Maple and begins to run, ``setup()`` is +called once, and then ``loop()`` is called repeatedly. The IDE +compilation process proceeds via a source-to-source translation from +the files in a sketch to C++. + +This translation process first concatenates the sketch files, then +parses the result to produce a list of all functions defined in the +global scope. (We borrow this stage from the Arduino IDE, which in +turn borrows it from Wiring. It uses regular expressions to parse +C++, which is, of course, `Bad and Wrong +`_. An +upcoming rewrite of the IDE performs this preprocessing step +correctly, using a real parser. Until then, you have our apologies.) +The order in which the individual sketch files are concatenated is not +defined; it is unwise to write code that depends on a particular +ordering. + +The concatenated sketch files are then appended onto a file which +includes `WProgram.h +`_ +(which includes the wirish and libmaple libraries, and declares +``setup()`` and ``loop()``), and then provides declarations for all +the function definitions found in the previous step. At this point, +we have a file that is a valid C++ translation unit, but lacks a +``main()`` method. The final step of compilation provides this +method, which behaves roughly like:: + + int main(void) { + setup(); + while (true) loop(); + } + +(The truth is a little bit more complicated, but not by much). + +As an example, consider a sketch with two files. The first file +contains ``setup()`` and ``loop()``:: + + int the_pin; + + void setup() { + the_pin = choose_a_pin(); + pinMode(the_pin, OUTPUT); + } + + void loop() { + static int toggle = 0; + toggle ^= 1; + digitalWrite(the_pin, toggle); + } + +The second file contains the (not very useful) implementation for +``choose_a_pin()``:: + + int choose_a_pin() { + return random(5, 15); + } + +Then the results of the concatenation process might be :: + + int the_pin; + + void setup() { + the_pin = choose_a_pin(); + pinMode(the_pin, OUTPUT); + } + + void loop() { + static int toggle = 0; + toggle ^= 1; + digitalWrite(the_pin, toggle); + } + + int choose_a_pin(void); + + int choose_a_pin() { + return random(5, 15); + } + +Which could plausibly be turned into the final source file :: + + #include "WProgram.h" + + void setup(void); + void loop(void); + int choose_a_pin(void); + + int the_pin; + + void setup() { + the_pin = choose_a_pin(); + pinMode(the_pin, OUTPUT); + } + + void loop() { + static int toggle = 0; + toggle ^= 1; + digitalWrite(the_pin, toggle); + } + + int choose_a_pin(void); + + int choose_a_pin() { + return random(5, 15); + } + + int main() { + setup(); + while (true) loop(); + } + +(Recall that it's legal C++ for a function to be declared multiple +times, as long as it's defined exactly once). + + Recommended Reading ------------------- diff --git a/source/libmaple-api.rst b/source/libmaple-api.rst new file mode 100644 index 0000000..df9a4d9 --- /dev/null +++ b/source/libmaple-api.rst @@ -0,0 +1,7 @@ +.. _libmaple_api: + +======================== + libmaple API reference +======================== + +Stub. diff --git a/source/libmaple.rst b/source/libmaple.rst index c7e5c83..620fdfa 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -1,5 +1,37 @@ +.. highlight:: sh + +.. _libmaple: + ==================== libmaple Reference ==================== -Stub. +.. image:: /_static/img/libmaple-screenshot-small.png + :align: center + :alt: libmaple screenshot + +`LeafLabs libmaple `_ is the low level library we have developed for for the ARM +Cortex-M3 chips manufactured by STMicroelectronics used in the Maple +boards (the `STM32F103x`_ series). We found the generic peripheral +libraries too painful to build on top of, and reimplemented the +functionality we needed in a simpler (and less general) form. + +.. _libmaple-libmaple: http://github.com/leaflabs/libmaple +.. _STM32F103x: http://www.st.com/stonline/stappl/productcatalog/app?path=/pages/stcom/PcStComPartNumberSearch.searchPartNumber&search=stm32f103 + +This library is transparently included in the `Maple IDE +`_, but we develop it separately +using good old Unix command line tools and release it for advanced +users who might chafe at the “sketch” programming model of the +IDE. Included are some examples, a Makefile, and the compatibility +wrappers and code to imitate the Arduino programming library. + +**Check out the latest source**:: + + git clone git://github.com/leaflabs/libmaple.git + +.. toctree:: + :maxdepth: 2 + + Unix Toolchain Quickstart + libmaple API reference diff --git a/source/libraries.rst b/source/libraries.rst index 374b71c..1f298fa 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -1,7 +1,119 @@ +.. highlight:: c++ +.. default-domain:: cpp + .. _libraries: ========================= Maple Library Reference ========================= -Stub +This page briefly summarizes the Arduino libraries that have been ported to Maple. You can use a library from within a sketch by going to Sketch > Import Library... from within the IDE, then choosing the library you want. + +Any incompatibilities between the Maple and Arduino versions are noted in the description of the library. + +* :ref:`LiquidCrystal ` +* :ref:`Wire ` + +.. _liquid_crystal: + +LiquidCrystal +------------- + +The LiquidCrystal library allows Maple to control LCD screens. For more information, see the Arduino LiquidCrystal documentation. +Compatibility Note + +At this time, no incompatibilities between the Maple and Arduino versions are known. Any observed differences should be considered bugs, and reported on the forums. + +.. _wire: + +Wire +---- + +We provide a soft (bit-banged) implementation of the `Wire I2C library +`_. + +Compatibility Note +^^^^^^^^^^^^^^^^^^ + +This implementation is synchronous, and thus supports only a subset of +the full Wire interface (however, the functionality which is supported +is fully compatible with Arduino). For now, please use the function +reference which follows when developing projects using our +implementation. + +Please note that the current implementation only supports master mode +using a bit-banged (software) protocol. Future enhancements will use +the hardware i2c peripheral on the stm32 as well as the DMA for +performance. Support for slave, smBUS, and multimaster modes are also +slated for inclusion in the enhanced Wire port. + +Function Reference +^^^^^^^^^^^^^^^^^^ + +``Wire.begin()`` + Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL + (this is compatible with the pin settings on the Arduino Mega). + +``Wire.begin(sda, scl)`` + Like ``Wire.begin()``, but with the given pins as SDA and + SCL. + +``Wire.beginTransmission(slave_address)`` + Set up a transmission to a slave device with the given (7-bit) + address. Bytes subsequently queued for transmission (using + ``Wire.send``) will be sent to ``slave_address`` when ``void + Wire.endTransmission()`` is called. + +``void Wire.send(byte)`` + Queues the given byte (``uint8`` or ``int``) to the slave address + previously specified by a call to ``Wire.beginTransmission``. At + most 32 bytes may be queued in a single transmission. + +``Wire.send(string)`` + Queues a given string (``char*``) for transmission. The characters + of the string are individually queued for transmission as + bytes. At most 32 bytes may be queued in a single transmission. + +``Wire.send(buffer, length)`` + Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with + ``length`` elements, for transmission. At most 32 bytes may be + queued in a single transmission. + +``Wire.endTransmission()`` + Ends a transmission (begun by ``Wire.beginTransmission(uint8)``), + and actually sends the bytes queued by calls to Wire.send. + + The return value is one of the following status codes: + + * ``SUCCESS``: All bytes were transmitted successfully. + + * ``EDATA``: More than 32 bytes were queued for transmission. No + bytes are actually sent when this happens. + + * ``ENACKADDR``: Did not receive ACK on transmit of address. No + bytes are actually sent when this happens. + + * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some + bytes may have been sent when this happens; however, the + transmission is aborted after the first byte of data which is + not ACKed by the slave device. + + * ``EOTHER``: Other error occurred. + +``Wire.requestFrom(address, num_bytes)`` + Requests ``num_bytes`` bytes from 7-bit slave address + address. Returns the actual number of bytes read. These bytes may + subsequently be read one at a time using ``Wire.receive()``. + + Note: if ``num_bytes`` exceeds the size of the transmit/receive + buffer (currently 32), it will be truncated to 32. + +``Wire.receive()`` + Get and return the next byte read during the previous call to + ``Wire.requestFrom(uint8, int)``. You can check how many bytes are + left to read using ``uint8 Wire.available()``. + +``Wire.available()`` + Returns the number of bytes which are still available for reading + (with ``Wire.receive()``) from the last call to + ``Wire.requestFrom(uint8, int)``. diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst new file mode 100644 index 0000000..b84df76 --- /dev/null +++ b/source/maple-ide-install.rst @@ -0,0 +1,10 @@ +.. _maple-ide-install: + +======================== + Maple IDE Installation +======================== + +.. _maple-ide-install-java: +.. _maple-ide-install-windows-drivers: + +Stub. diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst new file mode 100644 index 0000000..8184772 --- /dev/null +++ b/source/maple-quickstart.rst @@ -0,0 +1,256 @@ +.. highlight:: sh + +.. _maple-quickstart: + +======================== + Maple Quickstart Guide +======================== + +You'll need a `Maple board `_, a `mini-b +USB cable `_, a +functional computer, and possibly root (or "administrator") access to +that computer. + +If you have trouble along the way try the :ref:`install page +` for more detailed download and installation +instructions, and the :ref:`troubleshooting page ` +for help with some common problems. If all else fails, try our `forum +`_, or `contact us directly +`_! + +The major steps are: + +* :ref:`Download and install the IDE ` + +* :ref:`(Windows) Resolve driver issues ` + +* :ref:`Run the IDE `, then :ref:`compile + and upload a simple Blink program ` + +* Test the USB serial connection with a HelloWorld + +.. _maple-quickstart-download: + +1. Download the IDE +------------------- + +Choose the correct version for your operating system: + +.. list-table:: + :widths: 15 30 50 + :header-rows: 1 + + * - Platform + - Status + - IDE Package + * - Windows + - Tested on 32bit Windows XP + - `maple-ide-LATEST-windowsxp32.zip `_ (about 75mb) + * - Linux + - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) + - `maple-ide-LATEST-linux32.tgz `_ (about 30mb) + + `maple-ide-LATEST-linux64.tgz `_ (about 30mb) + * - Mac OSX + - Tested on Snow Leopard 10.6 (64bit and 32bit) + - `maple-ide-LATEST-macosx-10_6.dmg `_ (about 40mb) + +.. note:: + + The Linux release requires that you have a Java runtime (JRE) + installed. If you're on Linux, don't have a JRE, and don't know how + to install one, see the :ref:`installation page + `. + +The package bundles together a compiler, an upload utility, a software +library, and a simple GUI text editor. All this software is `free and +open `_; we are grateful to the `Arduino +`_, `CodeSourcery +`_, `GNU `_, and +`OpenMoko `_ developers, as well as many others, +who allow us to reuse their software. + +2. Install the IDE +------------------ + +**Windows:** + +First, extract all the files in the ZIP file to a suitable location on +your system (like your Desktop folder). + +Next, you'll have to install drivers; see the :ref:`installation page +` for more details. Sorry! + +**Linux:** + +Extract the tarball to an appropriate location (like your +home directory or desktop). + +Make sure you have a Java runtime (JRE) installed; if you can run +:command:`java` from the shell, you should be fine. For instructions +on installing a JRE, try the :ref:`installation page +` or searching the package manager for your +distribution. + +Next, run the script :file:`install-udev-rules.sh` in the extracted +IDE directory. It will ask for root permissions. You now need to +restart udev:: + + sudo /etc/init.d/udev restart + +This will grant members of the group ``plugdev`` read/write access to +Maple devices over USB. Make sure that you are in that group. (For +more information on why this is part of the install process, see the +:ref:`Unix toolchain quickstart `). + +**OS X:** + +Double-click on the :file:`.dmg` file you downloaded in :ref:`Step 1 +`. + +Next, drag and drop the Maple IDE icon into your computer's +Applications folder. + +.. _maple-quickstart-run-ide: + +3. Run the IDE +-------------- + +**Windows:** + +Double-click on the :command:`maple-ide` program from within the +extracted IDE directory. + +**Linux:** + +Run :file:`maple-ide` from the shell, or double click on it if your +window system supports it. + +**OS X:** + +Double-click the :command:`Maple IDE` application you dragged into +your computer's :file:`Applications` folder. + +.. _maple-quickstart-compile-blinky: + +4. Compile a program! +--------------------- + +Let's load up a simple example program that blinks the status LED. +From the File menu, select Examples > Digital > Blink: + +.. image:: /_static/img/blinky.png + :align: center + :alt: Click "Blink" + +Next, select Tools > Board > "LeafLabs Maple ... to FLASH": + +.. image:: /_static/img/blinky-to-flash.png + :align: center + :alt: Upload to FLASH + +.. note:: + + You have the option between RAM and FLASH programming: FLASH saves + the program into permanent memory so the program will be run every + time the Maple is reset, while RAM simply injects the compiled + program into the processor's memory. + + Programming to RAM is faster to upload and a buggy program can be + wiped away with a simple reset, while FLASH memory is larger and is + the only option for permanently uploading a program. + +.. image:: /_static/img/verify_button.png + :align: left + :alt: Verify button + +Now press the "verify" button (furthest to the left with a "play" +arrow) to compile the code. Some output should scroll by in the +bottom window, and then a confirmation message will appear: + +.. image:: /_static/img/verify-success.png + :align: center + :alt: Code verified successfully. + +5. Upload that program! +----------------------- + +Now it's (finally!) time to plug in your Maple. Use a mini-b cable, +making sure that the power source jumper is on the USB header +first. + +The Maple should blink a short pattern on the blue status LED every +time it is plugged in, reset, or reprogrammed, just to let you know +it's there. If it ever starts throbbing in a slow, smooth pattern that +means you've got a problem: see the troubleshooting page. + +On OS X, a modem setup dialog will pop up every time you plug in the +Maple. If you go to System Preferences Network Settings and accept +the default ("unconfigured") settings, the dialog won't pop up and +everything will work fine. + +If all systems are go, select the Board type and Serial Port +(something like /dev/ttyACM0, /dev/cu.usbmodem5d21, or COM3 depending +on your platform) from the Tools menu. Then press the "upload" button +(right arrow to a bunch of dots) to upload your program to the +Maple. You should see some text and a progress bar flash by in the +status window of the IDE, then some blinky patterns on the Maple, and +then a constant blink with whatever time period you programmed in +above. + +Go ahead and modify the file a little bit: if you change the +'delay(1000);' numbers to a different value the speed of the blink +will change. The value is a time in milliseconds to pause before +continuing with the program, so by default the LED will be on for 1 +second, then off for 1 second, etc. + +.. warning:: + + This step is the most common source of problems, especially on + Windows. + + The situation is much improved over the past, but if you have + trouble, try doing things again, unplugging your Maple and plugging + it back in, using :ref:`perpetual bootloader mode + `, or restarting the + IDE. + + Please report any problems in the forums. If we don't know it's + broken, we can't fix it! + +6. Use the serial port monitor! +------------------------------- + +As a last step to make sure everything has been configured correctly, +let's upload a hello world program that will send text from the Maple +back to the IDE over the USB connection. From File select Examples, +Stubs, HelloWorld, and make sure the correct board and serial port +targets are selected from the Tools pull-down. And of course you could +change the text to be printed out; make sure you leave the double +quotes around it though or you'll get a compile error. + +Open the serial monitor window (button on the far right) and make sure +the 9600 baud speed is selected. Then go back to the code editing +window and upload your program (upload will recompile your code +automatically if there's been any change since the last "verify"). You +should get text spit at you over the serial monitor right after the +program is uploaded. Shout back! We can hear you! + +7. Go forth exuberantly! +------------------------ + +We really hope you got this far and didn't frown or make a bitter +lemon face too often getting here. Where you go now is up to you: +perhaps you've got some crazy project cooking, or a longer tutorial to +work through, or maybe now is a good time for a trip to the kitchen +for a delicious sandwich. + +If you blew through this guide and are the kind of person who drinks +their coffee straight and has more than a 100 lines of vim or emacs +customization and doesn't even have a mouse plugged into your computer +you may want to look at the Unix Toolchain quickstart guide to getting +working with your old friends make, jtag, and gcc. + +Let us know what you come up with! Tag internet content with +#leaflabs, post in the forums, track us down in the real world, +whatever. We love projects! diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst new file mode 100644 index 0000000..0aba027 --- /dev/null +++ b/source/troubleshooting.rst @@ -0,0 +1,9 @@ +.. _troubleshooting: + +======================= + Maple Troubleshooting +======================= + +.. _troubleshooting-perpetual-bootloader: + +Stub. diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 8f7ce7c..9939979 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -1,5 +1,494 @@ -================ - Unix Toolchain -================ +.. highlight:: sh -Stub +.. _unix-toolchain: + +=========================== + Unix Toolchain Quickstart +=========================== + +You'll need a Maple board, a mini-b USB cable, a functional computer, +and root access to that computer. This guide assumes you've had +success with the IDE on your machine and that you are fairly +comfortable with the Unix command line; some previous experience with +editing your shell startup script (.bashrc, .tcshrc, etc.) and using +`make `_ is recommended. For +generic installation/setup issues, the `IDE install +`_ and +:ref:`troubleshooting` pages may be helpful. If all else fails, try +our `forum`_, or `contact us directly `_! + +.. _forum: http://forums.leaflabs.com + +We currently have instructions for 32- and 64-bit Linux and OS X Snow +Leopard. If you're on another Unix platform, Windows, or an earlier +version of OS X, we're guessing that you can translate/port these +directions on your own. As a jumping off point, you might want to +begin with these `stripped down distributions +`_ of the `CodeSourcery +GCC compiler tools `_ +(including win32 versions). If you do have success on other platforms, +please post in the forums, so we can fold your tips into this +document! + +* :ref:`Linux setup ` +* :ref:`OS X setup ` +* :ref:`Test compilation ` +* :ref:`Upload a program ` +* :ref:`Communicate over USB-serial interface ` +* :ref:`Starting your own projects ` +* :ref:`Debug with OpenOCD ` +* :ref:`Do it all with Code::Blocks ` +* :ref:`Go forth exuberantly! ` + +.. _toolchain-linux-setup: + +Linux Setup +----------- + +These instructions are oriented towards Linux users using a +contemporary Debian-based distribution. + +**1. Collect and Install Tools** + +First I'll give the commands to run, then explain:: + + $ sudo aptitude install build-essential git-core wget screen dfu-util \ + openocd python python-serial + +You'll want to install a bunch of developer "basics" like +:command:`make`, :command:`tar`, etc. A good catch-all for these +tools is the "build-essential" meta-package on most debian platforms: +installing this fake package will pull in dozens of useful tools +without bogging your system down too much. ``git-core`` is the name of +the git package; `Git `_ is a distributed code +versioning system we use to track changes in our source +code. :command:`wget` is a simple tool to download files over http +from the command line, and is optional (you could pull in the required +downloads using a browser). :command:`screen` is a really cool virtual +terminal program; in the context of Maple, we use it to connect to +serial port devices. + +:command:`dfu-util` is a tool from the `OpenMoko`_ project that we use +to upload programs to the Maple over USB. + +.. _OpenMoko: http://openmoko.com/ + +:command:`openocd` is a `JTAG +`_ control +program used in conjunction with an ARM JTAG device to do in circuit +debugging (pause/resume program execution, upload and download code, +read out register status, etc). (optional) + +Lastly, our reset script (which sends control signals over the +USB-serial connection to restart and enter the bootloader) is written +in Python and requires the `PySerial +`_ library (the ``python-serial`` +package; this could also be installed with `easy_install +`_). + +**2. Fetch libmaple and Compiler Toolchain** :: + + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git libmaple + $ cd libmaple + $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz + $ tar xvf arm-*-linux32.tar.gz + $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up + +This step is fairly straightforward: do a git clone of the `libmaple +repository `_ to some directory, +then download and extract the ARM compiler toolchain. + +The :file:`arm/bin/` directory will need to be added to +:envvar:`PATH`; you can check that this worked by entering +``arm-none-`` and hitting tab to auto-complete (bash should show a +bunch of results). Regardless of where you put the toolchain, make +sure to preserve its internal directory layout, as the binaries make +relative path calls and references. + +.. _toolchain-udev: + +**3. Install udev Rules** + +From the libmaple directory, :: + + $ groups # make sure it includes plugdev; if not add, yourself to it + $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules + $ sudo /etc/init.d/udev restart + +As a security precaution on linux, unknown USB devices can only be +accessed by the superuser. This udev script identifies the Maple based +on its vendor and product IDs, mounts it to :file:`/dev/maple`, and +grants read/write permissions to the ``plugdev`` group. After +restarting :command:`udev` you'll need to fully unplug or power cycle +any Maples connected to the computer. + +**So far, so good?** + +Great! Test your setup by :ref:`compiling a sample program +`. + +.. _toolchain-osx-setup: + +OS X Setup +---------- + +These instructions have been tested successfully on OS X 10.6.4. As +stated previously, this document assumes a general level of Unix +aptitude on the part of the reader; if you're uncomfortable using +Terminal (or if you don't know what that means), then you should +probably stick with using the `Maple IDE +`_ to develop programs. Some of +these software packages might be available on `MacPorts +`_. The author had some bad experiences with +MacPorts a few years ago, though, and hasn't touched it since. Of +course, your mileage may vary. + +**1. Collect and Install Tools** + +You will need the following tools to get started: + + 1. `XCode `_: If + you're reading this, you've probably already got this. Provides + compilers and other basic tools of the trade. It's a free download, + but requires registration (gross, we know). + + 2. `Git `_: All of our code is tracked by a + distributed versioning system called git. A `Mac installer + `_ + is available. + + 3. :command:`dfu-util`: A tool from `OpenMoko`_ that we use to upload + programs to the Maple over USB. If you're feeling masochistic, there + are instructions for `building dfu-util from source + `_. + + However, if you've got better things to do, you can steal a dfu-util + binary from a program called `Openmoko Flasher + `_. To + do this, first `download Openmoko Flasher + `_, then copy + the .app into your :file:`/Applications` folder (or wherever you + like). Let's pretend you saved the .app to the directory + + :file:`/Applications/OpenMoko Flasher.app` + + Then the :command:`dfu-util` binary resides in + + :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` + + To get access to it from the command line, just make a symbolic link + to the binary from some place on your :envvar:`PATH`:: + + $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ + /somewhere/on/your/PATH/dfu-util + + .. note:: + Just copying the binary somewhere doesn't work, as it relies on + dynamically linked libraries found elsewhere in the .app + bundle. It's possible to pull just the relevant pieces out of the + .app, but you're on your own. + + To make sure this worked, try plugging in your Maple, making sure + it's in bootloader mode (you can do this by pressing RESET, then + quickly pressing BUT and holding it for several seconds), then + running :: + + $ dfu-util -l + + If you see some lines that look like :: + + Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00" + Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000" + + then you're all set. + + 4. PySerial: our reset script (which sends control signals over the + USB-serial connection to restart and enter the bootloader) is written + in Python and requires the `PySerial + `_ library. Download the `latest + version `_. After you download + and untar, install it with :: + + $ cd /path/to/pyserial-x.y + $ python setup.py build + $ sudo python setup.py install + + The package is also available via :command:`easy_install`, so if + you're comfortable using that, you could also install it with :: + + $ easy_install pyserial + +**2. Fetch libmaple and Compiler Toolchain** + +You first need to clone libmaple:: + + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git libmaple + +Then you need to get the cross-compilers we use to build a +project. These are just modified versions of GCC; you can `download +them for OS X here +`_. Assuming +you saved this file to + + :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz` + +you can then unpack the archive and let OS X know where the compilers +live with :: + + $ cd ~/Downloads + $ tar -xvzf gcc-blah-blah-macosx32.tar.gz + $ mv arm ~/libmaple/arm + +After that's done, you'll probably want to update your shell startup +script to stick :file:`~/libmaple/arm/bin` into your :envvar:`PATH`. + +**So far, so good?** + +Great! Go on to the next section, where you test everything out. + +.. _toolchain-test: + +Test compilation +---------------- + +Get back into the libmaple directory (this tutorial assumes you put it +in :file:`~/libmaple`) and test that you've installed all the compilation +tools correctly:: + + $ cd ~/libmaple + $ cp main.cpp.example main.cpp + $ make clean + $ make + +If it all works out, you should end up seeing something like this:: + + find build -iname *.o | xargs arm-none-eabi-size -t + text data bss dec hex filename + 482 4 24 510 1fe build/wirish/comm/HardwareSerial.o + 260 0 0 260 104 build/wirish/comm/HardwareSPI.o + 60 0 0 60 3c build/wirish/wirish.o + + [...] + + 2196 0 1 2197 895 build/libmaple/usb/usb_lib/usb_core.o + 1904 0 0 1904 770 build/libmaple/usb/usb_lib/usb_regs.o + 56 0 0 56 38 build/libmaple/usb/usb_lib/usb_init.o + 344 0 0 344 158 build/libmaple/usb/usb_hardware.o + 6637 0 58 6695 1a27 build/main.o + 21499 201 391 22091 564b (TOTALS) + + Final Size: + arm-none-eabi-size build/maple.out + text data bss dec hex filename + 21824 200 552 22576 5830 build/maple.out + Flash build + +Woo! It worked. The ``dec`` field at the end gives the total program +size in bytes. The long listing of object files above the ``Final +Size`` helps to identify bloated code. As you write larger projects, +you may find that they use too much space. If that happens, the +file-by-file listing will help you track down the fatties porking up +your program. + +.. _toolchain-upload: + +Upload a program +---------------- + +Ok, let's blow away the little example program and upload the +interactive test session to your Maple. This will let you interact +textually with the Maple via USB-serial. If you're on Linux, then +before executing :command:`make install`, you'll want to have the udev +rules setup :ref:`as described above `. Plug in your Maple +using the mini-b USB cable; then run :: + + $ cd ~/libmaple + $ cp examples/test-session.cpp main.cpp + $ make clean + $ make + $ make install + +A number of things can go wrong at this stage. Simple debugging steps +include using :ref:`perpetual bootloader mode +`, restarting the Maple a couple +times, :command:`make clean`, etc. If nothing works, the `forum`_ is +your friend. + +.. _toolchain-serialusb: + +Communicate over USB-serial interface +------------------------------------- + +Okay, now that we've flashed the interactive test session to the +Maple, let's test it out. The device for the maple should look +something like :file:`/dev/ttyACMXXX` on Linux or +:file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly +different name on your system. To open up a session, run :: + + $ screen /dev/tty-whatever-it-is + +If the interactive test program built and uploaded correctly, you +should be able to connect without any errors reported by +:command:`screen`. Type ``h`` or hit the space bar to get a response; +there are a number of commands which demonstrate Maple peripheral +features. As of October 2010, the HardwareSerial library is blocking, +so using any commands which would write to the USART Serial ports will +cause the program to hang. To exit the screen session, type :kbd:`C-a +C-\\` (control-a, followed by control-backslash), and type ``y`` when +prompted if you're sure. + +Using :command:`screen` in this way sometimes messes up your session. +If your shell starts acting up after you exit screen, you should be +able to fix it with :: + + $ reset && clear + +.. _toolchain-projects: + +Starting your own projects +-------------------------- + +So everything worked, and you want to start your own project? Great! +It's easy. Just set the environment variable :envvar:`LIB_MAPLE_HOME` +in your shell startup script to point to the libmaple repository you +cloned (this tutorial assumes you put it in :file:`~/libmaple`). For +example, if you use bash as your shell, just put this line in your +:file:`~/.bashrc` or :file:`~/.bash_profile`:: + + export LIB_MAPLE_HOME=~/libmaple + +Now, in order to start your own projects, just grab a copy of the +:file:`Makefile` and skeleton :file:`main.cpp` we provided in the +libmaple repository, and you're good to go:: + + $ cd + $ mkdir my-awesome-project + $ cp ~/libmaple/Makefile ~/libmaple/build-targets.mk my-awesome-project + $ cp ~/libmaple/main.cpp.example my-awesome-project/main.cpp + +(TEMPORARY: The file :file:`build-targets.mk` is where the rule to +build the object file for :file:`main.cpp` lives. If you have multiple +source files, you'll probably need to look at it and edit as +appropriate. We're sorry about that and will update the Makefile +structure later to remove this pain point.) Then hack away! You can +:command:`make`, :command:`make clean`, and :command:`make install` +from your new directory :file:`my-awesome-project` just like you did +in the libmaple repository. + +.. note:: + + We update the libmaple repository fairly frequently with bugfixes + and other improvements. In order get access to these in your local + copy of the repository, you should periodically update it with:: + + $ cd $LIB_MAPLE_HOME + $ git pull + + The `commits page + `_ for the + github repository is a good place to watch for bleeding-edge + updates; our `blog `_ is the place to + watch for major releases. We keep releases of libmaple and the + Maple IDE in lockstep, so any IDE updates will have corresponding + library updates. + +.. _toolchain-openocd: + +Debug with OpenOCD +------------------ + +TODO. For now see `this great guide +`_ from fun-tech.se. + +.. _toolchain-codeblocks: + +Do it all with Code::Blocks +--------------------------- + +.. TODO this really should reflect the new, more pleasant build system + +Optional. `Code::Blocks `_ is a generic +cross platform IDE. We don't personally use it for development, so we +haven't worked out all the kinks (e.g., debugging isn't integrated), +but it might be helpful for people who are allergic to `vim +`_ and/or `Emacs +`_. The simple configuration +described here just calls down to the :file:`Makefile`, so follow the +above directions to get the command line tools configured (you'll +definitely need the arm-none-eabi-* tools on your :envvar:`PATH`), +then `install Code::Blocks +`_. You can do this on Linux +with:: + + $ sudo aptitude install codeblocks + +The first time it runs you'll maybe want to disable all the glitzy +"Getting Started" crap (when will they learn?). We've added a .cbp +"projects" file to the libmaple repository: you can try using that one +by copying it from :file:`support/codeblocks/libmaple.cbp` to the top +level directory, but no promises (it might be missing new source files +etc). It's probably worth reading through these instructions as well +to get a feel for how it all works. + +To create your own "libmaple" project, start with an "Empty Project" +with the "Folder to create project in" set to your +:envvar:`LIB_MAPLE_HOME`. Make sure that the "Resulting filename" is +in the top level directory as well. + +.. image:: /_static/img/codeblocks_newproject.png + :align: center + :alt: Code::Blocks new project wizard + +Select the "GNU GCC Compiler" (it won't be used, anyway) and disable +the "Debug" configuration in the next window. Now you should have a +project with no files; add files by right clicking on the project in +the left panel file hierarchy and "Add files recursively". Import both +the :file:`wirish` and :file:`libmaple` directories recursively, then +add :file:`main.cpp` separately. + +.. image:: /_static/img/codeblocks_makefile.png + :align: center + :alt: Code::Blocks targets options + +Next we have to configure the Makefile targets. Go to the +"Properties..." menu under "Project" and check the "This is a custom +Makefile" box. Then go to the "Build targets" tab and create "ram" and +"flash" targets, both of type "Console application" and without the +Auto-generated filename prefixes or extensions. Set the Output +filename to :file:`support/codeblocks/program_flash.sh` and +:file:`support/codeblocks/program_ram.sh` respectively; these scripts +just call the program_ram/program_flash make targets and are a hack to +get the "run" button to upload code to the Maple. The IDE will warn +that these files will be overwritten, but they won't be. For both the +"flash" and "ram" targets, click the "Build options..." button (below +"Virtual targets..." etc) and go to the far right tab ("'Make' +commands"). Edit the Clean project/target line so it's just "clean" +(not "clean$target"), and set the "Build project/target" and "Compile +single file" commands to ``$make -f $makefile MAPLE_TARGET=$target`` +and ``$make -f $makefile MAPLE_TARGET=$target $file``, respectively. + +.. image:: /_static/img/codeblocks_maketargets.png + :align: center + :alt: Code::Blocks make targets + +Save all these changes, go back to the main IDE window, and try to +build/run. "Build" will compile everything, "Run" will run the upload +script in a terminal window (if there are problems they will flash by +very quickly; you can start Code::Blocks in a terminal window and +check the output in that base window if necessary), and "Rebuild" will +clean before rebuilding. + +.. image:: /_static/img/codeblocks_build.png + :align: center + :alt: Success! + +.. _toolchain-exuberantly: + +Go forth exuberantly! +--------------------- + +Let us know what you come up with! Use #leaflabs on Twitter, post in +the `forum`_, track us down in the real world, whatever. We love +projects! -- cgit v1.2.3 From 20b3718c015db98433da121485fa6bb7ab88faa7 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 8 Oct 2010 22:07:53 -0400 Subject: current Maple documentation either rewritten or stubbed out in Sphinx --- source/_static/img/blinky-to-flash.png | Bin source/_static/img/blinky.png | Bin .../_static/img/osx-network-prefs-unconfigured.png | Bin 0 -> 81770 bytes source/_static/img/osx-unconfigured-popup.png | Bin 0 -> 28359 bytes source/_static/img/serial-port-mac.png | Bin 0 -> 64284 bytes source/_static/img/serial-port-ubuntu.png | Bin 0 -> 46629 bytes source/_static/img/serial-port-win.png | Bin 0 -> 15183 bytes source/_static/img/upload-button.png | Bin 0 -> 9993 bytes source/_static/img/verify-success.png | Bin source/adc.rst | 7 + source/bootloader.rst | 126 +++++++++- source/compatibility.rst | 7 + source/errata.rst | 7 + source/gpio.rst | 7 + source/hardware.rst | 24 ++ source/i2c.rst | 9 + source/index.rst | 14 +- source/jtag.rst | 7 + source/language.rst | 129 ++++++---- source/libraries.rst | 21 +- source/maple-ide-install.rst | 148 +++++++++++- source/maple-quickstart.rst | 266 +++++++++------------ source/pwm.rst | 7 + source/spi.rst | 7 + source/timers.rst | 7 + source/troubleshooting.rst | 239 +++++++++++++++++- source/unix-toolchain.rst | 10 +- source/usart.rst | 7 + source/usb.rst | 7 + 29 files changed, 832 insertions(+), 224 deletions(-) mode change 100755 => 100644 source/_static/img/blinky-to-flash.png mode change 100755 => 100644 source/_static/img/blinky.png create mode 100644 source/_static/img/osx-network-prefs-unconfigured.png create mode 100644 source/_static/img/osx-unconfigured-popup.png create mode 100644 source/_static/img/serial-port-mac.png create mode 100644 source/_static/img/serial-port-ubuntu.png create mode 100644 source/_static/img/serial-port-win.png create mode 100644 source/_static/img/upload-button.png mode change 100755 => 100644 source/_static/img/verify-success.png create mode 100644 source/adc.rst create mode 100644 source/compatibility.rst create mode 100644 source/errata.rst create mode 100644 source/gpio.rst create mode 100644 source/hardware.rst create mode 100644 source/i2c.rst create mode 100644 source/jtag.rst create mode 100644 source/pwm.rst create mode 100644 source/spi.rst create mode 100644 source/timers.rst create mode 100644 source/usart.rst create mode 100644 source/usb.rst diff --git a/source/_static/img/blinky-to-flash.png b/source/_static/img/blinky-to-flash.png old mode 100755 new mode 100644 diff --git a/source/_static/img/blinky.png b/source/_static/img/blinky.png old mode 100755 new mode 100644 diff --git a/source/_static/img/osx-network-prefs-unconfigured.png b/source/_static/img/osx-network-prefs-unconfigured.png new file mode 100644 index 0000000..70d2fa0 Binary files /dev/null and b/source/_static/img/osx-network-prefs-unconfigured.png differ diff --git a/source/_static/img/osx-unconfigured-popup.png b/source/_static/img/osx-unconfigured-popup.png new file mode 100644 index 0000000..a43ad57 Binary files /dev/null and b/source/_static/img/osx-unconfigured-popup.png differ diff --git a/source/_static/img/serial-port-mac.png b/source/_static/img/serial-port-mac.png new file mode 100644 index 0000000..b3a1989 Binary files /dev/null and b/source/_static/img/serial-port-mac.png differ diff --git a/source/_static/img/serial-port-ubuntu.png b/source/_static/img/serial-port-ubuntu.png new file mode 100644 index 0000000..8038e41 Binary files /dev/null and b/source/_static/img/serial-port-ubuntu.png differ diff --git a/source/_static/img/serial-port-win.png b/source/_static/img/serial-port-win.png new file mode 100644 index 0000000..90dc1c4 Binary files /dev/null and b/source/_static/img/serial-port-win.png differ diff --git a/source/_static/img/upload-button.png b/source/_static/img/upload-button.png new file mode 100644 index 0000000..20a663f Binary files /dev/null and b/source/_static/img/upload-button.png differ diff --git a/source/_static/img/verify-success.png b/source/_static/img/verify-success.png old mode 100755 new mode 100644 diff --git a/source/adc.rst b/source/adc.rst new file mode 100644 index 0000000..17c672d --- /dev/null +++ b/source/adc.rst @@ -0,0 +1,7 @@ +.. _adc: + +===== + ADC +===== + +Stub. diff --git a/source/bootloader.rst b/source/bootloader.rst index f893e1e..17cd34b 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -1,5 +1,129 @@ +.. highlight:: sh + ================== Maple Bootloader ================== -stub +The firmware which allows the Maple to be reprogrammed via a USB +connection. Every Maple board comes programmed with this by default, +and it is not overwritten by regular programs (it lives lower in the +Flash memory and only runs when the chip is reset). + +**Check out the latest source code version:** :: + + git clone git://github.com/leaflabs/maple-bootloader.git + +**Visit the github development project**: http://github.com/leaflabs/maple-bootloader + +Bootloader Schemes Explained! +----------------------------- + +Maple Rev 3 (the version currently shipping) represents a drastic +remake of the core library as well as the upload process. Some of +these changes are aesthetic, refactoring and reorganization. Some are +performance minded. The changes to the bootloader, however, were +implemented to solve some really gritty cross platform issues. Before +delving in to how the Rev1 bootloader worked and how the Rev 3 +bootloader works now, lets look at the features common to both of them +and touch a bit on the Arduino setup. This is a fairly involved +explanation, with a lot of details that are likely only interesting to +a few. If you just want to get the rough idea, skim this article. If +you want to start hacking on the bootloader, get in touch with us to +get even more info on how this all works. Of course, you can always +checkout the code at github! + +Arduino +^^^^^^^ + +Arduino is based off of AVR series micro controllers, most of which +lack USB support. Thus, boards like the Duemilanove add USB capability +via an FTDI USB to Serial converter chip. This chip interfaces with +the AVR over…serial. When you plug an Arduino into a computer only an +FTDI driver is needed. Since the FTDI chip is separate from the AVR, +you can reset the Arduino without closing this USB connection with the +FTDI chip. To program an Arduino, the host machine sends a command +over the USB pipe (reset DTR) which in turn resets the AVR. The AVR +will boot into a bootloader, which waits for a second for any upload +commands over serial. The host machine can either send those commands, +or do nothing. In which case the AVR will quickly jump to user code +and off you go. The whole process is quick, the bootloader doesn’t +live for very long, and will exit almost immediately if no upload +commands are received. + +Maple Rev1: The Horror... +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Maple is based off the STM32 (ARM cortex M3) series chips, which do +have embedded USB support. Thus, Maple doesn’t need the extra FTDI +chip. Firmware is uploaded via the standard DFU protocol (also used by +iPhone and openMoko). Since DFU is a standard, there is no need for +custom software running on the host to upload the firmware. Any DFU +compliant program will work. The maple ide is based around +:command:`dfu-util`, openMoko’s DFU utility. Using DFU came at a cost, +however. The USB port must additionally implement a separate serial +port at the same time (we use the CDC ACM class for serial +functionality). + +Maple Rev 1 attempted to run both DFU and CDC ACM devices +simultaneously on the USB peripheral. On Linux, this worked great. The +OS would service the DFU driver during uploads, and the CDC ACM for +serial port transactions. There was no reset necessary for uploads. No +waiting. The bootloader was always running the background, ready to +receive commands. + +The problem was that ONLY Linux did this. Windows refused to attach +more than one driver to a single USB device without repackaging the +DFU and CDC ACM into a single IAD Compound Device. It's not terribly +important what this means, except for two things. + +1. Four drivers were necessary to make everything work. +2. IAD is not supported by OS X. + +Mac, on the other hand, only supported Compound USB, a different trick +that is not supported by Windows. While a perpetual background +bootloader was attractive, it became clear, after much toiling, we +were going to have to write some custom drivers across several +platforms to make everything work this way. + +Maple Rev3 +^^^^^^^^^^ + +Maple Rev 3 takes a completely different tack, more along the lines of +Arduino. In Rev 3, the device resets into bootloader mode, which +stays alive for a few moments to receive commands and then jumps to +user code. The bootloader is implemented as a DFU device – just a DFU +device, no serial port. This requires one driver for windows +(:file:`drivers/mapleDrv/dfu`). As part of the :ref:`libmaple` +library, user code is automatically supplied with serial support via +some behind the scenes work that happens automatically when you +compile (``setupUSB()`` is appended to ``setup()``). This user mode +code only implements a CDC ACM class USB device, giving you functions +like ``Usb.print()``. Separating these two modes fixed the driver +issue, there are no complicated compound usb device nonsense, and the +scheme works well across platforms, requiring only two drivers (serial +and DFU) on Windows. + +However, it is no longer possible to upload code at will, since there +is no bootloader quietly listening in the background. Instead you have +to reset the board, then initiate a DFU transaction. This reset is +performed automatically by the IDE by sending a command over the USB +serial port. You can generate this reset on your own using a python +script or some other scheme. All you need do is: + +1. Pulse DTR (high and then low, so that youve created a negative + edge) +2. Write “1EAF” in ASCII over the serial pipe. This will cause Maple + to reset. Only the first 4 bytes after a negative edge of DTR are + checked for this command, so its important you actually create a + negative edge, rather than just ensuring DTR is low. + +After the reset, the host OS takes a few moments (.5-2 seconds) to +re-enumerate the device as DFU. This delay is unpredictable, and its +the reason the bootloader on Maple Rev3 stays alive for so +long. Sometimes the bootloader was exiting before the OS had even +enumerated the device! Once in bootloader mode, however, +:command:`dfu-util` uploads your sketch into either flash or ram (dfu +alternate setting 0 or 1 respectively) and resets the board again. +This time, however, no DFU transaction is initiated and the bootloader +gives way to user code, closing down the DFU pipe and bringing up the +USB serial. diff --git a/source/compatibility.rst b/source/compatibility.rst new file mode 100644 index 0000000..aeed36b --- /dev/null +++ b/source/compatibility.rst @@ -0,0 +1,7 @@ +.. _compatibility: + +============================= + Maple-Arduino Compatibility +============================= + +Stub. diff --git a/source/errata.rst b/source/errata.rst new file mode 100644 index 0000000..b702bd1 --- /dev/null +++ b/source/errata.rst @@ -0,0 +1,7 @@ +.. _errata: + +======== + Errata +======== + +Stub. diff --git a/source/gpio.rst b/source/gpio.rst new file mode 100644 index 0000000..f608a61 --- /dev/null +++ b/source/gpio.rst @@ -0,0 +1,7 @@ +.. _gpio: + +====== + GPIO +====== + +Stub. diff --git a/source/hardware.rst b/source/hardware.rst new file mode 100644 index 0000000..1fa3554 --- /dev/null +++ b/source/hardware.rst @@ -0,0 +1,24 @@ +.. _hardware: + +================================= + Hardware-Specific Documentation +================================= + +This page indexes the Maple's capabilities for interacting with +external hardware peripherals. For information about a particular +device or protocol, see its individual reference page. + +Individual reference pages: + +.. toctree:: + :maxdepth: 2 + + i2c + pwm + gpio + usb + jtag + adc + spi + usart + timers diff --git a/source/i2c.rst b/source/i2c.rst new file mode 100644 index 0000000..e0444eb --- /dev/null +++ b/source/i2c.rst @@ -0,0 +1,9 @@ +.. _i2c: + +===== +|i2c| +===== + +.. |i2c| replace:: I\ :sup:`2`\ C + +Stub. diff --git a/source/index.rst b/source/index.rst index ec7313d..cdf151d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -11,21 +11,27 @@ Maple Documentation Index Welcome! This is the documentation index for programming your Maple. It contains tutorials, quickstarts, and technical documentation. -If you just got a new Maple, you probably want the :ref:`Maple -quickstart `. +If you just got a new Maple, you probably want to begin with the +:ref:`quickstart `. You can then move on to reading +about the programming language you use with the Maple at the +:ref:`language reference `. Good luck, and have fun! Table of contents: +.. TODO: be more Pythonic with a "parts of the documentation" thing .. toctree:: :maxdepth: 2 Maple Quickstart Guide Maple IDE Installation Guide - Wiring/Arduino Language Reference - Wiring/Arduino Library Reference + Maple/Arduino Compatibility Reference + Maple Language Reference + Maple Library Reference libmaple Documentation and APIs Maple bootloader Troubleshooting + Hardware-Specific Documentation + Known Problems Indices and tables ================== diff --git a/source/jtag.rst b/source/jtag.rst new file mode 100644 index 0000000..e94229f --- /dev/null +++ b/source/jtag.rst @@ -0,0 +1,7 @@ +.. _jtag: + +====== + JTAG +====== + +Stub. diff --git a/source/language.rst b/source/language.rst index 6634f9d..7bf71c6 100644 --- a/source/language.rst +++ b/source/language.rst @@ -9,11 +9,17 @@ The Maple can be programmed in the `Wiring `_ language, which is the same language used to program the `Arduino `_ boards. -The entire language will be supported in a future release. Please see -the extensive `language reference +Please see the extensive `language reference `_ on the Arduino webpage for more information, or follow a direct link below. +.. warning:: + + The Arduino boards have different sizes for data types, so don't + trust their documentation for how many bytes an ``int``, ``long``, + etc. take up. The sizes of each data type on the Maple are given + in the :ref:`table below `. + C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the :ref:`arduino_c_for_c_hackers`. @@ -21,6 +27,8 @@ language and C++ may wish to skip to the Unique Maple Additions ---------------------- +.. _language-assert: + ``ASSERT(...)`` The ``ASSERT()`` function can be very useful for basic program debugging. The function accepts a boolean; for example:: @@ -46,6 +54,8 @@ Unique Maple Additions this will **not work in the IDE**; even with this definition, assertions will still be enabled. +.. _language-arduino-docs: + Arduino Documentation Links --------------------------- @@ -70,73 +80,73 @@ Arduino Documentation Links |* `for`_ | | | | |**Data Types** |* `analogRead()`_ | |* `switch/case`_ | | | -| |* `void`_ |* `analogWrite()`_ - PWM | -|* `while`_ | | | -| |* `boolean`_ | | -|* `do...while`_ | |**Advanced I/O** | -| |* `char`_ | | -|* `break`_ | |* `tone()`_ | -| |* `unsigned char`_ | | -|* `continue`_ | |* `noTone()`_ | -| |* `byte`_ | | -|* `return`_ | |* `shiftOut()`_ | -| |* `int`_ | | -|* `goto`_ | |* `pulseIn()`_ | -| |* `unsigned int`_ | | -| | | | -|**Further syntax** |* `word`_ |**Time** | -| | | | -|* `;`_ (semicolon) |* `long`_ |* `millis()`_ | -| | | | -|* `{}`_ (curly braces) |* `unsigned long`_ |* `micros()`_ | -| | | | -|* `//`_ (single line comment) |* `float`_ |* `delay()`_ | +| |Primitive data types on the Maple |* `analogWrite()`_ - PWM | +|* `while`_ |have different sizes than on the | | +| |Arduino, since the Maple has a full | | +|* `do...while`_ |32-bit processor. The size of each |**Advanced I/O** | +| |such type on the Maple is given | | +|* `break`_ |below. |* `tone()`_ | | | | | -|* `/\* \*/`_ (multi-line comment) |* `double`_ |* `delayMicroseconds()`_ | +|* `continue`_ |The ``word`` type is (deliberately) |* `noTone()`_ | +| |:ref:`not supported | | +|* `return`_ |`. |* `shiftOut()`_ | | | | | -|* `#define`_ |* `string`_ | | -| | |**Math** | -|* `#include`_ |* `array`_ | | -| | |* `min()`_ | +|* `goto`_ |* `void`_ |* `pulseIn()`_ | | | | | -|**Arithmetic Operators** |**Conversion** |* `max()`_ | +| |* `boolean`_ (1 byte) | | +|**Further syntax** | |**Time** | +| |* `char`_ (1 byte) | | +|* `;`_ (semicolon) | |* `millis()`_ | +| |* `unsigned char`_ (1 byte) | | +|* `{}`_ (curly braces) | |* `micros()`_ | +| |* `byte`_ (1 byte) | | +|* `//`_ (single line comment) | |* `delay()`_ | +| |* `int`_ (4 bytes) | | +|* `/\* \*/`_ (multi-line comment) | |* `delayMicroseconds()`_ | +| |* `unsigned int`_ (4 bytes) | | +|* `#define`_ | | | +| |* `long`_ (8 bytes) |**Math** | +|* `#include`_ | | | +| |* `unsigned long`_ (8 bytes) |* `min()`_ | | | | | -|* `=`_ (assignment operator) |* `char()`_ |* `abs()`_ | +|**Arithmetic Operators** |* `float`_ (4 bytes) |* `max()`_ | | | | | -|* `+`_ (addition) |* `byte()`_ |* `constrain()`_ | +|* `=`_ (assignment operator) |* `double`_ (8 bytes) |* `abs()`_ | | | | | -|* `-`_ (subtraction) |* `int()`_ |* `map()`_ | +|* `+`_ (addition) |* `string`_ |* `constrain()`_ | | | | | -|* `*`_ (multiplication) |* `word()`_ |* `pow()`_ | +|* `-`_ (subtraction) |* `array`_ |* `map()`_ | | | | | -|* `/`_ (division) |* `long()`_ |* `sqrt()`_ | +|* `*`_ (multiplication) | |* `pow()`_ | +| |**Conversion** | | +|* `/`_ (division) | |* `sqrt()`_ | +| |* `char()`_ | | +|* `%`_ (modulo) | | | +| |* `byte()`_ |**Trigonometry** | | | | | -|* `%`_ (modulo) |* `float()`_ | | -| | |**Trigonometry** | +|**Comparison Operators** |* `int()`_ |* `sin()`_ | | | | | -|**Comparison Operators** |**Variable Scope & Qualifiers** |* `sin()`_ | +|* `==`_ (equal to) |* `word()`_ |* `cos()`_ | | | | | -|* `==`_ (equal to) |* `variable scope`_ |* `cos()`_ | +|* `!=`_ (not equal to) |* `long()`_ |* `tan()`_ | | | | | -|* `!=`_ (not equal to) |* `static`_ |* `tan()`_ | -| | | | -|* `<`_ (less than) |* `volatile`_ | | +|* `<`_ (less than) |* `float()`_ | | | | |**Random Numbers** | -|* `>`_ (greater than) |* `const`_ | | -| | |* `randomSeed()`_ | +|* `>`_ (greater than) | | | +| |**Variable Scope & Qualifiers** |* `randomSeed()`_ | |* `<=`_ (less than or equal to) | | | -| |**Utilities** |* `random()`_ | +| |* `variable scope`_ |* `random()`_ | |* `>=`_ (greater than or equal to) | | | -| |* `sizeof()`_ (sizeof operator) | | +| |* `static`_ | | | | |**Bits and Bytes** | -|**Boolean Operators** | | | +|**Boolean Operators** |* `volatile`_ | | | | |* `lowByte()`_ | -|* `&&`_ (and) | | | +|* `&&`_ (and) |* `const`_ | | | | |* `highByte()`_ | |* `||`_ (or) | | | -| | |* `bitRead()`_ | +| |**Utilities** |* `bitRead()`_ | |* `!`_ (not) | | | -| | |* `bitWrite()`_ | +| |* `sizeof()`_ (sizeof operator) |* `bitWrite()`_ | | | | | |**Pointer Access Operators** | |* `bitSet()`_ | | | | | @@ -180,6 +190,27 @@ Arduino Documentation Links | | | | +------------------------------------+------------------------------------+-----------------------------------------+ +.. _language-no-word: + +.. note:: + + The ``word`` data type is not supported on the Maple. This is by + choice. + + We decided not to include it because, while the Maple has 32-bit + words, the word size on an Arduino board is only 16 bits, and code + that uses the ``word`` type is likely to rely on that fact. + + By not supporting ``word``, you'll get a compile error when porting + Arduino code to your Maple instead of potentially weird, + hard-to-debug runtime behavior. + + If you're porting over Arduino code and really want ``word``, you + can put the following at the top of the file you're porting:: + + typedef uint16 word; + + .. _setup(): http://arduino.cc/en/Reference/Setup .. _loop(): http://arduino.cc/en/Reference/Loop .. _if: http://arduino.cc/en/Reference/If diff --git a/source/libraries.rst b/source/libraries.rst index 1f298fa..c2d5cb0 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -7,9 +7,13 @@ Maple Library Reference ========================= -This page briefly summarizes the Arduino libraries that have been ported to Maple. You can use a library from within a sketch by going to Sketch > Import Library... from within the IDE, then choosing the library you want. +This page briefly summarizes the Arduino libraries that have been +ported to Maple. You can use a library from within a sketch by going +to Sketch > Import Library... from within the IDE, then choosing the +library you want. -Any incompatibilities between the Maple and Arduino versions are noted in the description of the library. +Any incompatibilities between the Maple and Arduino versions are noted +in the description of the library. * :ref:`LiquidCrystal ` * :ref:`Wire ` @@ -19,10 +23,14 @@ Any incompatibilities between the Maple and Arduino versions are noted in the de LiquidCrystal ------------- -The LiquidCrystal library allows Maple to control LCD screens. For more information, see the Arduino LiquidCrystal documentation. -Compatibility Note +The LiquidCrystal library allows Maple to control LCD screens. For +more information, see the Arduino LiquidCrystal documentation. -At this time, no incompatibilities between the Maple and Arduino versions are known. Any observed differences should be considered bugs, and reported on the forums. +**Compatibility Note** + +At this time, no incompatibilities between the Maple and Arduino +versions are known. Any observed differences should be considered +bugs, and reported on the forums. .. _wire: @@ -32,8 +40,7 @@ Wire We provide a soft (bit-banged) implementation of the `Wire I2C library `_. -Compatibility Note -^^^^^^^^^^^^^^^^^^ +**Compatibility Note** This implementation is synchronous, and thus supports only a subset of the full Wire interface (however, the functionality which is supported diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index b84df76..46c903b 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -1,10 +1,154 @@ +.. highlight:: c++ + .. _maple-ide-install: ======================== Maple IDE Installation ======================== +If you still can't get the IDE installed after reading this page, +check the :ref:`troubleshooting page ` for help with +some common problems. If all else fails, try our `forum`_, or `contact +us directly `_! + +.. _forum: http://forums.leaflabs.com + +Download +-------- + +Choose the correct version for your operating system: + +.. list-table:: + :widths: 15 30 50 + :header-rows: 1 + + * - Platform + - Status + - IDE Package + * - Windows + - Tested on 32bit Windows XP + - `maple-ide-LATEST-windowsxp32.zip `_ (about 75mb) + * - Linux + - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) + - `maple-ide-LATEST-linux32.tgz `_ (about 30mb) + + `maple-ide-LATEST-linux64.tgz `_ (about 30mb) + * - Mac OSX + - Tested on Snow Leopard 10.6 (64bit and 32bit) + - `maple-ide-LATEST-macosx-10_6.dmg `_ (about 40mb) + +The package bundles together a compiler, an upload utility, a software +library, and a simple GUI text editor. All this software is `free and +open `_; we are grateful to the `Arduino +`_, `CodeSourcery +`_, `GNU `_, and +`OpenMoko `_ developers, as well as many others, +who allow us to reuse their software. + +Installation +------------ + +* :ref:`Windows ` +* :ref:`Linux ` +* :ref:`OS X ` + +.. _maple-ide-install-windows: + +Windows +^^^^^^^ +First, extract all the files in the ZIP file to a suitable location on +your system (like your Desktop folder). Next, you have to install +some drivers. Sorry! + +First, install DFU drivers (for uploading code to your Maple) using +the following steps. + +1. Plug your Maple into the USB port. + +2. Hit the reset button on your Maple (it's the small button at the + bottom left, labeled RESET). Notice that it blinks quickly 6 times, + then blinks slowly a few more times. + +3. Hit reset again, and this time push and hold the other button + during the 6 fast blinks (the button is on the top right; it is + labeled BUT). You can release it once the slow blinks start. + +4. Your Maple is now in :ref:`perpetual bootloader mode + `. This should give you a + chance to install the DFU drivers. + +5. Windows should now prompt you for some drivers. In the top level + directory of the Maple IDE, point Windows to + :file:`drivers/mapleDrv/dfu/`. + +Next, install serial drivers (for communicating with your Maple using +serial over USB). + +1. Reset your Maple and allow it to exit the bootloader (wait for the + slow blinking to stop). The Maple will next start running whatever + program was uploaded to it last. (New Maples will start running the + test program we upload to them before shipping them to you). + +2. Once Maple is running some user code, Windows should prompt you for + more drivers. Point windows to :file:`driver/mapleDrv/serial`. + +You can now run the Maple IDE by double-clicking on the +:command:`maple-ide` program from within the extracted IDE directory. + +.. _maple-ide-install-linux: + +Linux +^^^^^ + .. _maple-ide-install-java: -.. _maple-ide-install-windows-drivers: +.. note:: + + The IDE is written in Java and requires a compatible runtime (JRE). + + If you don't have one, they're usually pretty easy to install. Sun + Java 1.6 and OpenJDK 1.6 are known to work, and runtimes mostly + compatible with Sun Java 1.5+ should probably get the job done. + + To install Java, try using your distribution's software packaging + tool and search for "JRE" or "java". On Debian-based systems + (including Ubuntu) you can try to install the OpenJDK 1.6 JRE + with:: + + $ sudo aptitude install openjdk-6-jre + +Extract the tarball to an appropriate location (like your home +directory or desktop). + +Make sure you have a Java runtime (JRE) installed; if you can run +:command:`java` from the shell, you should be fine. + +Next, run the script :file:`install-udev-rules.sh` in the extracted +IDE directory. It will ask for root permissions. You now need to +restart udev:: + + sudo /etc/init.d/udev restart + +This will grant members of the group ``plugdev`` read/write access to +Maple devices over USB. Make sure that you are in that group. (For +more information on why this is part of the install process, see the +:ref:`Unix toolchain quickstart `). + +To run the Maple IDE, run :command:`maple-ide` from the shell, or +double-click on it if your window system supports it. + +Feel free to put the IDE directory wherever you want. As long as you +leave its internal structure unchanged, things should be fine. + +.. _maple-ide-install-osx: + +OS X +^^^^ + +Double-click on the :file:`.dmg` file you downloaded to mount the disk +image. From the mounted image, drag and drop the Maple IDE icon into +your computer's Applications folder. + +To run the Maple IDE, double-click the :command:`Maple IDE` +application you dragged into your computer's :file:`Applications` +folder. -Stub. diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 8184772..9337611 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -11,130 +11,32 @@ USB cable `_, a functional computer, and possibly root (or "administrator") access to that computer. -If you have trouble along the way try the :ref:`install page -` for more detailed download and installation -instructions, and the :ref:`troubleshooting page ` -for help with some common problems. If all else fails, try our `forum -`_, or `contact us directly +If you have trouble along the way, try the :ref:`troubleshooting page +` for help with some common problems. If all else +fails, try our `forum`_, or `contact us directly `_! -The major steps are: +.. _forum: http://forums.leaflabs.com -* :ref:`Download and install the IDE ` +The steps are: -* :ref:`(Windows) Resolve driver issues ` +* :ref:`Install and run the IDE ` -* :ref:`Run the IDE `, then :ref:`compile - and upload a simple Blink program ` +* :ref:`Compile and upload a program ` -* Test the USB serial connection with a HelloWorld +* :ref:`Test the USB serial connection ` -.. _maple-quickstart-download: +.. _maple-quickstart-get-ide: -1. Download the IDE -------------------- - -Choose the correct version for your operating system: - -.. list-table:: - :widths: 15 30 50 - :header-rows: 1 - - * - Platform - - Status - - IDE Package - * - Windows - - Tested on 32bit Windows XP - - `maple-ide-LATEST-windowsxp32.zip `_ (about 75mb) - * - Linux - - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) - - `maple-ide-LATEST-linux32.tgz `_ (about 30mb) - - `maple-ide-LATEST-linux64.tgz `_ (about 30mb) - * - Mac OSX - - Tested on Snow Leopard 10.6 (64bit and 32bit) - - `maple-ide-LATEST-macosx-10_6.dmg `_ (about 40mb) - -.. note:: - - The Linux release requires that you have a Java runtime (JRE) - installed. If you're on Linux, don't have a JRE, and don't know how - to install one, see the :ref:`installation page - `. - -The package bundles together a compiler, an upload utility, a software -library, and a simple GUI text editor. All this software is `free and -open `_; we are grateful to the `Arduino -`_, `CodeSourcery -`_, `GNU `_, and -`OpenMoko `_ developers, as well as many others, -who allow us to reuse their software. - -2. Install the IDE ------------------- - -**Windows:** - -First, extract all the files in the ZIP file to a suitable location on -your system (like your Desktop folder). - -Next, you'll have to install drivers; see the :ref:`installation page -` for more details. Sorry! - -**Linux:** - -Extract the tarball to an appropriate location (like your -home directory or desktop). - -Make sure you have a Java runtime (JRE) installed; if you can run -:command:`java` from the shell, you should be fine. For instructions -on installing a JRE, try the :ref:`installation page -` or searching the package manager for your -distribution. - -Next, run the script :file:`install-udev-rules.sh` in the extracted -IDE directory. It will ask for root permissions. You now need to -restart udev:: - - sudo /etc/init.d/udev restart - -This will grant members of the group ``plugdev`` read/write access to -Maple devices over USB. Make sure that you are in that group. (For -more information on why this is part of the install process, see the -:ref:`Unix toolchain quickstart `). - -**OS X:** - -Double-click on the :file:`.dmg` file you downloaded in :ref:`Step 1 -`. - -Next, drag and drop the Maple IDE icon into your computer's -Applications folder. - -.. _maple-quickstart-run-ide: - -3. Run the IDE --------------- - -**Windows:** - -Double-click on the :command:`maple-ide` program from within the -extracted IDE directory. - -**Linux:** - -Run :file:`maple-ide` from the shell, or double click on it if your -window system supports it. - -**OS X:** +Install and run the IDE +----------------------- -Double-click the :command:`Maple IDE` application you dragged into -your computer's :file:`Applications` folder. +See the :ref:`IDE installation page ` for instructions. .. _maple-quickstart-compile-blinky: -4. Compile a program! ---------------------- +Compile a program! +------------------ Let's load up a simple example program that blinks the status LED. From the File menu, select Examples > Digital > Blink: @@ -172,42 +74,89 @@ bottom window, and then a confirmation message will appear: :align: center :alt: Code verified successfully. -5. Upload that program! ------------------------ +Upload that program! +-------------------- Now it's (finally!) time to plug in your Maple. Use a mini-b cable, -making sure that the power source jumper is on the USB header -first. +making sure that the power source jumper is on the USB header first. +We ship Maples with the power source jumper configured that way, so +you shouldn't have to do anything. For reference, it should look like +this: + +.. image:: /_static/img/plugged-in-maple.png + :align: center + :alt: Correctly plugged in Maple + +.. note:: + + On OS X, a network interface dialog will pop up every time you plug in + the Maple. + + .. image:: /_static/img/osx-unconfigured-popup.png + :align: center + :alt: Unconfigured modem popup + + If you click "Network Preferences..." and accept the default ("Not + Configured"), the dialog won't pop up and everything will work fine. + That is, from this window, click "Apply": + + .. image:: /_static/img/osx-network-prefs-unconfigured.png + :align: center + :scale: 75% + :alt: Click "Apply" The Maple should blink a short pattern on the blue status LED every time it is plugged in, reset, or reprogrammed, just to let you know -it's there. If it ever starts throbbing in a slow, smooth pattern that -means you've got a problem: see the troubleshooting page. - -On OS X, a modem setup dialog will pop up every time you plug in the -Maple. If you go to System Preferences Network Settings and accept -the default ("unconfigured") settings, the dialog won't pop up and -everything will work fine. +it's there. If it ever starts throbbing in a slow, smooth pattern, +then you've got a problem: see the :ref:`troubleshooting +` page for help. If all systems are go, select the Board type and Serial Port -(something like /dev/ttyACM0, /dev/cu.usbmodem5d21, or COM3 depending -on your platform) from the Tools menu. Then press the "upload" button -(right arrow to a bunch of dots) to upload your program to the -Maple. You should see some text and a progress bar flash by in the -status window of the IDE, then some blinky patterns on the Maple, and -then a constant blink with whatever time period you programmed in -above. +(something like :file:`COM3`, :file:`/dev/ttyACM0`, or +:file:`/dev/tty.usbmodemfa221`, depending on your platform, from the +Tools menu: + +Windows XP: + +.. image:: /_static/img/serial-port-win.png + :align: center + :alt: Board type and serial port for Windows XP + +Linux: + +.. image:: /_static/img/serial-port-ubuntu.png + :align: center + :alt: Board type and serial port for Linux + +OS X: + +.. image:: /_static/img/serial-port-mac.png + :align: center + :alt: Board type and serial port for the OS X + +Then press the "Upload" button to upload your program to the +Maple. + +.. image:: /_static/img/upload-button.png + :align: center + :alt: Click the "Upload" button + +You should see some text and a progress bar flash by in the status +window of the IDE, then some blinky patterns on the Maple, and then a +constant blinking on and off. Go ahead and modify the file a little bit: if you change the 'delay(1000);' numbers to a different value the speed of the blink will change. The value is a time in milliseconds to pause before continuing with the program, so by default the LED will be on for 1 -second, then off for 1 second, etc. +second, then off for 1 second, etc. Any time you make any changes, go +through the same Verify and Upload process to upload the new version +of your program to your Maple. .. warning:: - This step is the most common source of problems, especially on - Windows. + The uploading step is the most common source of problems, + especially on Windows. The situation is much improved over the past, but if you have trouble, try doing things again, unplugging your Maple and plugging @@ -215,42 +164,43 @@ second, then off for 1 second, etc. `, or restarting the IDE. - Please report any problems in the forums. If we don't know it's - broken, we can't fix it! + If nothing works, please report the problem in the `forum`_. + +.. _maple-quickstart-serial-port: -6. Use the serial port monitor! -------------------------------- +Use the serial port monitor! +---------------------------- As a last step to make sure everything has been configured correctly, let's upload a hello world program that will send text from the Maple -back to the IDE over the USB connection. From File select Examples, -Stubs, HelloWorld, and make sure the correct board and serial port -targets are selected from the Tools pull-down. And of course you could -change the text to be printed out; make sure you leave the double -quotes around it though or you'll get a compile error. +back to the IDE over the USB connection. From the File menu, select +Examples > Stubs > HelloWorld (similarly to when you selected the +Blink program), and make sure the correct board and serial port +targets are selected from the Tools pull-down. Open the serial monitor window (button on the far right) and make sure the 9600 baud speed is selected. Then go back to the code editing -window and upload your program (upload will recompile your code -automatically if there's been any change since the last "verify"). You +window and upload your program (Upload will recompile your code +automatically if there's been any change since the last Verify). You should get text spit at you over the serial monitor right after the program is uploaded. Shout back! We can hear you! -7. Go forth exuberantly! ------------------------- +Go forth exuberantly! +--------------------- We really hope you got this far and didn't frown or make a bitter -lemon face too often getting here. Where you go now is up to you: -perhaps you've got some crazy project cooking, or a longer tutorial to -work through, or maybe now is a good time for a trip to the kitchen -for a delicious sandwich. +lemon face getting here. Where you go now is up to you: perhaps you've +got some crazy project cooking, or a longer tutorial to work through, +or maybe now is a good time for a trip to the kitchen for a delicious +`sandwich `_. If you blew through this guide and are the kind of person who drinks -their coffee straight and has more than a 100 lines of vim or emacs -customization and doesn't even have a mouse plugged into your computer -you may want to look at the Unix Toolchain quickstart guide to getting -working with your old friends make, jtag, and gcc. - -Let us know what you come up with! Tag internet content with -#leaflabs, post in the forums, track us down in the real world, -whatever. We love projects! +their coffee straight, has more than a 100 lines of vim or emacs +customization, and doesn't even have a mouse plugged into their +computer, you may want to look at the :ref:`Unix Toolchain quickstart +` guide. It's the tutorial for getting working with +your old friends :command:`make`, :command:`jtag`, and :command:`gcc`. + +Let us know what you come up with! Tag us with #leaflabs on Twitter, +post in the `forum`_, track us down in the real world, whatever. We +love projects! diff --git a/source/pwm.rst b/source/pwm.rst new file mode 100644 index 0000000..c01e415 --- /dev/null +++ b/source/pwm.rst @@ -0,0 +1,7 @@ +.. _pwm: + +============================== + Pulse-Width Modulation (PWM) +============================== + +Stub. diff --git a/source/spi.rst b/source/spi.rst new file mode 100644 index 0000000..8518f3c --- /dev/null +++ b/source/spi.rst @@ -0,0 +1,7 @@ +.. _spi: + +===== + SPI +===== + +Stub. diff --git a/source/timers.rst b/source/timers.rst new file mode 100644 index 0000000..c156d4f --- /dev/null +++ b/source/timers.rst @@ -0,0 +1,7 @@ +.. _timers: + +======== + Timers +======== + +Stub. diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 0aba027..7fdfe17 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -1,9 +1,246 @@ +.. highlight:: sh + .. _troubleshooting: ======================= Maple Troubleshooting ======================= +* :ref:`Hardware Problems ` + + * The status LED is throbbing and I can't upload my program! + * My board is bricked! I can't upload via the bootloader no matter what! + * My 5v peripheral doesn't work! (I2C, SPI, USART, etc) + * The reset and D38/serial buttons don't seem to work reliably! + +* :ref:`IDE installation problems ` + + * I don't have root/administrator access! + * [Linux] I don't use udev! + +* :ref:`IDE usage problems ` + + * [Mac OSX] The "Board" and "Serial Port" menu items are missing! + +* :ref:`Common compiler problems ` + + * ``NullPointerException`` + * ``undefined reference to setup()/loop()`` + * ``error: 'Serial' was not declared in this scope`` + * ``File(s) not found`` + +* :ref:`Common upload problems ` + + * My program is too large! + * ``No DFU capable USB device found`` + * I have multiple Maples installed; how do I know which one will get flashed? + +* :ref:`Command-line issues ` + + * My flash programs don't seem to stick; they behave like they are RAM! + * [Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` + +* :ref:`Tips and tricks ` + + * Perpetual bootloader mode + +.. _troubleshooting-hardware: + +Hardware problems +----------------- + +The status LED is throbbing and I can't upload my program! + + The LED throbs when there has been a failed software + :ref:`assertion `. + + You can still reprogram by resetting the board and uploading + during the short window when the bootloader waits for a + program. + + To make this window longer (it can be hard to get the timing + right), use :ref:`perpetual bootloader mode + `. + +My board is bricked! I can't upload via the bootloader no matter what! + + Use the hardcoded serial STM32 serial bootloader to re-flash the + bootloader. + + .. TODO insert docs on reflashing the bootloader + + If it really is bricked, and you think it's our fault, + `contact us `_\ ! + +My 5v peripheral doesn't work! (I2C, SPI, USART, etc) + + Yup, the Maple is a 3.3v board. You may need to use a level + converter. See the :ref:`compatibility `, + :ref:`GPIO `, or other :ref:`hardware specific documentation + ` for more information. + +The reset and D38/serial buttons don't seem to work reliably! + + A few rev3 boards shipped in May-June 2010 may have had unreliable + buttons; see the :ref:`errata page ` for details. `We're + happy to replace these for you `_\ ! + +.. _troubleshooting-ide-install: + +Installation problems +--------------------- + + +I don't have root/administrator access! + + There are probably hacks or work-arounds to getting programs + uploaded without higher level system permissions. If you can + access USB character devices (ACM or ttyUSB style), you should be + able to communicate with the Maple and reprogram using an FTDI + converter and the serial bootloader, but we haven't tried. + + .. TODO: be more helpful + +[Linux] I don't use udev! + + There is probably a simple way to get autoconfiguration working + with devfs; in the meantime, you could try running the entire IDE + as root. + + .. TODO: be more helpful + +.. _troubleshooting-ide-usage: + +IDE problems +------------ + +[Mac OSX] The "Board" and "Serial Port" menu items are missing! + + Sometimes this happens if you try to compile or upload without + having a board selected. The work-around is to restart the + IDE. Mysterious! + +.. _troubleshooting-compilation: + +Common compiler problems +------------------------ + +``NullPointerException`` + + A classic! Make sure you have selected a board from the pulldown menu. + + .. TODO: remove when Python version is released + +``undefined reference to setup()/loop()`` + + Your sketch/program either does not include one of the :ref:`setup + ` or :ref:`loop ` functions, or it was not found + by the compiler. Your program must include both ``void setup()`` + and ``void loop()`` functions; they don't have to do anything, but + they **must** be there. + + You can start with an example program (to see one in the IDE, + click on File > Examples > Stubs > BareMinimum) to get the basic + structure. See also the :ref:`language ` documentation. + + This is a common error when your entire sketch is blank. + +``error: 'Serial' was not declared in this scope`` + + The classic Arduino has only one USART device and uses the unique + name "Serial" to control it. Larger devices like the Arduino Mega + and the Maple have multiple USARTS referred to as ``Serial1``, + ``Serial2``, etc. You probably want ``Serial2`` on the Maple; + that's the one connected to pins D0 and D1. See also the + :ref:`USART docs `. + +``File(s) not found`` + + There is an intermittent bug with the temporary directory build + system that on occasion will lose many of the ``#include``\ d + libmaple files. If you recompile everything, it should be fine. + + .. TODO remove when the Python version is released + +.. _troubleshooting-upload: + +Common upload problems +---------------------- + +My program is too large! + + First, make sure you're using the FLASH target instead of RAM; + there is several times more FLASH memory available for user + programs. + +``No DFU capable USB device found`` + + This probably means you don't have a Maple plugged in or powered on! + +I have multiple Maples installed; how do I know which one will get flashed? + + Because the Maple IDE uses DFU to upload programs, you can't + select a particular Maple from the Serial Port menu to upload to a + particular board. There's no solution to this problem for now: + you'll have to just plug in the Maples one at a time. If this is a + real problem let us know and we'll see if we can come up with a + better solution. + +.. _troubleshooting-shell: + +Command-line issues +------------------- + +My flash programs don't seem to stick; they behave like they are RAM! + + Make sure you :command:`make clean` when switching between FLASH + and RAM targets; :command:`make` isn't smart enough to rebuild + everything that needs to be for the new target. + +[Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` + + This is a nasty one! It means that all 32 possible CDC_ACM serial + devices (:file:`/dev/ttyACM25`, etc.) have been used up. + + The usual cause is using a serial port monitor and not closing it + before restarting the Maple or uploading a new program. The + operating system doesn't like that, and locks up that + device. After reset the Maple comes back up as a new device. If + you develop heavily and don't restart you'll blow right through + all 32 devices. + + The lazy solution is to always close the monitor before + restarting, and if you get this error in :file:`dmesg` after a + dfu-util "Not Found" error, restart you machine. + + The hacker solution is to restart your cdc_acm kernel module. On + Ubuntu 09.10, this goes a little something like:: + + $ sudo rmmod cdc-acm + $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko + +.. _troubleshooting-tips-tricks: + +Tips and Tricks +--------------- + .. _troubleshooting-perpetual-bootloader: -Stub. +**Perpetual Bootloader Mode** + +In this mode, Maple stays a DFU device and does not jump to user code +until the next reset. This is useful for guaranteeing that your Maple +will be available for reprogramming. + +To put your Maple into perpetual bootloader mode: + +1. Plug your Maple into the USB port. + +2. Hit the reset button on your Maple (it's the small button at the +bottom left, labeled RESET). Notice that it blinks quickly 6 times, +then blinks slowly a few more times. + +3. Hit reset again, and this time push and hold the other button +during the 6 fast blinks (the button is on the top right; it is +labeled BUT). You can release it once the slow blinks start. + diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 9939979..0328a5c 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -6,6 +6,10 @@ Unix Toolchain Quickstart =========================== +This is a tutorial for using the Maple with a standard Unix toolchain. +It's not necessary to do this in order to program the Maple; you can +always use our `IDE `_ instead. + You'll need a Maple board, a mini-b USB cable, a functional computer, and root access to that computer. This guide assumes you've had success with the IDE on your machine and that you are fairly @@ -240,9 +244,10 @@ live with :: $ cd ~/Downloads $ tar -xvzf gcc-blah-blah-macosx32.tar.gz $ mv arm ~/libmaple/arm + $ export PATH=$PATH:~/libmaple/arm/bin After that's done, you'll probably want to update your shell startup -script to stick :file:`~/libmaple/arm/bin` into your :envvar:`PATH`. +script so :file:`~/libmaple/arm/bin` stays in your :envvar:`PATH`. **So far, so good?** @@ -400,7 +405,8 @@ Debug with OpenOCD ------------------ TODO. For now see `this great guide -`_ from fun-tech.se. +`_ from fun-tech.se, and +the ``jtag`` Makefile target. .. _toolchain-codeblocks: diff --git a/source/usart.rst b/source/usart.rst new file mode 100644 index 0000000..30c953a --- /dev/null +++ b/source/usart.rst @@ -0,0 +1,7 @@ +.. _usart: + +======= + USART +======= + +Stub. diff --git a/source/usb.rst b/source/usb.rst new file mode 100644 index 0000000..2460df5 --- /dev/null +++ b/source/usb.rst @@ -0,0 +1,7 @@ +.. _usb: + +===== + USB +===== + +Stub. -- cgit v1.2.3 From 8de4fe4b0f3e28c99cac6dbf919dfa9b0009765f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 11 Oct 2010 12:32:31 -0400 Subject: docs --- source/bootloader.rst | 58 ++++++++++++++++++++++----------------------- source/conf.py | 8 ++++++- source/epilog.rst | 8 +++++++ source/index.rst | 2 +- source/language.rst | 4 +--- source/libmaple-api.rst | 5 +++- source/maple-quickstart.rst | 5 +--- source/troubleshooting.rst | 8 +++---- source/unix-toolchain.rst | 4 +--- 9 files changed, 56 insertions(+), 46 deletions(-) create mode 100644 source/epilog.rst diff --git a/source/bootloader.rst b/source/bootloader.rst index 17cd34b..9280c68 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -23,22 +23,22 @@ remake of the core library as well as the upload process. Some of these changes are aesthetic, refactoring and reorganization. Some are performance minded. The changes to the bootloader, however, were implemented to solve some really gritty cross platform issues. Before -delving in to how the Rev1 bootloader worked and how the Rev 3 +delving in to how the Rev 1 bootloader worked and how the Rev 3 bootloader works now, lets look at the features common to both of them and touch a bit on the Arduino setup. This is a fairly involved explanation, with a lot of details that are likely only interesting to a few. If you just want to get the rough idea, skim this article. If you want to start hacking on the bootloader, get in touch with us to get even more info on how this all works. Of course, you can always -checkout the code at github! +`check out the code at github `_! Arduino -^^^^^^^ +------- Arduino is based off of AVR series micro controllers, most of which lack USB support. Thus, boards like the Duemilanove add USB capability via an FTDI USB to Serial converter chip. This chip interfaces with -the AVR over…serial. When you plug an Arduino into a computer only an +the AVR over…serial. When you plug an Arduino into a computer, only an FTDI driver is needed. Since the FTDI chip is separate from the AVR, you can reset the Arduino without closing this USB connection with the FTDI chip. To program an Arduino, the host machine sends a command @@ -50,8 +50,8 @@ and off you go. The whole process is quick, the bootloader doesn’t live for very long, and will exit almost immediately if no upload commands are received. -Maple Rev1: The Horror... -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Maple Rev 1: The Horror... +--------------------------- Maple is based off the STM32 (ARM cortex M3) series chips, which do have embedded USB support. Thus, Maple doesn’t need the extra FTDI @@ -71,7 +71,7 @@ serial port transactions. There was no reset necessary for uploads. No waiting. The bootloader was always running the background, ready to receive commands. -The problem was that ONLY Linux did this. Windows refused to attach +The problem was that *only* Linux did this. Windows refused to attach more than one driver to a single USB device without repackaging the DFU and CDC ACM into a single IAD Compound Device. It's not terribly important what this means, except for two things. @@ -86,35 +86,35 @@ were going to have to write some custom drivers across several platforms to make everything work this way. Maple Rev3 -^^^^^^^^^^ +---------- Maple Rev 3 takes a completely different tack, more along the lines of Arduino. In Rev 3, the device resets into bootloader mode, which -stays alive for a few moments to receive commands and then jumps to -user code. The bootloader is implemented as a DFU device – just a DFU -device, no serial port. This requires one driver for windows -(:file:`drivers/mapleDrv/dfu`). As part of the :ref:`libmaple` -library, user code is automatically supplied with serial support via -some behind the scenes work that happens automatically when you -compile (``setupUSB()`` is appended to ``setup()``). This user mode -code only implements a CDC ACM class USB device, giving you functions -like ``Usb.print()``. Separating these two modes fixed the driver -issue, there are no complicated compound usb device nonsense, and the -scheme works well across platforms, requiring only two drivers (serial -and DFU) on Windows. +stays alive for a few moments to receive commands, and then jumps to +user code. The bootloader is implemented as a DFU device -- just a DFU +device, no serial port. This requires one driver for Windows +(:file:`drivers/mapleDrv/dfu` in the Windows IDE directory). As part +of the :ref:`libmaple ` library, user code is automatically +supplied with serial support via some behind the scenes work that +happens automatically when you compile (``setupUSB()`` is appended to +``setup()``). This user mode code only implements a CDC ACM class USB +device, giving you functions like ``Usb.print()``. Separating these +two modes fixed the driver issue, required no complicated compound USB +device nonsense, and works well across platforms, requiring only two +drivers (serial and DFU) on Windows. However, it is no longer possible to upload code at will, since there is no bootloader quietly listening in the background. Instead you have to reset the board, then initiate a DFU transaction. This reset is performed automatically by the IDE by sending a command over the USB -serial port. You can generate this reset on your own using a python +serial port. You can generate this reset on your own using a Python script or some other scheme. All you need do is: -1. Pulse DTR (high and then low, so that youve created a negative +1. Pulse DTR (high and then low, so that you've created a negative edge) -2. Write “1EAF” in ASCII over the serial pipe. This will cause Maple +2. Write "1EAF" in ASCII over the serial pipe. This will cause Maple to reset. Only the first 4 bytes after a negative edge of DTR are - checked for this command, so its important you actually create a + checked for this command, so it's important you actually create a negative edge, rather than just ensuring DTR is low. After the reset, the host OS takes a few moments (.5-2 seconds) to @@ -122,8 +122,8 @@ re-enumerate the device as DFU. This delay is unpredictable, and its the reason the bootloader on Maple Rev3 stays alive for so long. Sometimes the bootloader was exiting before the OS had even enumerated the device! Once in bootloader mode, however, -:command:`dfu-util` uploads your sketch into either flash or ram (dfu -alternate setting 0 or 1 respectively) and resets the board again. -This time, however, no DFU transaction is initiated and the bootloader -gives way to user code, closing down the DFU pipe and bringing up the -USB serial. +:command:`dfu-util` uploads your sketch into either flash or RAM (DFU +alternate setting 0 or 1, respectively) and resets the board again. +This time, however, no DFU transaction is initiated, and the +bootloader gives way to user code, closing down the DFU pipe and +bringing up the USB serial. diff --git a/source/conf.py b/source/conf.py index 7f2b3b4..5fcb939 100644 --- a/source/conf.py +++ b/source/conf.py @@ -68,7 +68,11 @@ release = '0.0.7' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ['epilog.rst'] + +# Included at the end of every source file that is read. +with open('epilog.rst', 'r') as ep: + rst_epilog = ep.read() # The reST default role (used for this markup: `text`) to use for all # documents. @@ -91,6 +95,8 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] +# Warn about all references where the target cannot be found. +#nitpicky = True # -- Options for HTML output -------------------------------------------------- diff --git a/source/epilog.rst b/source/epilog.rst new file mode 100644 index 0000000..0e430c8 --- /dev/null +++ b/source/epilog.rst @@ -0,0 +1,8 @@ +.. This file automatically gets included at the end of every file, so +.. it's useful for common references, etc. + +.. Common URL references +.. _forum: http://forums.leaflabs.com +.. _contact: http://leaflabs.com/contact/ +.. _setup(): http://arduino.cc/en/Reference/Setup +.. _loop(): http://arduino.cc/en/Reference/Loop diff --git a/source/index.rst b/source/index.rst index cdf151d..e5af08f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -28,9 +28,9 @@ Table of contents: Maple Language Reference Maple Library Reference libmaple Documentation and APIs - Maple bootloader Troubleshooting Hardware-Specific Documentation + Maple bootloader Known Problems Indices and tables diff --git a/source/language.rst b/source/language.rst index 7bf71c6..8115d6b 100644 --- a/source/language.rst +++ b/source/language.rst @@ -210,9 +210,7 @@ Arduino Documentation Links typedef uint16 word; - -.. _setup(): http://arduino.cc/en/Reference/Setup -.. _loop(): http://arduino.cc/en/Reference/Loop +.. setup()/loop() are part of the standard rst_epilog in conf.py .. _if: http://arduino.cc/en/Reference/If .. _if...else: http://arduino.cc/en/Reference/Else .. _for: http://arduino.cc/en/Reference/For diff --git a/source/libmaple-api.rst b/source/libmaple-api.rst index df9a4d9..af283cb 100644 --- a/source/libmaple-api.rst +++ b/source/libmaple-api.rst @@ -4,4 +4,7 @@ libmaple API reference ======================== -Stub. +This page documents the lower-level features of libmaple, which may be +of use to programmers who don't wish to use the Arduino-style +environment provided by the `Maple IDE `_. + diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 9337611..20d84a0 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -13,10 +13,7 @@ that computer. If you have trouble along the way, try the :ref:`troubleshooting page ` for help with some common problems. If all else -fails, try our `forum`_, or `contact us directly -`_! - -.. _forum: http://forums.leaflabs.com +fails, try our `forum`_, or `contact us directly `_! The steps are: diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 7fdfe17..b878ae4 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -133,10 +133,10 @@ Common compiler problems ``undefined reference to setup()/loop()`` - Your sketch/program either does not include one of the :ref:`setup - ` or :ref:`loop ` functions, or it was not found - by the compiler. Your program must include both ``void setup()`` - and ``void loop()`` functions; they don't have to do anything, but + Your sketch/program either does not include one of the `setup + `_ or `loop `_ functions, or it was not found by + the compiler. Your program must include both ``void setup()`` and + ``void loop()`` functions; they don't have to do anything, but they **must** be there. You can start with an example program (to see one in the IDE, diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 0328a5c..295090e 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -19,9 +19,7 @@ editing your shell startup script (.bashrc, .tcshrc, etc.) and using generic installation/setup issues, the `IDE install `_ and :ref:`troubleshooting` pages may be helpful. If all else fails, try -our `forum`_, or `contact us directly `_! - -.. _forum: http://forums.leaflabs.com +our `forum`_, or `contact us directly `_! We currently have instructions for 32- and 64-bit Linux and OS X Snow Leopard. If you're on another Unix platform, Windows, or an earlier -- cgit v1.2.3 From 56078b6b44f3a3e724f3ec2e3173075ab9043310 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 11 Oct 2010 20:02:04 -0400 Subject: more docs --- Doxyfile | 1634 ++++++++++++++++++++++++++++++++++++++++++ README | 41 +- source/adc.rst | 70 +- source/bootloader.rst | 3 + source/compatibility.rst | 129 ++++ source/conf.py | 22 +- source/epilog.rst | 51 ++ source/errata.rst | 11 + source/gpio.rst | 89 ++- source/i2c.rst | 2 - source/language.rst | 53 +- source/libmaple-api.rst | 1 + source/libmaple.rst | 2 + source/libraries.rst | 4 +- source/maple-ide-install.rst | 3 +- source/maple-quickstart.rst | 9 +- source/prolog.rst | 7 + source/troubleshooting.rst | 275 ++++--- 18 files changed, 2183 insertions(+), 223 deletions(-) create mode 100644 Doxyfile create mode 100644 source/prolog.rst diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..73f18f9 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,1634 @@ +# Doxyfile 1.7.1 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = libmaple + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = custom-build + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = ./docs/doxygen + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = "sideeffect=\par Side Effects:\n" + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this +# tag. The format is ext=language, where ext is a file extension, and language +# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, +# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make +# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C +# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions +# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen to replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the +# methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = YES + +# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to +# determine which symbols to keep in memory and which to flush to disk. +# When the cache is full, less often used symbols will be written to disk. +# For small to medium size projects (<1000 input files) the default value is +# probably good enough. For larger projects a too small cache size can cause +# doxygen to be busy swapping symbols to and from disk most of the time +# causing a significant performance penality. +# If the system has enough physical memory increasing the cache will improve the +# performance by keeping more symbols in memory. Note that the value works on +# a logarithmic scale so increasing the size by one will rougly double the +# memory usage. The cache size is given by this formula: +# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols + +SYMBOL_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespace are hidden. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = NO + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen +# will sort the (brief and detailed) documentation of class members so that +# constructors and destructors are listed first. If set to NO (the default) +# the constructors will appear in the respective orders defined by +# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. +# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO +# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = YES + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = NO + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = NO + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command , where is the value of +# the FILE_VERSION_FILTER tag, and is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. The create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. +# You can optionally specify a file name after the option, if omitted +# DoxygenLayout.xml will be used as the name of the layout file. + +LAYOUT_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = YES + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = libmaple/ \ + wirish/ + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 + +FILE_PATTERNS = *.c \ + *.cpp \ + *.h + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = * + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command , where +# is the value of the INPUT_FILTER tag, and is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. Otherwise they will link to the documentation. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = YES + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. +# Doxygen will adjust the colors in the stylesheet and background images +# according to this color. Hue is specified as an angle on a colorwheel, +# see http://en.wikipedia.org/wiki/Hue for more information. +# For instance the value 0 represents red, 60 is yellow, 120 is green, +# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. +# The allowed range is 0 to 359. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of +# the colors in the HTML output. For a value of 0 the output will use +# grayscales only. A value of 255 will produce the most vivid colors. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to +# the luminance component of the colors in the HTML output. Values below +# 100 gradually make the output lighter, whereas values above 100 make +# the output darker. The value divided by 100 is the actual gamma applied, +# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, +# and 100 does not change the gamma. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = YES + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). + +HTML_DYNAMIC_SECTIONS = NO + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated +# that can be used as input for Qt's qhelpgenerator to generate a +# Qt Compressed Help (.qch) of the generated HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to +# add. For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see +# +# Qt Help Project / Custom Filters. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's +# filter section matches. +# +# Qt Help Project / Filter Attributes. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before +# the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. + +GENERATE_TREEVIEW = NO + +# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, +# and Class Hierarchy pages using a tree view instead of an ordered list. + +USE_INLINE_TREES = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open +# links to external symbols imported via tag files in a separate window. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are +# not supported properly for IE 6.0, but are supported on all modern browsers. +# Note that when changing this option you need to delete any form_*.png files +# in the HTML output before the changes have effect. + +FORMULA_TRANSPARENT = YES + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box +# for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using +# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets +# (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = YES + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a PHP enabled web server instead of at the web client +# using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server +# based approach is that it scales better to large projects and allows +# full text search. The disadvances is that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +# If LATEX_SOURCE_CODE is set to YES then doxygen will include +# source code with syntax highlighting in the LaTeX output. +# Note that which sources are shown also depends on other settings +# such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = YES + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. This is useful +# if you want to understand what is going on. On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = YES + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is +# allowed to run in parallel. When set to 0 (the default) doxygen will +# base this on the number of processors available in the system. You can set it +# explicitly to a value larger than 0 to get control over the balance +# between CPU load and processing speed. + +DOT_NUM_THREADS = 0 + +# By default doxygen will write a font called FreeSans.ttf to the output +# directory and reference it in all dot files that doxygen generates. This +# font does not include all possible unicode characters however, so when you need +# these (or just want a differently looking font) you can specify the font name +# using DOT_FONTNAME. You need need to make sure dot is able to find the font, +# which can be done by putting it in a standard location or by setting the +# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory +# containing the font. + +DOT_FONTNAME = FreeSans.ttf + +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the output directory to look for the +# FreeSans.ttf font (which doxygen will put there itself). If you specify a +# different font using DOT_FONTNAME you can set the path where dot +# can find it using this tag. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES diff --git a/README b/README index 8556dd2..174f55a 100644 --- a/README +++ b/README @@ -1,22 +1,36 @@ -This directory contains the Sphinx documentation for libmaple. You -can generate HTML documentation using the Makefile if you have make, -or using make.bat from Windows. +This directory contains the Sphinx documentation for libmaple, as well +as a Doxygen configuration file; we turn Doxygen XML output into +Sphinx documentation. You can generate HTML documentation using the +Makefile if you have make, or using make.bat from Windows. -For the impatient, you can build the HTML docs with (on Unix): +You need a recent-ish version of doxygen in your PATH: + + http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc + +For the Doxygen-to-Sphinx bridge, we rely on a project called Breathe, +by Michael Jones. You must clone the breathe repository and set an +environment variable BREATHE_HOME to be able to build the +documentation. Something like this on bash: + + $ git clone http://github.com/michaeljones/breathe.git + $ export BREATHE_HOME /path/to/breathe/repo/ + +You can now build the HTML docs with (on Unix): $ sudo easy_install -U Sphinx $ make html -Which will produce HTML documentation in build/html. +Which will produce Doxygen documentation in doxygen/xml, and HTML +documentation (this is what you want to look at) in build/html. All of the documentation itself lives in source/. The directory source/_static is for static content like style sheets; -source/_templates contains Sphinx templates. +source/_templates contains Sphinx templates (or, it would if we had +any). -The documentation is written in reStructuredText (reST); it's a Python -thing that they use to produce the docs at python.org (which are -beautiful, if you've never seen them). You can read more about Sphinx -here: +The docs are written in reStructuredText (reST); it's a Python thing +that they use to produce the docs at python.org (which are beautiful, +if you've never seen them). You can read more about Sphinx here: http://sphinx.pocoo.org/tutorial.html @@ -24,5 +38,8 @@ Specific information on documenting C and C++ is available here: http://sphinx.pocoo.org/domains.html -The file source/conf.py is an autogenerated configuration file; you -can read it yourself. +You can view the reST source for any generated page of documentation +by clicking the "Show Source" link in the sidebar. + +The file source/conf.py is the Sphinx configuration file; you can go +read it for more information about our setup. diff --git a/source/adc.rst b/source/adc.rst index 17c672d..4e118aa 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -4,4 +4,72 @@ ADC ===== -Stub. +Analog-Digital Conversion is the process of reading a physical voltage +as a number. The Maple has a large number of pins which are capable of +taking 12-bit ADC measurements, which means that voltages from ground +to +3.3v are read as numbers from 0 to 4095; this corresponds to a +theoretical sensitivity of just under 1 millivolt. In reality, a +number of factors introduce noise and bias into this reading and a +number of techniques must be used to get good precision and accuracy. + +.. compound:: + + The header pins with ADC functionality (marked as "AIN" on the + silkscreen) are: + + D0, D1, D2, D3, D10, D11, D12, D13, D15, D16, D17, D18, D19, D20, D27, D28 + +.. contents:: Contents + :local: + +.. _adc-noise-bias: + +Noise and Bias +-------------- + +The biggest issues with analog-digital conversion are noise and bias. +With the Maple, we have tried to isolate the ADC pins and traces from +strong noise sources but there are always trade--offs between noise, +additional functionality, cost, and package size. + +The 6 ADC pins in a bank (D15--D20) generally have the least +noise and should be used for fine measurements. If the input voltage +changes relatively slowly, a number of samples can be taken in +succession and averaged together, or the same voltage can even be +sampled by multiple ADC pins at the same time. + +An important factor when taking a voltage reading is the reference +voltages that the sample is being compared against. In the case of the +Maple, the high reference is |vcc| and the low reference is ground. +This means that noise or fluctuations on either |vcc| or ground will +affect the measurement. It also means that the voltage you are trying +to sample must be between ground and 3.3V. In the case of a variable +reading, it is best if the voltage varies over the entire range of +0--3.3V; otherwise, only a fraction of the sensitivity is being +leveraged. Resistor dividers and constant voltage diodes are basic +tools which can help bring a given voltage signal into the appropriate +range; opamps and other powered components can also be used. + +.. _adc-function-reference: + +Function Reference +------------------ + +.. TODO function reference (figure out Doxygen first) + +.. _adc-recommended-reading: + +Recommended Reading +------------------- + +* `Wikipedia article on Analog-to-digital converter `_ +* `Arduino Analog Input Tutorial `_ +* STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet (pdf) `_ + * `Reference Manual (pdf) `_ + * `Application Note on ADC Modes (pdf) `_ + * `Application Note on ADC Oversampling (pdf) `_ + + diff --git a/source/bootloader.rst b/source/bootloader.rst index 9280c68..c4c5da2 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -15,6 +15,9 @@ Flash memory and only runs when the chip is reset). **Visit the github development project**: http://github.com/leaflabs/maple-bootloader +.. contents:: Contents + :local: + Bootloader Schemes Explained! ----------------------------- diff --git a/source/compatibility.rst b/source/compatibility.rst index aeed36b..6166ec5 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -1,7 +1,136 @@ +.. highlight:: cpp + .. _compatibility: ============================= Maple-Arduino Compatibility ============================= +.. contents:: Contents + :local: + +Overview +-------- + +The biggest difference between the Maple and most Arduino boards is +that the Maple uses a 32-bit ARM Cortex-M3 architecture chip while the +Arduinos have 8-bit Atmel AVR chips. The different instruction set +means that machine code (executable binary programs) is incompatible +between the two, and a different compiler (actually just a different +version of `gcc `_) is required. The compiler for +the regular Arduino IDE is the popular :command:`avr-gcc` package; the +compiler for the Maple version of the IDE is CodeSourcery's edition of +gcc for the ARM EABI target (:command:`arm-non-eabi-gcc`). + +The bitwidth of the processor means that the Maple can process 32-bit +operations (like adding two 32-bit integers) in a single instruction, +while an Arduino processor would have to split up large operations +into several smaller ones. In a lot of cases 8-bit operations are +plenty (integers 0-255, single characters of text, etc.), but if +you're dealing with higher resolution data, the speed up could be +significant. A trade-off is that code could be larger as well; program +instructions and memory locations can be up to 32-bits each, which in +the worst case would quadruple program size. In reality, the removal +of extra instructions and fancy packing together of simple +instructions means that programs aren't much larger (or are even +smaller). + +Header Numbering and Incompatibilities +-------------------------------------- + +The numbering of headers is different; on the Maple each GPIO has a +unique number: D0, D1, D2, all the way up to D37 (actually, there are +:ref:`a few more `...). On the Arduino, the analog pins are +numbered separately (A0-A5) from the digital pins (D0\ -D13). + +The incompatible hardware differences are: + +* |i2c| port: on most Arduinos, the |i2c| port is Analog Input + 4 (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5 + (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 (SDA). + + It should be possible to skywire, sacrificing signal quality (due to + increased capacitance). Alternatively, |i2c| can be bit-banged + reasonably well in software. This peripheral could potentially be + rerouted internally, but we haven't looked into it. + +* :ref:`PWM ` on D10: all the other standard Arduino PWM headers have PWM + functionality on the Maple (D2,D3,D6,D9,D11), but not D10. We did + our best! It may be possible to reroute this peripheral internally + using low level configuration, but we haven't looked in to it. + +* No External Voltage Reference: The Arduino has an Aref pin which + allows the use of an external ADC voltage reference; the Maple has + an extra GPIO pin (14) with PWM capability in this spot, and does + not allow an external voltage reference to be configured. + +* EEPROM: the Maple does not have any internal EEPROM. This + functionality can be emulated with regular persistent flash memory, + or with an external EEPROM chip. + +* ISP Programming: the Maple does not use an ISP/ICSP bus for + debugging; it uses :ref:`JTAG `. + + +Software Language/Library Changes +--------------------------------- + +With :ref:`one notable exception `, the entire +Arduino language is supported. However, there are some subtle +differences, most of which are improvements: + +* 32-bit integers: many standard functions either expect or return + full 32-bit (4 byte) integer values instead of the regular 16-bit (2 + byte) Arduino values. + +* `pinMode()`_ types: any :ref:`GPIO ` (including analog pins) + can be configured into one of the following modes with a single call + to `pinMode()`_: ``OUTPUT``, ``OUTPUT_OPEN_DRAIN``, + ``INPUT_FLOATING``, ``INPUT_PULLUP``, + ``INPUT_PULLDOWN``. Additionally, the PWM and Analog Input pins can + be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the + :ref:`GPIO documentation ` for more information. + + .. TODO: reference libmaple docs above when they're done + +* Serial1 syntax: like the `Arduino Mega + `_, the Maple has + multiple USART ports. By default, Serial is not mapped to any of + them, use ``Serial1`` through ``Serial3`` instead. + + .. TODO: reference libmaple docs for Serial[n] above when they're done + +* 16-bit :ref:`PWM `: Arduino boards support 8-bit PWM, which + means that calls to `analogWrite()`_ take values between 0 (always + off) and 255 (always on). The Maple supports 16-bit PWM, so the + corresponding values should be between 0 (always off) and 65535 + (always on). + +* 12-bit :ref:`ADC `: Arduino boards support 10-bit ADC, which + means that calls to `analogRead()`_ will return values between 0 and + 1023. The Maple supports 12-bit ADC, so the same call will instead + return values between 0 and 4095. + + +.. class:: ported-feature + +I am supported! + +This should be ordinary + +.. class:: non-ported-feature + +I can't do it :( + +Also ordinary + +.. class:: partly-ported-feature + +I sorta work + +And I am also ordinary + Stub. + +(not finished) + diff --git a/source/conf.py b/source/conf.py index 5fcb939..26147fd 100644 --- a/source/conf.py +++ b/source/conf.py @@ -17,7 +17,11 @@ import sys, os # 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('.')) +# +# We rely on Michael Jones's breathe as a Doxygen-to-Sphinx bridge. +# See libmaple/docs/README for information on obtaining it and letting +# Sphinx know where it is. +sys.path.append(os.environ['BREATHE_HOME']) # -- General configuration ---------------------------------------------------- @@ -29,7 +33,7 @@ import sys, os # ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', - 'sphinx.ext.coverage'] + 'sphinx.ext.coverage', 'breathe'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -68,12 +72,16 @@ release = '0.0.7' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['epilog.rst'] +exclude_patterns = ['epilog.rst', 'prolog.rst'] # Included at the end of every source file that is read. with open('epilog.rst', 'r') as ep: rst_epilog = ep.read() +# Included at the beginning of every source file that is read. +with open('prolog.rst', 'r') as pr: + rst_prolog = pr.read() + # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None @@ -229,3 +237,11 @@ man_pages = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} + + +# -- Options for breathe integration ------------------------------------------ + +breathe_projects = {'libmaple' : os.path.join(os.environ['LIB_MAPLE_HOME'], + 'docs', 'doxygen', 'xml')} + +breathe_default_project = 'libmaple' diff --git a/source/epilog.rst b/source/epilog.rst index 0e430c8..7805362 100644 --- a/source/epilog.rst +++ b/source/epilog.rst @@ -4,5 +4,56 @@ .. Common URL references .. _forum: http://forums.leaflabs.com .. _contact: http://leaflabs.com/contact/ + + +.. Arduino built-in functions .. _setup(): http://arduino.cc/en/Reference/Setup .. _loop(): http://arduino.cc/en/Reference/Loop + +.. _pinMode(): http://arduino.cc/en/Reference/PinMode +.. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite +.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead + +.. _analogReference(): http://arduino.cc/en/Reference/AnalogReference +.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead +.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite + +.. _tone(): http://arduino.cc/en/Reference/Tone +.. _noTone(): http://arduino.cc/en/Reference/NoTone +.. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut +.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn + +.. _millis(): http://arduino.cc/en/Reference/Millis +.. _micros(): http://arduino.cc/en/Reference/Micros +.. _delay(): http://arduino.cc/en/Reference/Delay +.. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds + +.. _min(): http://arduino.cc/en/Reference/Min +.. _max(): http://arduino.cc/en/Reference/Max +.. _abs(): http://arduino.cc/en/Reference/Abs +.. _constrain(): http://arduino.cc/en/Reference/Constrain + +.. _map(): http://arduino.cc/en/Reference/Map +.. _pow(): http://arduino.cc/en/Reference/Pow +.. _sqrt(): http://arduino.cc/en/Reference/Sqrt + +.. _sin(): http://arduino.cc/en/Reference/Sin +.. _cos(): http://arduino.cc/en/Reference/Cos +.. _tan(): http://arduino.cc/en/Reference/Tan + +.. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed +.. _random(): http://arduino.cc/en/Reference/Random + +.. _lowByte(): http://arduino.cc/en/Reference/LowByte +.. _highByte(): http://arduino.cc/en/Reference/HighByte +.. _bitRead(): http://arduino.cc/en/Reference/BitRead +.. _bitWrite(): http://arduino.cc/en/Reference/BitWrite +.. _bitSet(): http://arduino.cc/en/Reference/BitSet +.. _bitClear(): http://arduino.cc/en/Reference/BitClear +.. _bit(): http://arduino.cc/en/Reference/Bit + +.. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt +.. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt + +.. _interrupts(): http://arduino.cc/en/Reference/Interrupts +.. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts diff --git a/source/errata.rst b/source/errata.rst index b702bd1..09b2ad1 100644 --- a/source/errata.rst +++ b/source/errata.rst @@ -4,4 +4,15 @@ Errata ======== +This page is a collection of known issues and warnings for each +revision of the Maple board. The failure modes aren't design errors, +but are easy ways to break or damage your board permanently. For a +list of differences between the Maple and Arduinos, see the page on +:ref:`compatibility `. + +.. contents:: Contents + :local: + Stub. + +(not finished) diff --git a/source/gpio.rst b/source/gpio.rst index f608a61..2567221 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -4,4 +4,91 @@ GPIO ====== -Stub. +The Maple features 38 ready-to-use general purpose input/output (GPIO) +pins for digital input/output, numbered D0 through D37. These numbers +correspond to the numeric values next to each header on the Maple +silkscreen. + +Many of these pins may additionally be used for special features or +peripheral functions. This page documents those capabilities, by pin. + +The current and voltage limitations have not been copied over from the +STM32 datasheet (see the :ref:`Recommended Reading +` for a link). In particular, a number of +GPIO pins are 5v tolerant (which means that applying 5v to a pin and +reading it as input or allowing it to drain to ground will not damage +that pin), while some are not. + +.. contents:: Contents + :local: + +Pin Mapping Mega Table +---------------------- + +This huge reference table shows the available functionality on every +GPIO pin, by peripheral type. The "STM32" column refers to the port +and number that the header is connected to on the microcontroller. +The "5v?" column documents whether or not the pin is 5v tolerant (see +above). + +.. csv-table:: + :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" + + "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" + "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" + "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" + "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" + "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" + "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" + "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" + "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" + "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" + "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" + "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" + "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" + "D12", "PA6", "ADC6", "TIM3_CH1", - - SPI1_MISO No + D13 PA5 ADC5 - - - SPI1_SCK No + D14 PB8 - TIM4_CH3 - - - Yes + + Analog header + + D15 PC0 ADC10 - - - - No + D16 PC1 ADC11 - - - - No + D17 PC2 ADC12 - - - - No + D18 PC3 ADC13 - - - - No + D19 PC4 ADC14 - - - - No + D20 PC5 ADC15 - - - - No + + External header + + D21 PC13 - - - - - No + D22 PC14 - - - - - No + D23 PC15 - - - - - No + D24 PB9 - TIM4_CH4 - - - Yes + D25 PD2 - TIM3_ETR - - - Yes + D26 PC10 - - - - - Yes + D27 PB0 ADC8 TIM3_CH3 - - - No + D28 PB1 ADC9 TIM3_CH4 - - - No + D29 PB10 - - I2C2_SCL USART3_TX - Yes + D30 PB11 - - I2C2_SDA USART3_RX - Yes + D31 PB12 - TIM1_BKIN I2C2_SMBAL USART3_CK SPI2_NSS Yes + D32 PB13 - TIM1_CH1N - USART3_CTS SPI2_SCK Yes + D33 PB14 - TIM1_CH2N - USART3_RTS SPI2_MISO Yes + D34 PB15 - TIM1_CH3N - - SPI2_MOSI Yes + D35 PC6 - - - - - Yes + D36 PC7 - - - - - Yes + D37 PC8 - - - - - + + +Stub (unfinished). + +.. _gpio-recommended-reading: + +Recommended Reading +------------------- + +STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet (pdf) `_ + * `Reference Manual (pdf) `_ diff --git a/source/i2c.rst b/source/i2c.rst index e0444eb..34bd57c 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -4,6 +4,4 @@ |i2c| ===== -.. |i2c| replace:: I\ :sup:`2`\ C - Stub. diff --git a/source/language.rst b/source/language.rst index 8115d6b..6eb5bc7 100644 --- a/source/language.rst +++ b/source/language.rst @@ -24,6 +24,9 @@ C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the :ref:`arduino_c_for_c_hackers`. +.. contents:: Contents + :local: + Unique Maple Additions ---------------------- @@ -308,59 +311,15 @@ Arduino Documentation Links .. _const: http://arduino.cc/en/Reference/Const .. _sizeof(): http://arduino.cc/en/Reference/Sizeof -.. _pinMode(): http://arduino.cc/en/Reference/PinMode -.. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite -.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead - -.. _analogReference(): http://arduino.cc/en/Reference/AnalogReference -.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead -.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite - -.. _tone(): http://arduino.cc/en/Reference/Tone -.. _noTone(): http://arduino.cc/en/Reference/NoTone -.. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut -.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn - -.. _millis(): http://arduino.cc/en/Reference/Millis -.. _micros(): http://arduino.cc/en/Reference/Micros -.. _delay(): http://arduino.cc/en/Reference/Delay -.. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds - -.. _min(): http://arduino.cc/en/Reference/Min -.. _max(): http://arduino.cc/en/Reference/Max -.. _abs(): http://arduino.cc/en/Reference/Abs -.. _constrain(): http://arduino.cc/en/Reference/Constrain - -.. _map(): http://arduino.cc/en/Reference/Map -.. _pow(): http://arduino.cc/en/Reference/Pow -.. _sqrt(): http://arduino.cc/en/Reference/Sqrt - -.. _sin(): http://arduino.cc/en/Reference/Sin -.. _cos(): http://arduino.cc/en/Reference/Cos -.. _tan(): http://arduino.cc/en/Reference/Tan - -.. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed -.. _random(): http://arduino.cc/en/Reference/Random - -.. _lowByte(): http://arduino.cc/en/Reference/LowByte -.. _highByte(): http://arduino.cc/en/Reference/HighByte -.. _bitRead(): http://arduino.cc/en/Reference/BitRead -.. _bitWrite(): http://arduino.cc/en/Reference/BitWrite -.. _bitSet(): http://arduino.cc/en/Reference/BitSet -.. _bitClear(): http://arduino.cc/en/Reference/BitClear -.. _bit(): http://arduino.cc/en/Reference/Bit - +.. Links for the standard Arduino built-in functions are included as +.. part of the standard epilog. .. _our reference page: http://leaflabs.com/docs/external-interrupts/ -.. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt -.. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt - -.. _interrupts(): http://arduino.cc/en/Reference/Interrupts -.. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts .. _Serial: http://arduino.cc/en/Reference/Serial .. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary .. _newlib: http://sourceware.org/newlib/ + .. _arduino_c_for_c_hackers: Note for C/C++ Programmers diff --git a/source/libmaple-api.rst b/source/libmaple-api.rst index af283cb..d5b90b6 100644 --- a/source/libmaple-api.rst +++ b/source/libmaple-api.rst @@ -8,3 +8,4 @@ This page documents the lower-level features of libmaple, which may be of use to programmers who don't wish to use the Arduino-style environment provided by the `Maple IDE `_. +Stub. diff --git a/source/libmaple.rst b/source/libmaple.rst index 620fdfa..a018cd7 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -30,6 +30,8 @@ wrappers and code to imitate the Arduino programming library. git clone git://github.com/leaflabs/libmaple.git +**Table of contents:** + .. toctree:: :maxdepth: 2 diff --git a/source/libraries.rst b/source/libraries.rst index c2d5cb0..6a97b0e 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -15,8 +15,8 @@ library you want. Any incompatibilities between the Maple and Arduino versions are noted in the description of the library. -* :ref:`LiquidCrystal ` -* :ref:`Wire ` +.. contents:: Contents + :local: .. _liquid_crystal: diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 46c903b..3c3fffe 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -11,7 +11,8 @@ check the :ref:`troubleshooting page ` for help with some common problems. If all else fails, try our `forum`_, or `contact us directly `_! -.. _forum: http://forums.leaflabs.com +.. contents:: Contents + :local: Download -------- diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 20d84a0..4d646d7 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -15,13 +15,8 @@ If you have trouble along the way, try the :ref:`troubleshooting page ` for help with some common problems. If all else fails, try our `forum`_, or `contact us directly `_! -The steps are: - -* :ref:`Install and run the IDE ` - -* :ref:`Compile and upload a program ` - -* :ref:`Test the USB serial connection ` +.. contents:: Contents + :local: .. _maple-quickstart-get-ide: diff --git a/source/prolog.rst b/source/prolog.rst new file mode 100644 index 0000000..2823947 --- /dev/null +++ b/source/prolog.rst @@ -0,0 +1,7 @@ +.. Additions to this file will be included at the beginning of every +.. .rst file. DO NOT USE IT to insert a header; this is not +.. recommended by the Sphinx people, who have other ways of doing it. + +.. Common substitutions +.. |vcc| replace:: V\ :sub:`cc` +.. |i2c| replace:: I\ :sup:`2`\ C diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index b878ae4..9d452d1 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -2,231 +2,212 @@ .. _troubleshooting: -======================= - Maple Troubleshooting -======================= - -* :ref:`Hardware Problems ` - - * The status LED is throbbing and I can't upload my program! - * My board is bricked! I can't upload via the bootloader no matter what! - * My 5v peripheral doesn't work! (I2C, SPI, USART, etc) - * The reset and D38/serial buttons don't seem to work reliably! - -* :ref:`IDE installation problems ` - - * I don't have root/administrator access! - * [Linux] I don't use udev! - -* :ref:`IDE usage problems ` - - * [Mac OSX] The "Board" and "Serial Port" menu items are missing! - -* :ref:`Common compiler problems ` - - * ``NullPointerException`` - * ``undefined reference to setup()/loop()`` - * ``error: 'Serial' was not declared in this scope`` - * ``File(s) not found`` - -* :ref:`Common upload problems ` - - * My program is too large! - * ``No DFU capable USB device found`` - * I have multiple Maples installed; how do I know which one will get flashed? +Troubleshooting +=============== -* :ref:`Command-line issues ` +This page documents common problems and their solutions. - * My flash programs don't seem to stick; they behave like they are RAM! - * [Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` +.. contents:: Contents + :local: -* :ref:`Tips and tricks ` - - * Perpetual bootloader mode - -.. _troubleshooting-hardware: - -Hardware problems ------------------ +=================== + Hardware problems +=================== The status LED is throbbing and I can't upload my program! +---------------------------------------------------------- - The LED throbs when there has been a failed software - :ref:`assertion `. +The LED throbs when there has been a failed software :ref:`assertion +`. - You can still reprogram by resetting the board and uploading - during the short window when the bootloader waits for a - program. +You can still reprogram by resetting the board and uploading during +the short window when the bootloader waits for a program. - To make this window longer (it can be hard to get the timing - right), use :ref:`perpetual bootloader mode - `. +To make this window longer (it can be hard to get the timing right), +use :ref:`perpetual bootloader mode +`. My board is bricked! I can't upload via the bootloader no matter what! +---------------------------------------------------------------------- - Use the hardcoded serial STM32 serial bootloader to re-flash the - bootloader. +Use the hardcoded serial STM32 serial bootloader to re-flash the +bootloader. - .. TODO insert docs on reflashing the bootloader +.. TODO insert docs on reflashing the bootloader - If it really is bricked, and you think it's our fault, - `contact us `_\ ! +If it really is bricked, and you think it's our fault, `contact us +`_\ ! My 5v peripheral doesn't work! (I2C, SPI, USART, etc) +----------------------------------------------------- - Yup, the Maple is a 3.3v board. You may need to use a level - converter. See the :ref:`compatibility `, - :ref:`GPIO `, or other :ref:`hardware specific documentation - ` for more information. +Yup, the Maple is a 3.3v board. You may need to use a level +converter. See the :ref:`compatibility `, :ref:`GPIO +`, or other :ref:`hardware specific documentation ` +for more information. The reset and D38/serial buttons don't seem to work reliably! +------------------------------------------------------------- - A few rev3 boards shipped in May-June 2010 may have had unreliable - buttons; see the :ref:`errata page ` for details. `We're - happy to replace these for you `_\ ! +A few rev3 boards shipped in May-June 2010 may have had unreliable +buttons; see the :ref:`errata page ` for details. `We're +happy to replace these for you `_\ ! -.. _troubleshooting-ide-install: -Installation problems ---------------------- +.. _troubleshooting-ide-install: +======================= + Installation problems +======================= I don't have root/administrator access! +--------------------------------------- - There are probably hacks or work-arounds to getting programs - uploaded without higher level system permissions. If you can - access USB character devices (ACM or ttyUSB style), you should be - able to communicate with the Maple and reprogram using an FTDI - converter and the serial bootloader, but we haven't tried. +There are probably hacks or work-arounds to getting programs uploaded +without higher level system permissions. If you can access USB +character devices (ACM or ttyUSB style), you should be able to +communicate with the Maple and reprogram using an FTDI converter and +the serial bootloader, but we haven't tried. - .. TODO: be more helpful +.. TODO: be more helpful [Linux] I don't use udev! +------------------------- - There is probably a simple way to get autoconfiguration working - with devfs; in the meantime, you could try running the entire IDE - as root. +There is probably a simple way to get autoconfiguration working with +devfs; in the meantime, you could try running the entire IDE as root. - .. TODO: be more helpful +.. TODO: be more helpful .. _troubleshooting-ide-usage: -IDE problems ------------- +============== + IDE problems +============== -[Mac OSX] The "Board" and "Serial Port" menu items are missing! +[Mac OS X] The "Board" and "Serial Port" menu items are missing! +---------------------------------------------------------------- - Sometimes this happens if you try to compile or upload without - having a board selected. The work-around is to restart the - IDE. Mysterious! +Sometimes this happens if you try to compile or upload without having +a board selected. The work-around is to restart the IDE. Mysterious! .. _troubleshooting-compilation: -Common compiler problems ------------------------- +========================== + Common compiler problems +========================== ``NullPointerException`` +------------------------ - A classic! Make sure you have selected a board from the pulldown menu. +A classic! Make sure you have selected a board from the pulldown menu. - .. TODO: remove when Python version is released +.. TODO: remove when Python version is released ``undefined reference to setup()/loop()`` +----------------------------------------- - Your sketch/program either does not include one of the `setup - `_ or `loop `_ functions, or it was not found by - the compiler. Your program must include both ``void setup()`` and - ``void loop()`` functions; they don't have to do anything, but - they **must** be there. +Your sketch/program either does not include one of the `setup +`_ or `loop `_ functions, or it was not found by the +compiler. Your program must include both ``void setup()`` and ``void +loop()`` functions; they don't have to do anything, but they **must** +be there. - You can start with an example program (to see one in the IDE, - click on File > Examples > Stubs > BareMinimum) to get the basic - structure. See also the :ref:`language ` documentation. +You can start with an example program (to see one in the IDE, click on +File > Examples > Stubs > BareMinimum) to get the basic structure. +See also the :ref:`language ` documentation. - This is a common error when your entire sketch is blank. +This is a common error when your entire sketch is blank. ``error: 'Serial' was not declared in this scope`` +-------------------------------------------------- - The classic Arduino has only one USART device and uses the unique - name "Serial" to control it. Larger devices like the Arduino Mega - and the Maple have multiple USARTS referred to as ``Serial1``, - ``Serial2``, etc. You probably want ``Serial2`` on the Maple; - that's the one connected to pins D0 and D1. See also the - :ref:`USART docs `. +The classic Arduino has only one USART device and uses the unique name +"Serial" to control it. Larger devices like the Arduino Mega and the +Maple have multiple USARTS referred to as ``Serial1``, ``Serial2``, +etc. You probably want ``Serial2`` on the Maple; that's the one +connected to pins D0 and D1. See also the :ref:`USART docs `. ``File(s) not found`` +--------------------- - There is an intermittent bug with the temporary directory build - system that on occasion will lose many of the ``#include``\ d - libmaple files. If you recompile everything, it should be fine. +There is an intermittent bug with the temporary directory build system +that on occasion will lose many of the ``#include``\ d libmaple +files. If you recompile everything, it should be fine. - .. TODO remove when the Python version is released +.. TODO remove when the Python version is released .. _troubleshooting-upload: -Common upload problems ----------------------- +======================== + Common upload problems +======================== My program is too large! +------------------------ - First, make sure you're using the FLASH target instead of RAM; - there is several times more FLASH memory available for user - programs. +First, make sure you're using the FLASH target instead of RAM; there +is several times more FLASH memory available for user programs. ``No DFU capable USB device found`` +----------------------------------- - This probably means you don't have a Maple plugged in or powered on! +This probably means you don't have a Maple plugged in or powered on! I have multiple Maples installed; how do I know which one will get flashed? +--------------------------------------------------------------------------- - Because the Maple IDE uses DFU to upload programs, you can't - select a particular Maple from the Serial Port menu to upload to a - particular board. There's no solution to this problem for now: - you'll have to just plug in the Maples one at a time. If this is a - real problem let us know and we'll see if we can come up with a - better solution. +Because the Maple IDE uses DFU to upload programs, you can't select a +particular Maple from the Serial Port menu to upload to a particular +board. There's no solution to this problem for now: you'll have to +just plug in the Maples one at a time. If this is a real problem let +us know and we'll see if we can come up with a better solution. .. _troubleshooting-shell: -Command-line issues -------------------- +===================== + Command-line issues +===================== My flash programs don't seem to stick; they behave like they are RAM! +--------------------------------------------------------------------- - Make sure you :command:`make clean` when switching between FLASH - and RAM targets; :command:`make` isn't smart enough to rebuild - everything that needs to be for the new target. +Make sure you :command:`make clean` when switching between FLASH and +RAM targets; :command:`make` isn't smart enough to rebuild everything +that needs to be for the new target. [Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` +----------------------------------------------------- - This is a nasty one! It means that all 32 possible CDC_ACM serial - devices (:file:`/dev/ttyACM25`, etc.) have been used up. +This is a nasty one! It means that all 32 possible CDC_ACM serial +devices (:file:`/dev/ttyACM25`, etc.) have been used up. - The usual cause is using a serial port monitor and not closing it - before restarting the Maple or uploading a new program. The - operating system doesn't like that, and locks up that - device. After reset the Maple comes back up as a new device. If - you develop heavily and don't restart you'll blow right through - all 32 devices. +The usual cause is using a serial port monitor and not closing it +before restarting the Maple or uploading a new program. The operating +system doesn't like that, and locks up that device. After reset the +Maple comes back up as a new device. If you develop heavily and don't +restart you'll blow right through all 32 devices. - The lazy solution is to always close the monitor before - restarting, and if you get this error in :file:`dmesg` after a - dfu-util "Not Found" error, restart you machine. +The lazy solution is to always close the monitor before restarting, +and if you get this error in :file:`dmesg` after a dfu-util "Not +Found" error, restart you machine. - The hacker solution is to restart your cdc_acm kernel module. On - Ubuntu 09.10, this goes a little something like:: +The hacker solution is to restart your cdc_acm kernel module. On +Ubuntu 09.10, this goes a little something like:: - $ sudo rmmod cdc-acm - $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko + $ sudo rmmod cdc-acm + $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko .. _troubleshooting-tips-tricks: -Tips and Tricks ---------------- +================= + Tips and Tricks +================= .. _troubleshooting-perpetual-bootloader: -**Perpetual Bootloader Mode** +Perpetual Bootloader Mode +------------------------- In this mode, Maple stays a DFU device and does not jump to user code until the next reset. This is useful for guaranteeing that your Maple @@ -234,13 +215,13 @@ will be available for reprogramming. To put your Maple into perpetual bootloader mode: -1. Plug your Maple into the USB port. +#. Plug your Maple into the USB port. -2. Hit the reset button on your Maple (it's the small button at the -bottom left, labeled RESET). Notice that it blinks quickly 6 times, -then blinks slowly a few more times. +#. Hit the reset button on your Maple (it's the small button at the + bottom left, labeled RESET). Notice that it blinks quickly 6 + times, then blinks slowly a few more times. -3. Hit reset again, and this time push and hold the other button -during the 6 fast blinks (the button is on the top right; it is -labeled BUT). You can release it once the slow blinks start. +#. Hit reset again, and this time push and hold the other button + during the 6 fast blinks (the button is on the top right; it is + labeled BUT). You can release it once the slow blinks start. -- cgit v1.2.3 From e001d6a587f02ad29621ce95d20c02fae971294f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 11 Oct 2010 20:19:15 -0400 Subject: sphinx bugfixes --- Doxyfile | 6 +++--- Makefile | 37 ++++++++++++++++++++----------------- README | 2 +- 3 files changed, 24 insertions(+), 21 deletions(-) diff --git a/Doxyfile b/Doxyfile index 73f18f9..21b847b 100644 --- a/Doxyfile +++ b/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NUMBER = custom-build # If a relative path is entered, it will be relative to the location # where doxygen was started. If left blank the current directory will be used. -OUTPUT_DIRECTORY = ./docs/doxygen +OUTPUT_DIRECTORY = ./doxygen # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create # 4096 sub-directories (in 2 levels) under the output directory of each output @@ -590,8 +590,8 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = libmaple/ \ - wirish/ +INPUT = ../libmaple/ \ + ../wirish/ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/Makefile b/Makefile index ffa91c5..c182a90 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,7 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest doxygen help: @echo "Please use \`make ' where is one of" @@ -36,38 +36,38 @@ help: clean: -rm -rf $(BUILDDIR)/* -html: +html: doxygen $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -dirhtml: +dirhtml: doxygen $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -singlehtml: +singlehtml: doxygen $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." -pickle: +pickle: doxygen $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." -json: +json: doxygen $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." -htmlhelp: +htmlhelp: doxygen $(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: +qthelp: doxygen $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ @@ -76,7 +76,7 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/libmaple.qhc" -devhelp: +devhelp: doxygen $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @@ -85,46 +85,49 @@ devhelp: @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/libmaple" @echo "# devhelp" -epub: +epub: doxygen $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." -latex: +latex: doxygen $(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: +latexpdf: doxygen $(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." -text: +text: doxygen $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." -man: +man: doxygen $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." -changes: +changes: doxygen $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." -linkcheck: +linkcheck: doxygen $(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: +doctest: doxygen $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." + +doxygen: + doxygen diff --git a/README b/README index 174f55a..b8bf19d 100644 --- a/README +++ b/README @@ -13,7 +13,7 @@ environment variable BREATHE_HOME to be able to build the documentation. Something like this on bash: $ git clone http://github.com/michaeljones/breathe.git - $ export BREATHE_HOME /path/to/breathe/repo/ + $ export BREATHE_HOME=/path/to/breathe/repo/ You can now build the HTML docs with (on Unix): -- cgit v1.2.3 From 9764fdc458ac8eb282d7cae10d43309e13f91fa0 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 11 Oct 2010 23:39:50 -0400 Subject: more sphinx docs --- source/_static/img/jtag-wiring.png | Bin 0 -> 40550 bytes source/bootloader.rst | 2 + source/gpio.rst | 168 ++++++++++++++------ source/i2c.rst | 87 ++++++++++- source/jtag.rst | 66 +++++++- source/language.rst | 10 +- source/pwm.rst | 159 ++++++++++++++++++- source/spi.rst | 66 +++++++- source/timers.rst | 310 ++++++++++++++++++++++++++++++++++++- source/usart.rst | 94 ++++++++++- source/usb.rst | 186 +++++++++++++++++++++- 11 files changed, 1089 insertions(+), 59 deletions(-) create mode 100644 source/_static/img/jtag-wiring.png diff --git a/source/_static/img/jtag-wiring.png b/source/_static/img/jtag-wiring.png new file mode 100644 index 0000000..9c63e82 Binary files /dev/null and b/source/_static/img/jtag-wiring.png differ diff --git a/source/bootloader.rst b/source/bootloader.rst index c4c5da2..fea1f35 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -88,6 +88,8 @@ bootloader was attractive, it became clear, after much toiling, we were going to have to write some custom drivers across several platforms to make everything work this way. +.. _bootloader-rev3: + Maple Rev3 ---------- diff --git a/source/gpio.rst b/source/gpio.rst index 2567221..9104fed 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -22,6 +22,8 @@ that pin), while some are not. .. contents:: Contents :local: +.. _pin-mapping-mega-table: + Pin Mapping Mega Table ---------------------- @@ -34,53 +36,121 @@ above). .. csv-table:: :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" - "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" - "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" - "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" - "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" - "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" - "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" - "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" - "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" - "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" - "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" - "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" - "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" - "D12", "PA6", "ADC6", "TIM3_CH1", - - SPI1_MISO No - D13 PA5 ADC5 - - - SPI1_SCK No - D14 PB8 - TIM4_CH3 - - - Yes - - Analog header - - D15 PC0 ADC10 - - - - No - D16 PC1 ADC11 - - - - No - D17 PC2 ADC12 - - - - No - D18 PC3 ADC13 - - - - No - D19 PC4 ADC14 - - - - No - D20 PC5 ADC15 - - - - No - - External header - - D21 PC13 - - - - - No - D22 PC14 - - - - - No - D23 PC15 - - - - - No - D24 PB9 - TIM4_CH4 - - - Yes - D25 PD2 - TIM3_ETR - - - Yes - D26 PC10 - - - - - Yes - D27 PB0 ADC8 TIM3_CH3 - - - No - D28 PB1 ADC9 TIM3_CH4 - - - No - D29 PB10 - - I2C2_SCL USART3_TX - Yes - D30 PB11 - - I2C2_SDA USART3_RX - Yes - D31 PB12 - TIM1_BKIN I2C2_SMBAL USART3_CK SPI2_NSS Yes - D32 PB13 - TIM1_CH1N - USART3_CTS SPI2_SCK Yes - D33 PB14 - TIM1_CH2N - USART3_RTS SPI2_MISO Yes - D34 PB15 - TIM1_CH3N - - SPI2_MOSI Yes - D35 PC6 - - - - - Yes - D36 PC7 - - - - - Yes - D37 PC8 - - - - - - - -Stub (unfinished). + "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" + "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" + "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" + "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" + "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" + "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" + "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" + "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" + "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" + "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" + "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" + "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" + "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" + "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" + "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" + "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" + "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" + "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" + "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" + "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" + "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" + "D21", "PC13", "-", "-", "-", "-", "-", "No" + "D22", "PC14", "-", "-", "-", "-", "-", "No" + "D23", "PC15", "-", "-", "-", "-", "-", "No" + "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" + "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" + "D26", "PC10", "-", "-", "-", "-", "-", "Yes" + "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" + "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" + "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" + "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" + "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBAL", "USART3_CK", "SPI2_NSS", "Yes" + "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" + "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" + "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" + "D35", "PC6", "-", "-", "-", "-", "-", "Yes" + "D36", "PC7", "-", "-", "-", "-", "-", "Yes" + "D37", "PC8", "-", "-", "-", "-", "-", "Yes" + +.. _gpio-modes: + +GPIO Modes +---------- + +``OUTPUT`` + + Basic digital output: when the pin set high the voltage is held at + +3.3V (|vcc|) and when set low it is pulled down to ground. + +``OUTPUT_OPEN_DRAIN`` + + In open drain mode, the pin indicates "low" by accepting current + flow to ground and "high" by providing increased impedance. An + example use would be to connect a pin to a bus line (which is + pulled up to a positive voltage by a separate supply through a + large resistor). When the pin is high, not much current flows + through to ground and the line stays at positive voltage; when the + pin is low the bus "drains" to ground with a small amount of + current constantly flowing through the large resistor from the + external supply. In this mode no current is ever actually + *sourced* from the pin. + +``INPUT`` (or ``INPUT_FLOATING``) + + Basic digital input. The pin voltage is sampled; when it is closer + to 3.3V (|vcc|) the pin status is high, and when it is closer to + 0V (ground) it is low. If no external circuit is pulling the pin + voltage to high or low, it will tend to randomly oscillate and be + very sensitive to noise (e.g., a breath of air across the pin will + cause the state to flip). + +``INPUT_PULLUP`` + + The state of the pin in this mode is reported the same way as with + INPUT, but the pin voltage is gently "pulled up" towards + +3.3V. This means the state will be high unless an external device + is specifically pulling the pin down to ground, in which case the + "gentle" pull up will not effect the state of the input. + +``INPUT_PULLDOWN`` + + The state of the pin in this mode is reported the same way as with + INPUT, but the pin voltage is gently "pulled down" towards + 0V. This means the state will be low unless an external device is + specifically pulling the pin up to 3.3V, in which case the + "gentle" pull down will not effect the state of the input. + +``INPUT_ANALOG`` + + This is a special mode for when the pin will be used for analog + (not digital) reads. See the :ref:`ADC ` page. + +``PWM`` + + This is a special mode for when the pin will be used for PWM + output (a special case of digital output). See the :ref:`PWM + ` page. + +.. TODO PWM_OPEN_DRAIN needs documentation + +Function Reference +------------------ + +``pinMode(pin_number, MODE)`` + + Usually called from within `setup()`_ to configure the pin. MODE + is one of the set listed :ref:`above `. + +``digitalRead(pin_number)`` + + Returns ``HIGH`` (|vcc|) or ``LOW`` (0V). + +``digitalWrite(pin_number, value)`` + + Sets the pin to ``HIGH`` or ``LOW``. .. _gpio-recommended-reading: @@ -90,5 +160,5 @@ Recommended Reading STMicro documentation for STM32F103RB microcontroller: * `All `_ - * `Datasheet (pdf) `_ - * `Reference Manual (pdf) `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/i2c.rst b/source/i2c.rst index 34bd57c..564ca0e 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -4,4 +4,89 @@ |i2c| ===== -Stub. +.. note:: + + The i2c interface is currently only available from the 'i2c' branch + of the github `libmaple `_ + repository. + +|i2c| is a crude and easy-to-hack serial protocol that requires only +two wires/channels for communication between many devices. Every +message passed on the bus is between a *master* (who initiates the +message) and a *slave* device. Slaves are addressed using 7-bit +addresses (up to 127 unique devices); 10-bit addressing is possible, +but currently unimplemented. Every message consists of an arbitrary +combination of 8-bit reads and writes as requested by the master. +Higher level functionality, such as reading a particular register +value, is achieved by writing to set the memory location then reading +to pull out the data. + +Note that the master/slave designation is on a message-by-message +basis. The Maple can act as both a master (messages initiated by user +code) and slave device (responding to requests via configurable +interrupt handlers) at the same time. + +.. contents:: Contents + :local: + +Hardware/Circuit Design +----------------------- + +The Maple has two |i2c| ports. Port 1 (i2c1) has SDA on header D9 and +SCL on D5; Port 2 (i2c2) has SDA on D30 and SCL on D29. + +The Maple reliably communicates with up to a 400kHz clock speed; this +doesn't translate into a 400kbps data rate except in extreme cases +because of addressing and protocol overhead. We have tested clock +speeds up to a megahertz and have had mixed results; in theory it +could be possible to achieve even higher rates, but signal quality +degrades rapidly and the bus becomes unreliable. + +Proper wiring and pull-up resistor selection are essential when +incorporating |i2c| into a circuit, especially with data rates above +100kHz. In the lab, we usually use approximately 5kΩ resistors with +|vcc| (3.3V) as the high voltage, and try to connect the pullup +voltage as close to the SDA and SCL pins as possible. We recommend +looking at the ST reference website for |i2c| (see the +:ref:`recommended reading ` below), starting +with a slow clock rate (10kHz), and, if possible, using an +oscilloscope to debug any issues. + +Function Reference +------------------ + +The function API for |i2c| is not finished! See the `source code +`_ for +now. + +.. TODO link to libmaple I2C docs once (1) finished, (2) in master + +SMBus +----- + +The STM32 microcontroller has hardware support for SMBus; we simply +have not written software for it. The SMBAL line for i2c1 is on header +D4 and for i2c2 is on D31. + +.. TODO link to libmaple SMBus docs once (1) finished, (2) in master + +.. _i2c-recommended-reading: + +Recommended Reading +------------------- + +* `i2c-bus.org `_ +* `Wikipedia Article on i2c `_ +* `Arduino i2c/TWI reference `_ +* STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet + `_ + (pdf) + * `Reference Manual + `_ + (pdf) + * `Application Note on Advanced I2C Usage + `_ + (pdf) diff --git a/source/jtag.rst b/source/jtag.rst index e94229f..5301a18 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -4,4 +4,68 @@ JTAG ====== -Stub. +JTAG is an interface for low-level debugging of digital devices. It +gives instruction by instruction control over the microprocessor and +allows data to be read and written to arbitrary memory and register +locations. It is typically used with a debugging tool like `gdb +`_ when hacking low level routines +and hardware peripherals (we use it when working on :ref:`libmaple +`) or to flash a new bootloader. + +Note that the STM32 on the Maple has a built-in low level serial +debugger which could also be used to flash bootloaders, and that the +:ref:`ASSERT ` framework allows basic debugging over +a USART serial channel. We expect only advanced users to use this +feature. + +.. contents:: Contents + :local: + + +Wiring Diagram +-------------- + +.. figure:: /_static/img/jtag-wiring.png + :align: center + :alt: JTAG wiring diagram + + JTAG wiring diagram to connect a standard 20-pin ARM JTAG device to + the 8-pin JTAG port on the Maple. + +.. TODO jtag wiring diagram (above) looks terrible; replace it + +The Maple has holes for a 8-pin JTAG header but that header is not +soldered on by default. If you know ahead of time that you'll be +needing it, and you order `straight from LeafLabs +`_, add a comment to your order and we can +probably solder one on for no charge. Otherwise, you can simply +attach standard 0.1" pitch male header pins (either the exact 4x2 +block or two 4-pin pieces of breakaway straight header). For a one-off +usage hack, the header can be jammed in the holes and twisted to +ensure electrical contact; this is what we do to flash our bootloader. + +The above schematic assumes that the header has been soldered on to +the *bottom* of the board, not the top; most ribbon cable connectors +will interfere with the power header. If you don't want a header +coming off the bottom, you can use a slim connector and invert this +diagram appropriately. + + +Compatible Devices +------------------ + +We have had good experience with the `Olimex ARM-USB-OCD +`_ device, which costs +about 55 euro plus shipping (as of October 2010). + + +Recommended Reading +------------------- + +* `Wikipedia Article on Joint Test Action Group (JTAG) `_ +* `STM32/gdb/OpenOCD HOWTO `_ +* STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet (pdf) `_ + * `Reference Manual (pdf) `_ diff --git a/source/language.rst b/source/language.rst index 6eb5bc7..36cb801 100644 --- a/source/language.rst +++ b/source/language.rst @@ -484,6 +484,10 @@ Recommended Reading * STMicro documentation for STM32F103RB microcontroller: * `All documents `_ - * `Datasheet (pdf) `_ - * `Reference Manual (pdf) `_ - * `Programming Manual (pdf) `_ (assembly language and register reference) + * `Datasheet (pdf) + `_ + * `Reference Manual (pdf) + `_ + * `Programming Manual (pdf) + `_ + (assembly language and register reference) diff --git a/source/pwm.rst b/source/pwm.rst index c01e415..8d3a8d9 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -4,4 +4,161 @@ Pulse-Width Modulation (PWM) ============================== -Stub. +Pulse Width Modulation is a basic technique to create repeated square +waves (digital high/low voltage transitions) of user defined length +and duty cycle. It can be used as a way to encode an "analog" signal +on a single digital (high/low) line using the time between transitions +("pulse width") as the variable; this technique is commonly used to +send servo position and motor speed commands. Another use is to use to +the ratio of "high" and "low" time to approximate a voltage output; +this technique can be used to dim an LED or even (with careful +filtering) generate audio waveforms. + +.. contents:: Contents + :local: + +Overview +-------- + +The Maple has a large number of 16-bit PWM outputs, each connected to +one of 4 timers. Some configuration, such as the clock rate or +prescaling, must be common to the entire timer; see the :ref:`timer +documentation ` for more information. + +Note that unlike the Arduino, the Maple does not have PWM +functionality on pin D10; all other pins are :ref:`compatible +`. + +The following table shows which :ref:`timer ` generates which +PWM outputs. See the :ref:`pin mapping table ` +to track down exactly which timer *channel* corresponds to each pin. + +.. _pwm-timer-table: + +.. csv-table:: + :header: Timer, PWM Headers + :delim: | + + Timer1 | D6,D7,D8 + Timer2 | D0,D1,D2,D3 + Timer3 | D11,D12,D27,D28 + Timer4 | D5,D9,D14,D24 + +Background +---------- + +In its simplest form, the device is a single counter with two +variables. The counter starts at zero, and the output starts at +"high". The counter increments every clock cycle until it reaches the +first variable number, at which point the output goes "low". The +counter continues incrementing until it reaches the second variable at +which point the output goes "high" again and the counter resets to +zero. The time spent with output high is called the **pulse duration** +or **duty**; the total time before repeat is the **period**. + +This simple functionality could be approximated in software by setting +a GPIO high or low, but the beauty of PWM is that user code simply has +to configure the device and set the two variables and the device will +function on its own; no further microprocessor cycles will be +consumed, and a repeated high/low waveform will spew out. + +The Maple has 16-bit PWM resolution, which means that the counter and +variables can be as large as 65535, as opposed to 255 with 8-bit +resolution. With a 72MHz clock rate, a PWM output could have maximum +period of about one millisecond; using a :ref:`prescaler +` (clock divider) in front of the counter can increase +this maximum period. Setting the :ref:`period ` to +something other than the maximum value gives further control over the +total length of the waveform. However, this effectively limits the +resolution with which the duty can be modified: the duty must be less +than or equal to the period. + +Here are some commonly used PWM configurations (note that servos are +notoriously variable, especially the lower cost models): + ++-------------+----------+-----------+---------+---------------+------+ +|**Purpose** |**Period**|**Duty** |Prescaler|Period |Duty | +| |(ms) |(ms) | | | | ++=============+==========+===========+=========+===============+======+ +|LED throb |0.020 |0--0.020 |1 (none) |65535 (default)|0--767| +| | | | | | | ++-------------+----------+-----------+---------+---------------+------+ +|Servo control|20 |1.25 (0°) |21 |65535 (default)|4096 | +| | | | | | | +| | |1.50 (90°) |21 |65535 (default)|4915 | +| | | | | | | +| | |1.75 (180°)|21 |65535 (default)|5734 | +| | | | | | | ++-------------+----------+-----------+---------+---------------+------+ + +Function Reference +------------------ + +``pinMode(pin_num, PWM)`` + + This command is usually called from `setup()`_ to tell the + microcontroller that pin_num should be configured to PWM + output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` is + also available (see the list of :ref:`GPIO modes ` for + more information). + +.. _pwm-pwmwrite: + +``pwmWrite(pin_num, value)`` + + This command sets the PWM duty. User code is expected to determine + and honor the maximum value (based on the configured period). As a + convenience, ``analogWrite`` is an alias for ``pwmWrite`` to ease + porting Arduino code, though period and duty will have to be + recalibrated (see :ref:`compatibility `). + +.. _pwm-overflow: + +``Timer1.setOverflow(overflow)`` + + This function sets the period ("reload" or "overflow") value for + an entire PWM timer bank. The value is 16bit (0 to 65535) and + determines the maximum value that can be written with + :ref:`pwmWrite() ` corresponding to 100% duty + cycle. This also affects the PWM frequency: the higher reload is, + the lower the PWM frequency will be. + + The PWM output pin starts HIGH, then the timer begins counting up + from zero (with frequency equal to 72MHz/:ref:`prescaler + `) until it hits the duty value, at which point it + drops to LOW. The timer then continues counting up until it hits + the total period (set with this function), at which point the + cycle starts again. + +.. _pwm-prescaler: + +``Timer[1,2,3,4].setPrescaleFactor(prescale)`` + + Find the appropriate timer for a given PWM header using the table + :ref:`above `, then set the prescaler. A + prescaler is a clock divider. The timer will normally count with + frequency equal to the STM32's normal clock (72MHz); this + corresponds to setting ``prescale`` to 1 (which is the default). + + If a longer frequency is desired, use a larger ``prescale`` value. + For instance, an 8MHz frequency can be achieved by setting + ``prescale`` to 9, since 72MHz / 9 = 8MHz. + + This function is normally called once from, `setup()`_, but the + timer can be reconfigured with a new prescaler at any time. + +Recommended Reading +------------------- + +* `Wikipedia Article on Pulse-width modulation + `_ +* `Arduino tutorial on PWM `_ +* `Secrets of Arduino PWM + `_ by Ken + Shirriff +* `So You Want To Use PWM, Eh? `_ at Non-Lexical Vocables +* STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet (pdf) `_ + * `Reference Manual (pdf) `_ diff --git a/source/spi.rst b/source/spi.rst index 8518f3c..3c29b79 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -4,4 +4,68 @@ SPI ===== -Stub. +The Maple has two SPI ports. The first has NSS on D10, MOSI on D11, +MISO on D12, and SCK on D13. The second has NSS on D31, SCK on D32, +MISO on D33, and MOSI on D34. + +.. _spi-speeds: + +Each port can be configured at one of the following speeds: + +* ``SPI_18MHZ``: 18 MHz +* ``SPI_9MHZ``: 9 MHz +* ``SPI_4_5MHZ``: 4.5 MHz +* ``SPI_2_25MHZ``: 2.25 MHz +* ``SPI_1_125MHZ``: 1.124 MHz +* ``SPI_562_500KHZ``: 562.500 KHz +* ``SPI_281_250KHZ``: 281.250 KHz +* ``SPI_140_625KHZ``: 140.625 KHz + +.. contents:: Contents + :local: + +Function Reference +------------------ + +``HardwareSPI Spi(number);`` + + This declaration must be included at the start of any sketch or + program that uses the SPI interface. The argument number is either + 1 or 2 and specifies which port to use. + +``Spi.begin(freq, endianness, mode)`` + + ``begin`` is usually called in `setup()`_ to configure the + baudrate of the given SPI port and to set up the header pins + appropriately. ``freq`` is one of the set listed :ref:`above + `; ``endianness`` is either ``LSBFIRST`` or + ``MSBFIRST``; mode is one of 0, 1, 2, 3, and specifies which "SPI + Mode" is used (see specification docs linked below). + +``Spi.begin()`` + + A default ``begin`` with no arguments is provided for the lazy; it + is equivalent to ``Spi.begin(SPI_1_125MHZ, MSBFIRST, 0)``. + +``Spi.send(data, size)`` + + Writes data into the port buffer to be transmitted as soon as + possible. ``data`` should be an array of type ``byte*``; ``size`` + should be the number of elements in ``data``. + +Recommended Reading +------------------- + +* `Wikipedia Article on Serial Peripheral Interface Bus (SPI) + `_ +* `Arduino reference on SPI + `_ +* `Hardcore SPI on Arduino `_ by kik64 +* STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet (pdf) + `_ + * `Reference Manual (pdf) + `_ + diff --git a/source/timers.rst b/source/timers.rst index c156d4f..e0e57cb 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -1,7 +1,315 @@ +.. highlight:: cpp + .. _timers: ======== Timers ======== -Stub. +There are four general purpose timers in the Maple microcontroller +that can be configured to generate periodic or delayed events with +minimal work done by the microcontroller. For example, the :ref:`PWM +` channels, once enabled, generate regular square-wave signals on +specific output pins that will continue even if the microcontroller is +busy crunching numbers or handling communications interrupts. By +attaching interrupt handlers to these channels (instead of just +changing the voltage on an external pin), more complex events like +printing to a serial port, updating a variable, or emitting a whale +mating call can be scheduled. You can even modify the configuration of +the timer itself at a regular interval; the possibilities are endless! + +The four timers each have four separate compare channels. Each timer +is a single 16-bit counter that can be configured with both a +prescaler and an overflow value. The prescaler acts as a divider of +the 72MHz system clock; without prescaling the counter would get up to +65536 (2 to the 16th power) and roll over more than a thousand times a +second; even with the full prescaler it rolls over about once a +minute. The overflow value is the maximum value the counter will go up +to. It defaults to the full 65535; smaller values will cause the +counter to reset to zero more frequently. + + +Caveats +------- + +**PWM Conflicts:** Because PWM functionality on a given pin depends on +the configuration of the timer and channel, you must chose your +channels carefully if you want to use both timer interrupts and PWM in +the same program. Refer to the full :ref:`pin mapping table +` to match up timer channels and Maple header +pin numbers. + +**Overhead:** there is some overhead associated with function and +interrupt calls (loading and unloading the stack, preparing state, +etc.) and this overhead can fudge your timing. Imperfect code +branching also means that, e.g., channel 1 interrupts may get called a +couple clock cycles sooner than a channel 4 interrupt, all other +configuration being the same. + +.. compound:: + + **Jitter:** other interrupts (USB, Serial, SysTick, or other + timers) can and will get called before or during the timer + interrupt routines, causing pseudo-random delays and other + frustrations. + + Disabling the USB port (by calling ``SerialUSB.end()``, or just + running off a battery) helps a lot, but then you lose the + auto-reset and communications functionality. This will require + that you put your Maple into :ref:`perpetual bootloader mode + ` before uploading a new + program to it. + + Disabling SysTick with ``systick_disable()`` helps as well. + However, calling this function will break the ``micros()`` and + ``millis()`` functions. + +**General:** working with timers and interrupts can be tricky and hard +to debug; they are a somewhat "advanced" topic. Start simple, test +with :ref:`ASSERT() `, and don't try to do too much +in your interrupt handlers! Make sure that what you're trying to do in +a handler isn't going to block other interrupts from firing (e.g. USB, +Serial, SysTick) if those other interrupts are important for your +program. + +.. _timers-modes: + +General Timer Modes +------------------- + +``TIMER_DISABLED`` + + Exactly what it sounds like: the timer stops counting, interrupts + are not called, and no state changes are output. + +``TIMER_PWM`` + + This is the default mode for pins after initialization. See the + :ref:`PWM docs ` for more information on this mode. + + .. note:: + + ``Timer1.setChannel1Mode(TIMER_PWM)`` may not work as expected; + if you want PWM functionality on a channel, make sure you don't + set it to something else. + +``TIMER_OUTPUTCOMPARE`` + + In this mode, the timer counts from 0 to the overflow value + repeatedly; every time the counter value reaches one of the + channel compare values, the corresponding interrupt is fired. + +SysTick Peripheral +------------------ + +The SysTick peripheral allows another, simple way to perform periodic +or delayed events. This separate timer does not conflict with any +other peripherals, but the associated 1kHz interrupt can jitter the +general purpose timer interrupts; this is clearly seen when running +VGA code, where the timing jitters are transformed into visual jags in +the image. The SysTick peripheral can be disabled by calling +``systick_disable()``, and re-enabled using ``systick_resume()``. + +Function Reference +------------------ + +For all of these functions, ``Timer1`` can be replaced with +``Timer2``, ``Timer3``, or ``Timer4``; the channel numbers also range +from 1 to 4. + +``Timer1.pause()``/\ ``Timer1.resume()`` + + These functions start and stop the counter without affecting the + rest of the configuration. These functions can be used during the + setup period to prevent interrupts from firing before they are + completely configured. Note that there is some function call + overhead with these functions, so they are not a perfect way to + align multiple timers to the same count value. + +``Timer1.setOverflow(val)`` + + Sets the overflow (or "reload") value for the whole timer; when + the counter reaches this value it resets to zero. Defaults to + 65535 (the largest unsigned 16bit integer); setting it to anything + lower will cause interrupts to be called more frequently (see the + setPeriod function below for a shortcut). This number sets the + maximum value for the channel compare values. + +``Timer1.setPrescaleFactor(val)`` + + The prescaler acts as a clock divider to slow down the rate at + which the counter increments. For example, the system clock rate + is 72MHz, so the counter will reach 65535 in (13.89 nanoseconds) * + (65535 counts) = (910.22 microseconds), or about a thousand times + a second. If you set the prescaler to 1098, then the clock rate is + effectively 65.56KHz, and the counter will reach 65536 in (15.25 + microseconds) * (65536 counts) = (0.999 seconds), or just about + once a second. Use the :ref:`setPeriod ` + function below if you are allergic to math! + +.. _timers-set-period: + +``Timer1.setPeriod(val)`` + + This tricky trick will configure the prescaler and overflow values + to generate a timer reload with a period as close to val + microseconds as possible. It returns the chosen overflow value, + which you can then use to set the channel compare values + appropriately: if you just want the interrupts to fire when the + clock rolls over and you don't care about the relative "phase", + you can always set the channel compare values to 1. + + Remember: a microsecond is 1/1,000,000th of a second, or 1/1,000 + of a millisecond. The prescaler itself is 16bit, so the longest + period that can be configured is 1/(72MHz) * (2^32) = (59.65 + seconds) or about a minute. You can get around this by creating an + interrupt that increments a 32-bit variable, by using the + ``millis()`` function, or by interfacing with an external + real-time-clock chip. + +``Timer1.setCount(val)``/\ ``Timer1.getCount()`` + + These functions let you mess with the counter's brains + directly. You can probably make it not work if you try! The timer + is 16bit, so ``val`` and the return value of ``getCount`` are + ``uint16``. + +``Timer1.setChannel1Mode(MODE)`` + + This sets the given channel (here 1) of the given timer (here 1) + to the given mode. See the :ref:`list above ` for + possible values; for interrupts you want ``TIMER_OUTPUTCOMPARE``. + +``Timer1.setCompare1(val)`` + + Sets the compare value for the given channel; when the counter + reaches this value the interrupt for this channel will fire if the + channel is in output compare mode and an interrupt is attached. + + By default this only changes the relative offsets between events + on a single timer ("phase"); they don't control the frequency with + which they occur. However, a common trick is to increment the + compare value manually in the interrupt handler so that the event + will fire again after the increment period. There can be a + different increment value for each channel, so this trick allows + events to be programmed at 4 different rates on a single timer! + Note that function call overhead means that the smallest increment + rate is a couple microseconds. + +``Timer1.attachCompare1Interrupt(function)``/\ ``Timer1.detachCompare1Interrupt()`` + + This is how to attach or disable an interrupt handlers to timer + channels; this what will get called when the counter reaches the + compare value set with ``setCompareN(val)``. ``function`` + (sometimes referred to as an ISR: "interrupt service routine") + should be of a type that does not accept or return any values + (C/C++ programmers: ``void (function*)(void)``). They are just + like any other function in your sketch/program and must be + initialized at the top of the file and defined below. + + ``function`` should try to do what it has to do as fast as + possible. Blinking the LED, some logic, PWM updates, and Serial + writes are fine; writing to SerialUSB or waiting for user input + can take a long time and other compare interrupts won't fire. Tip: + if you have a ``delay()`` in your ISR, you're probably doing it + wrong. + + Stay vigilant here... function pointers are serious business, and + once you go down that path you'll find yourself in a `forest of + parentheses `_ before you know it. + +Code Examples +------------- + +LED blink +^^^^^^^^^ + +\ :: + + #define LED_PIN 13 + #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles + + void handler_led(void); + + int toggle = 0; + + void setup() + { + // Set up the LED to blink + pinMode(LED_PIN, OUTPUT); + + // Setup Timer + Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer2.setPeriod(LED_RATE); // in microseconds + Timer2.setCompare1(1); // overflow might be small + Timer2.attachCompare1Interrupt(handler_led); + } + + void loop() { + // Nothing! It's all in the interrupts + } + + void handler_led(void) { + toggle ^= 1; + digitalWrite(LED_PIN, toggle); + } + +Racing Counters +^^^^^^^^^^^^^^^ + +\ :: + + #define BUTTON_PIN 38 + + void handler_count1(void); + void handler_count2(void); + + int count1 = 0; + int count2 = 0; + + void setup() + { + // Set up BUT for input + pinMode(BUTTON_PIN, INPUT_PULLUP); + + // Setup Counting Timers + Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer3.pause(); + Timer4.pause(); + Timer3.setCount(0); + Timer4.setCount(0); + Timer3.setOverflow(30000); + Timer4.setOverflow(30000); + Timer3.setCompare1(1000); // somewhere in the middle + Timer4.setCompare1(1000); + Timer3.attachCompare1Interrupt(handler1); + Timer4.attachCompare1Interrupt(handler2); + Timer3.resume(); + Timer4.resume(); + } + + void loop() { + // Display the running counts + SerialUSB.print("Count 1: "); + SerialUSB.print(count1); + SerialUSB.print("\t\tCount 2: "); + SerialUSB.println(count2); + + // Run... while BUT is held, pause Count2 + for(int i = 0; i<1000; i++) { + if(digitalRead(BUTTON_PIN)) { + Timer4.pause(); + } else { + Timer4.resume(); + } + delay(1); + } + } + + void handler1(void) { + count1++; + } + void handler2(void) { + count2++; + } diff --git a/source/usart.rst b/source/usart.rst index 30c953a..19b054f 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -4,4 +4,96 @@ USART ======= -Stub. +.. contents:: + :local: + +Hardware/Circuit Design +----------------------- + +The Maple has 3 separate USART devices: ``Serial1``, ``Serial2``, and +``Serial3``. In the most simple use case, the RX and TX pins are used +to send data at a predetermined baudrate with the line voltage level +relative to ground. + ++-----------+--------+-----+ +|Port |Function|Pin | ++===========+========+=====+ +|``Serial1``|TX |D7 | +| | | | +| |RX |D8 | +| | | | +| |CK |D6 | ++-----------+--------+-----+ +|``Serial2``|TX |D1 | +| | | | +| |RX |D0 | +| | | | +| |CK |D10 | +| | | | +| |CTS |D2 | +| | | | +| |RTS |D3 | ++-----------+--------+-----+ +|``Serial3``|TX |D29 | +| | | | +| |RX |D30 | +| | | | +| |CK |D31 | +| | | | +| |CTS |D32 | +| | | | +| |RTS |D33 | ++-----------+--------+-----+ + +.. TODO make above less ugly + +Compatible Devices and Specifications +------------------------------------- + +We have successfully used the Maple USART ports with an FT232R-based USB-serial converter at up to 115200 baud; higher speeds should certainly be possible. + +Function Reference +------------------ + +In the following, you may replace ``SerialN`` with ``Serial1``, +``Serial2``, or ``Serial3``. + +``SerialN.begin(baudrate)`` + + ``SerialN.begin`` is usually called in `setup()`_ to configure the + baudrate of the given serial port and to set up the header pins + appropriately. It can be called at any time to reconfigure a port + or to change the baudrate. 9600 baud is the generic speed most + widely supported by other devices and terminals. + +``SerialN.print(...)``/\ ``SerialN.println(...)`` + + Writes data into the port buffer to be transmitted as soon as + possible. Accepts strings (``char*``). If a raw integer is + passed, the corresponding ASCII character will be transmitted; to + print out a number in human readable form add a second parameter + with the base system. + + For example, to print out the decimal number '1234' use + ``SerialN.print(1234, DEC)``; to print out the binary number + '1001', use ``SerialN.print(9, BIN)``. + +``SerialN.available()``/\ ``SerialN.read()`` + + ``SerialN.read()`` will return the next unread character that has + been received over the port. ``SerialN.available()`` returns how + many such bytes are available (or zero if none are). If none are + available, ``SerialN.read()`` will block/fail, so the usual + program structure is to poll with ``SerialN.available`` and only + read if a nonzero value is returned. + +Recommended Reading +------------------- + +* `Wikipedia article on Universal asynchronous receiver/transmitter (USART) `_ +* `Arduino reference on Serial `_ +* STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/usb.rst b/source/usb.rst index 2460df5..1ce91f0 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -1,7 +1,191 @@ +.. highlight:: cpp + .. _usb: ===== USB ===== -Stub. +.. note:: Changes and Caveats + + The SerialUSB functionality was modified for the 0.0.6 IDE + release. It now includes a 50 millisecond timeout for writes and + does not try to detect if the USB host is "really" connected or + just enumerated and initialized. This means that if you have a + number of SerialUSB writes or prints in your code and you are not + monitoring on a computer your program will run much, much slower + than if it is being monitored or totally disconnected (battery). + + You can avoid this behavior by :ref:`deciphering the port status + ` using the DTR and RTS line status; the behavior + of these control lines is platform dependent and we no longer + interpret them by default. + +The Maple STM32 microprocessor includes a dedicated USB peripheral +which can be configured to act as a general USB slave device with +transfer rates up to 12Mbps (it unfortunately can't be configured as a +host or on-the-go device). By default, the peripheral is configured +for two uses: first, to receive sketch/program uploads from the IDE, +and second, to emulate a regular serial port for use as a terminal +(text read/write). + +The emulated terminal is relatively slow and inefficient; it is best +for transferring data at regular serial speeds (kilobaud). Users +requiring faster data transfer should consider implementing a +different communications protocol; the Maple could be reprogrammed to +appear as a mass storage device (thumb drive), human interface device +(mouse or keyboard), microphone, or any other USB device. + +The SerialUSB channel is also used as part of the auto-reset feature +of the IDE to program the board (on Maple Rev3): a :ref:`magic +sequence of control line toggles and transmitted data +` causes the Maple to reset itself and enter +bootloader mode. As an unfortunate consequence, the auto-reset will +not work if the IDE can not access the serial port, either due to a +conflict with another program (serial monitor) or because the +interface has been disabled from the Maple side (through +``SerialUSB.end()``). + +Function Reference +------------------ + +``SerialUSB.print(...)``/\ ``SerialUSB.println(...)`` + + Writes data into the port buffer to be transmitted as soon as + possible. Accepts strings (``char*``). If a raw integer is passed + the corresponding ASCII character will be transmitted; to print + out a number in human readable form add a second parameter with + the base system. For example, to print out the decimal number + "1234", use ``SerialUSB.print(1234, DEC)``; to print out the + binary number "1001", use ``SerialUSB.print(9, BIN)``. + +.. _usb-write: + +``SerialUSB.write(bytes)`` + + ``write`` is a lower-level function that writes bytes directly + into the buffer. :ref:`print() ` often calls this + function dozens of times to write out a single formatted number; + user code can optimize raw data speed by calling this function + with 64-byte chunks instead. + +``SerialUSB.available()``/\ ``SerialUSB.read()`` + + ``SerialUSB.read()`` will return the next available character + (``byte``) that has been received over the port. + ``SerialUSB.available()`` returns how many such bytes are actually + available. If there is no data, ``read`` will block/fail, so the + usual program structure is to poll with ``available`` and only + ``read`` if there are data to read. + +``SerialUSB.read(buffer, length)`` + + An alternative version of ``SerialUSB.read``; will write the next + ``length`` available characters into the array ``buffer``. + +``SerialUSB.pending()`` + + Returns the number of bytes waiting in the transmit + buffer. Usercode can use this to prevent any blocking/waiting when + using the direct :ref:`write ` functions, or to check + if data was actually requested/received by the host. + +``SerialUSB.getRTS()`` + + Returns the state (1 or 0) of the virtual RTS ("ready to send") + line. This can be used to guess if the USB host is actively + waiting for data (e.g., if a serial monitor program is running) or + just "configured" (i.e., the virtual serial port is configured, + but no program is reading data). + +``SerialUSB.getDTR()`` + + Returns the state (1 or 0) of the virtual DTR ("data terminal + ready") line. This can be used to guess if the USB host is + actively waiting for data (e.g., if a serial monitor program is + running) or just "configured" (i.e., the virtual serial port is + configured, but no program is reading data). + +.. TODO deprecate crap out of above two functions; write a sane API + +``SerialUSB.isConnected()`` + + Returns 1 if the USB host is connected and the virtual serial + interface is initialized (though not necessarily active). + Otherwise, returns 0. + +``SerialUSB.end()``/\ ``SerialUSB.begin()`` + + The USB peripheral is enabled by default so that the auto-reset + feature will work, but it can be disabled/restarted at any time + with the ``SerialUSB.end()`` and ``SerialUSB.begin()`` + functions. + + ``SerialUSB.end()`` is a relatively hard shutdown, similar to + unplugging the board; this may crash or confuse any programs + running host-side. Note that calling this function will require + the Maple to be put into :ref:`perpetual bootloader mode + ` before another program can + be uploaded onto it, unless ``SerialUSB.begin()`` is called before + the upload is attempted. + + It's probably wise to wait a few seconds between calls to + ``SerialUSB.end()`` and ``SerialUSB.begin()`` (or to + ``SerialUSB.begin()`` and ``SerialUSB.print()``) to let the + computer reconfigure. + +Code Examples +------------- + +.. _usb-safe-print: + +Safe Print +^^^^^^^^^^ + +This function should run smoothly and not block; the LED should blink +at roughly the same speed whether being monitored, running from +battery, or connected but not monitored. You may need to experiment +with the DTR/RTS logic for your platform and device configuration. :: + + #define LED_PIN 13 + + void setup() { + /* Set up the LED to blink */ + pinMode(LED_PIN, OUTPUT); + } + + void loop() { + // LED will stay off if we are disconnected; + // will blink quickly if USB is unplugged (battery etc) + if(SerialUSB.isConnected()) { + digitalWrite(LED_PIN, 1); + } + delay(100); + + // If this logic fails to detect if bytes are going to + // be read by the USB host, then the println() will fully + // many times, causing a very slow LED blink. + // If the characters are printed and read, the blink will + // only slow a small amount when "really" connected, and fast + // when the virtual port is only configured. + if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) { + for(int i=0; i<10; i++) { + SerialUSB.println(123456,BIN); + } + } + digitalWrite(LED_PIN, 0); + delay(100); + } + +Recommended Reading +------------------- + +* `USB in a NutShell `_ overview from Beyond Logic +* `Wikipedia article on Universal Serial Bus (USB) `_ +* Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ +* STMicro documentation for STM32F103RB microcontroller: + + * `All documents `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Programming Manual `_ (pdf; assembly language and register reference) -- cgit v1.2.3 From 1b2faa19df53008a88a16913644e478e58da5c78 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 11 Oct 2010 23:47:56 -0400 Subject: switching docs to leaflabs fork of breathe --- README | 11 +++++++---- source/compatibility.rst | 4 +--- source/errata.rst | 2 -- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/README b/README index b8bf19d..b467d2d 100644 --- a/README +++ b/README @@ -8,11 +8,14 @@ You need a recent-ish version of doxygen in your PATH: http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc For the Doxygen-to-Sphinx bridge, we rely on a project called Breathe, -by Michael Jones. You must clone the breathe repository and set an -environment variable BREATHE_HOME to be able to build the -documentation. Something like this on bash: +by Michael Jones. - $ git clone http://github.com/michaeljones/breathe.git +***** You must clone the LEAFLABS VERSION OF THE breathe repository ****** + + ... and then set an environment variable BREATHE_HOME to be able to +build the documentation. Something like this on bash: + + $ git clone git@github.com:leaflabs/breathe.git $ export BREATHE_HOME=/path/to/breathe/repo/ You can now build the HTML docs with (on Unix): diff --git a/source/compatibility.rst b/source/compatibility.rst index 6166ec5..8872a1b 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -130,7 +130,5 @@ I sorta work And I am also ordinary -Stub. - -(not finished) +Stub (unfinished) diff --git a/source/errata.rst b/source/errata.rst index 09b2ad1..4b03513 100644 --- a/source/errata.rst +++ b/source/errata.rst @@ -14,5 +14,3 @@ list of differences between the Maple and Arduinos, see the page on :local: Stub. - -(not finished) -- cgit v1.2.3 From abcfcc62cc62dfc088d30d5a6b6c36d6c89f7b07 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 20 Oct 2010 06:17:31 -0400 Subject: weird broken table for maple mini --- Doxyfile | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Doxyfile b/Doxyfile index 21b847b..4016c05 100644 --- a/Doxyfile +++ b/Doxyfile @@ -147,7 +147,7 @@ SHORT_NAMES = NO # comments will behave just like regular Qt-style comments # (thus requiring an explicit @brief command for a brief description.) -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # If the QT_AUTOBRIEF tag is set to YES then Doxygen will # interpret the first line (until the first dot) of a Qt-style @@ -608,9 +608,7 @@ INPUT_ENCODING = UTF-8 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 -FILE_PATTERNS = *.c \ - *.cpp \ - *.h +FILE_PATTERNS = *.h # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. @@ -1442,7 +1440,7 @@ PERL_PATH = /usr/bin/perl # fallback. It is recommended to install and use dot, since it yields more # powerful graphs. -CLASS_DIAGRAMS = YES +CLASS_DIAGRAMS = NO # You can define message sequence charts within doxygen comments using the \msc # command. Doxygen will then run the mscgen tool (see @@ -1502,19 +1500,19 @@ DOT_FONTPATH = # indirect inheritance relations. Setting this tag to YES will force the # the CLASS_DIAGRAMS tag to NO. -CLASS_GRAPH = YES +CLASS_GRAPH = NO # If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen # will generate a graph for each documented class showing the direct and # indirect implementation dependencies (inheritance, containment, and # class references variables) of the class with other documented classes. -COLLABORATION_GRAPH = YES +COLLABORATION_GRAPH = NO # If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen # will generate a graph for groups, showing the direct groups dependencies -GROUP_GRAPHS = YES +GROUP_GRAPHS = NO # If the UML_LOOK tag is set to YES doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling -- cgit v1.2.3 From 85c1c72db022bba891868afd3375e39dbe245701 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 20 Oct 2010 06:46:52 -0400 Subject: initial check-in of arduino docs in RST format (converted using wget+pandoc) --- flibbit.py | 26 ++++ source/adc.rst | 18 +-- source/arduino/abs.rst | 33 +++++ source/arduino/analogread.rst | 134 ++++++++++++++++++++ source/arduino/analogreference.rst | 66 ++++++++++ source/arduino/analogwrite.rst | 116 ++++++++++++++++++ source/arduino/arithmetic.rst | 104 ++++++++++++++++ source/arduino/array.rst | 114 +++++++++++++++++ source/arduino/assignment.rst | 63 ++++++++++ source/arduino/attachinterrupt.rst | 114 +++++++++++++++++ source/arduino/bit.rst | 42 +++++++ source/arduino/bitclear.rst | 48 ++++++++ source/arduino/bitread.rst | 48 ++++++++ source/arduino/bitset.rst | 47 +++++++ source/arduino/bitshift.rst | 127 +++++++++++++++++++ source/arduino/bitwiseand.rst | 230 +++++++++++++++++++++++++++++++++++ source/arduino/bitwisecompound.rst | 227 ++++++++++++++++++++++++++++++++++ source/arduino/bitwisexornot.rst | 51 ++++++++ source/arduino/bitwrite.rst | 52 ++++++++ source/arduino/boolean.rst | 94 ++++++++++++++ source/arduino/booleanvariables.rst | 53 ++++++++ source/arduino/braces.rst | 113 +++++++++++++++++ source/arduino/break.rst | 28 +++++ source/arduino/byte.rst | 29 +++++ source/arduino/bytecast.rst | 41 +++++++ source/arduino/changes.rst | 93 ++++++++++++++ source/arduino/char.rst | 51 ++++++++ source/arduino/charcast.rst | 41 +++++++ source/arduino/comments.rst | 45 +++++++ source/arduino/comparison.rst | 54 ++++++++ source/arduino/const.rst | 55 +++++++++ source/arduino/constants.rst | 144 ++++++++++++++++++++++ source/arduino/constrain.rst | 60 +++++++++ source/arduino/continue.rst | 29 +++++ source/arduino/cos.rst | 33 +++++ source/arduino/define.rst | 83 +++++++++++++ source/arduino/delay.rst | 94 ++++++++++++++ source/arduino/delaymicroseconds.rst | 93 ++++++++++++++ source/arduino/detachinterrupt.rst | 26 ++++ source/arduino/digitalread.rst | 86 +++++++++++++ source/arduino/digitalwrite.rst | 113 +++++++++++++++++ source/arduino/double.rst | 32 +++++ source/arduino/dowhile.rst | 33 +++++ source/arduino/else.rst | 73 +++++++++++ source/arduino/float.rst | 88 ++++++++++++++ source/arduino/floatcast.rst | 51 ++++++++ source/arduino/for.rst | 117 ++++++++++++++++++ source/arduino/fpconstants.rst | 36 ++++++ source/arduino/goto.rst | 55 +++++++++ source/arduino/highbyte.rst | 42 +++++++ source/arduino/if.rst | 95 +++++++++++++++ source/arduino/include.rst | 42 +++++++ source/arduino/increment.rst | 58 +++++++++ source/arduino/incrementcompound.rst | 49 ++++++++ source/arduino/int.rst | 84 +++++++++++++ source/arduino/intcast.rst | 41 +++++++ source/arduino/integerconstants.rst | 130 ++++++++++++++++++++ source/arduino/interrupts.rst | 59 +++++++++ source/arduino/long.rst | 50 ++++++++ source/arduino/longcast.rst | 41 +++++++ source/arduino/loop.rst | 39 ++++++ source/arduino/lowbyte.rst | 42 +++++++ source/arduino/map.rst | 119 ++++++++++++++++++ source/arduino/max.rst | 71 +++++++++++ source/arduino/micros.rst | 66 ++++++++++ source/arduino/millis.rst | 67 ++++++++++ source/arduino/min.rst | 71 +++++++++++ source/arduino/modulo.rst | 84 +++++++++++++ source/arduino/nointerrupts.rst | 56 +++++++++ source/arduino/notone.rst | 47 +++++++ source/arduino/pinmode.rst | 67 ++++++++++ source/arduino/pointer.rst | 16 +++ source/arduino/pow.rst | 47 +++++++ source/arduino/pulsein.rst | 79 ++++++++++++ source/arduino/random.rst | 92 ++++++++++++++ source/arduino/randomseed.rst | 70 +++++++++++ source/arduino/return.rst | 69 +++++++++++ source/arduino/scope.rst | 56 +++++++++ source/arduino/semicolon.rst | 27 ++++ source/arduino/serial.rst | 62 ++++++++++ source/arduino/setup.rst | 31 +++++ source/arduino/shiftout.rst | 133 ++++++++++++++++++++ source/arduino/sin.rst | 35 ++++++ source/arduino/sizeof.rst | 71 +++++++++++ source/arduino/sqrt.rst | 33 +++++ source/arduino/static.rst | 71 +++++++++++ source/arduino/string.rst | 158 ++++++++++++++++++++++++ source/arduino/stringobject.rst | 88 ++++++++++++++ source/arduino/switchcase.rst | 77 ++++++++++++ source/arduino/tan.rst | 35 ++++++ source/arduino/tone.rst | 78 ++++++++++++ source/arduino/unsignedchar.rst | 41 +++++++ source/arduino/unsignedint.rst | 77 ++++++++++++ source/arduino/unsignedlong.rst | 63 ++++++++++ source/arduino/void.rst | 37 ++++++ source/arduino/volatile.rst | 70 +++++++++++ source/arduino/while.rst | 46 +++++++ source/arduino/word.rst | 29 +++++ source/arduino/wordcast.rst | 51 ++++++++ source/arm-gcc.rst | 13 ++ source/conf.py | 1 + source/epilog.rst | 8 ++ source/foo.rst | 114 +++++++++++++++++ source/gpio.rst | 75 ++---------- source/i2c.rst | 10 +- source/index.rst | 3 +- source/jtag.rst | 6 +- source/language.rst | 13 +- source/pwm.rst | 6 +- source/spi.rst | 8 +- source/usart.rst | 6 +- source/usb.rst | 9 +- 112 files changed, 6928 insertions(+), 109 deletions(-) create mode 100644 flibbit.py create mode 100644 source/arduino/abs.rst create mode 100644 source/arduino/analogread.rst create mode 100644 source/arduino/analogreference.rst create mode 100644 source/arduino/analogwrite.rst create mode 100644 source/arduino/arithmetic.rst create mode 100644 source/arduino/array.rst create mode 100644 source/arduino/assignment.rst create mode 100644 source/arduino/attachinterrupt.rst create mode 100644 source/arduino/bit.rst create mode 100644 source/arduino/bitclear.rst create mode 100644 source/arduino/bitread.rst create mode 100644 source/arduino/bitset.rst create mode 100644 source/arduino/bitshift.rst create mode 100644 source/arduino/bitwiseand.rst create mode 100644 source/arduino/bitwisecompound.rst create mode 100644 source/arduino/bitwisexornot.rst create mode 100644 source/arduino/bitwrite.rst create mode 100644 source/arduino/boolean.rst create mode 100644 source/arduino/booleanvariables.rst create mode 100644 source/arduino/braces.rst create mode 100644 source/arduino/break.rst create mode 100644 source/arduino/byte.rst create mode 100644 source/arduino/bytecast.rst create mode 100644 source/arduino/changes.rst create mode 100644 source/arduino/char.rst create mode 100644 source/arduino/charcast.rst create mode 100644 source/arduino/comments.rst create mode 100644 source/arduino/comparison.rst create mode 100644 source/arduino/const.rst create mode 100644 source/arduino/constants.rst create mode 100644 source/arduino/constrain.rst create mode 100644 source/arduino/continue.rst create mode 100644 source/arduino/cos.rst create mode 100644 source/arduino/define.rst create mode 100644 source/arduino/delay.rst create mode 100644 source/arduino/delaymicroseconds.rst create mode 100644 source/arduino/detachinterrupt.rst create mode 100644 source/arduino/digitalread.rst create mode 100644 source/arduino/digitalwrite.rst create mode 100644 source/arduino/double.rst create mode 100644 source/arduino/dowhile.rst create mode 100644 source/arduino/else.rst create mode 100644 source/arduino/float.rst create mode 100644 source/arduino/floatcast.rst create mode 100644 source/arduino/for.rst create mode 100644 source/arduino/fpconstants.rst create mode 100644 source/arduino/goto.rst create mode 100644 source/arduino/highbyte.rst create mode 100644 source/arduino/if.rst create mode 100644 source/arduino/include.rst create mode 100644 source/arduino/increment.rst create mode 100644 source/arduino/incrementcompound.rst create mode 100644 source/arduino/int.rst create mode 100644 source/arduino/intcast.rst create mode 100644 source/arduino/integerconstants.rst create mode 100644 source/arduino/interrupts.rst create mode 100644 source/arduino/long.rst create mode 100644 source/arduino/longcast.rst create mode 100644 source/arduino/loop.rst create mode 100644 source/arduino/lowbyte.rst create mode 100644 source/arduino/map.rst create mode 100644 source/arduino/max.rst create mode 100644 source/arduino/micros.rst create mode 100644 source/arduino/millis.rst create mode 100644 source/arduino/min.rst create mode 100644 source/arduino/modulo.rst create mode 100644 source/arduino/nointerrupts.rst create mode 100644 source/arduino/notone.rst create mode 100644 source/arduino/pinmode.rst create mode 100644 source/arduino/pointer.rst create mode 100644 source/arduino/pow.rst create mode 100644 source/arduino/pulsein.rst create mode 100644 source/arduino/random.rst create mode 100644 source/arduino/randomseed.rst create mode 100644 source/arduino/return.rst create mode 100644 source/arduino/scope.rst create mode 100644 source/arduino/semicolon.rst create mode 100644 source/arduino/serial.rst create mode 100644 source/arduino/setup.rst create mode 100644 source/arduino/shiftout.rst create mode 100644 source/arduino/sin.rst create mode 100644 source/arduino/sizeof.rst create mode 100644 source/arduino/sqrt.rst create mode 100644 source/arduino/static.rst create mode 100644 source/arduino/string.rst create mode 100644 source/arduino/stringobject.rst create mode 100644 source/arduino/switchcase.rst create mode 100644 source/arduino/tan.rst create mode 100644 source/arduino/tone.rst create mode 100644 source/arduino/unsignedchar.rst create mode 100644 source/arduino/unsignedint.rst create mode 100644 source/arduino/unsignedlong.rst create mode 100644 source/arduino/void.rst create mode 100644 source/arduino/volatile.rst create mode 100644 source/arduino/while.rst create mode 100644 source/arduino/word.rst create mode 100644 source/arduino/wordcast.rst create mode 100644 source/arm-gcc.rst create mode 100644 source/foo.rst diff --git a/flibbit.py b/flibbit.py new file mode 100644 index 0000000..5f149d4 --- /dev/null +++ b/flibbit.py @@ -0,0 +1,26 @@ +import os +import shutil +import re +from os.path import * + +src = '/Users/mbolivar/foo/arduino.cc/en/Reference' +dst = '/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino' + +fs = [x for x in os.listdir(src) if x.endswith('.rst')] + +def process(line): + if re.match('-+$', line.rstrip()): + return '=' * (len(line) - 1) + '\n' + elif re.match('\^+$', line.rstrip()): + return '-' * (len(line) - 1) + '\n' + return line + +for f in fs: + print 'processing:', f + with open(join(src,f), 'r') as f_in: + with open(join(dst, basename(f)), 'w') as f_out: + label = '.. _arduino-%s:\n\n' % (f.split('.')[0]) + f_out.write(label) + for line in list(f_in.readlines())[20:-22]: + f_out.write(process(line)) + diff --git a/source/adc.rst b/source/adc.rst index 4e118aa..c1281be 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -19,6 +19,10 @@ number of techniques must be used to get good precision and accuracy. D0, D1, D2, D3, D10, D11, D12, D13, D15, D16, D17, D18, D19, D20, D27, D28 + Note that pins 3, 27, and 28 are not marked AIN on the silkscreen + for Maple revisions through Rev 5, however, they **do work** as + analog input pins. + .. contents:: Contents :local: @@ -55,7 +59,7 @@ range; opamps and other powered components can also be used. Function Reference ------------------ -.. TODO function reference (figure out Doxygen first) +TODO function reference (figure out Doxygen first) .. _adc-recommended-reading: @@ -66,10 +70,8 @@ Recommended Reading * `Arduino Analog Input Tutorial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet (pdf) `_ - * `Reference Manual (pdf) `_ - * `Application Note on ADC Modes (pdf) `_ - * `Application Note on ADC Oversampling (pdf) `_ - - + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Application Note on ADC Modes (pdf) `_ + * `Application Note on ADC Oversampling (pdf) `_ diff --git a/source/arduino/abs.rst b/source/arduino/abs.rst new file mode 100644 index 0000000..5d699ae --- /dev/null +++ b/source/arduino/abs.rst @@ -0,0 +1,33 @@ +.. _arduino-abs: + +abs(x) +====== + +Description +----------- + +(Macro) computes the absolute value of a number. + +Parameters +---------- + +**x**: the number + +Returns +------- + +**x**: if **x** is greater than or equal to 0. + +**-x**: if **x** is less than 0. + +Warning +------- + +Because of the way ``abs()`` is implemented, avoid using other +functions or causing side effects inside the brackets, as it may lead +to incorrect results :: + + abs(a++); // avoid this - yields incorrect results + + a++; // use this instead - + abs(a); // keep other math outside the function diff --git a/source/arduino/analogread.rst b/source/arduino/analogread.rst new file mode 100644 index 0000000..d0fa5a1 --- /dev/null +++ b/source/arduino/analogread.rst @@ -0,0 +1,134 @@ +.. highlight:: cpp + +.. _arduino-analogread: + +analogRead() +============ + + +Signature +--------- + +``int analogRead(int pin);`` + + +Description +----------- + +Reads the value from the specified analog pin. The Maple board +contains a 16-channel, 12-bit analog to digital converter. This means +that it will map input voltages between 0 and 3.3 volts into integer +values between 0 and 4095. This yields a resolution between readings +of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors +interfere with getting full accuracy and precision. For more +information, see :ref:`adc`. + +Before calling analogRead() on a pin, that pin must first be +configured for analog input, using :ref:`arduino-pinMode`. + +The input range and resolution can be changed using +:ref:`arduino-analogReference`. + +It takes about 0.8 microseconds (.0000008 seconds) to read an analog +input, so the maximum sample rate using this function is approximately +1.3 million samples per second [#fsamp]_. + + +Parameters +---------- + +**pin** + + The number of the analog input pin to read from. Header pins on the + Maple with ADC functionality (marked as "AIN" on the silkscreen) + are: + + 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 + + Note that pins 3, 27, and 28 are not marked AIN on the silkscreen + for Maple revisions through Rev 5, however, they **do work** as + analog input pins. + +Returns +------- + +Converted input voltage as an ``int``, with value 0 to 4095, inclusive. + + +Note +---- + +If the analog input pin is not connected to anything, the value +returned by analogRead() will fluctuate based on a number of factors +(e.g. the values of the other analog inputs, how close your hand is to +the board, etc.). + + +Example +------- + + :: + + + int analogPin = 3; // potentiometer wiper (middle terminal) connected to analog pin 3 + // outside leads to ground and +3.3V + int val = 0; // variable to store the value read + + void setup() { + pinMode(analogPin, INPUT_ANALOG); + SerialUSB.begin(); + } + + void loop() { + val = analogRead(analogPin); // read the input pin + SerialUSB.println(val); // debug value + } + + +Arduino Compatibility Note +-------------------------- + +The Arduino board contains a 6 channel (8 channels on the Mini and +Nano, 16 on the Mega), 10-bit analog to digital converter. This means +that it will map input voltages between 0 and 5 volts into integer +values between 0 and 1023. This yields a resolution between readings +of: 5 volts / 1024 units or, .0049 volts (4.9 mV) per unit. On the +Arduino, the input range and resolution can be changed using their +implementation of `analogReference() +`_\ . + +On the Arduino, it takes about 100 microseconds (0.0001 s) to read an +analog input, so the maximum reading rate is about 10,000 times a +second. + + +See also +-------- + +- :ref:`ADC note ` +- :ref:`analogReference ` +- `(Arduino) Tutorial: Analog Input Pins `_ + + +.. rubric:: Footnotes + +.. [#fsamp] This is based on the current configuration of a 55.5 cycle + sample time, at 72 MHz. However, the minimum sample time *possible* + is 1.5 cycles, leading to a theoretical maximum of approximately 48 + million samples per second (of course, doing anything with the + readings also consumes cycles, so this maximum can't be reached in + practice). + + See the `STM32 Reference Manual `_, §§11.12.4--5 + (pp. 225--226), for more information on the low-level bit twiddling + currently necessary to change the sample time. For examples of how + the ADCs are configured in libmaple, see `adc.h + `_ + and `adc.c + `_\ + . Be aware that changing the sample time has important + consequences related to the impedance of the device connected to + the input pin. If you want to make changes, as a minimum, you + should first read ST's application notes on `ADC modes + `_ and `ADC oversampling + `_. diff --git a/source/arduino/analogreference.rst b/source/arduino/analogreference.rst new file mode 100644 index 0000000..9a25169 --- /dev/null +++ b/source/arduino/analogreference.rst @@ -0,0 +1,66 @@ +.. _arduino-analogreference: + +analogReference(type) +===================== + +Description +----------- + +Configures the reference voltage used for analog input (i.e. the +value used as the top of the input range). The options are: + + + + +- DEFAULT: the default analog reference of 5 volts (on 5V Arduino + boards) or 3.3 volts (on 3.3V Arduino boards) +- INTERNAL: an built-in reference, equal to 1.1 volts on the + ATmega168 or ATmega328 and 2.56 volts on the ATmega8. +- EXTERNAL: the voltage applied to the AREF pin is used as the + reference. + + + +Parameters +---------- + +type: which type of reference to use (DEFAULT, INTERNAL, or +EXTERNAL). + + + +Returns +------- + +None. + + + +Warning +------- + +**If you're using an external reference voltage (applied to the AREF pin), you must set the analog reference to EXTERNAL before calling analogRead().** +Otherwise, you will short together the active reference voltage +(internally generated) and the AREF pin, possibly damaging the +microcontroller on your Arduino board. + + + +Alternatively, you can connect the external reference voltage to +the AREF pin through a 5K resistor, allowing you to switch between +external and internal reference voltages. Note that the resistor +will alter the voltage that gets used as the reference because +there is an internal 32K resistor on the AREF pin. The two act as a +voltage divider, so, for example, 2.5V applied through the resistor +will yield 2.5 \* 32 / (32 + 5) = ~2.2V at the AREF pin. + + + +See also +-------- + + +- `Description of the analog input pins `_ +- `analogRead `_\ () + + diff --git a/source/arduino/analogwrite.rst b/source/arduino/analogwrite.rst new file mode 100644 index 0000000..64ecd5b --- /dev/null +++ b/source/arduino/analogwrite.rst @@ -0,0 +1,116 @@ +.. _arduino-analogwrite: + +analogWrite() +============= + +TODO + +In libmaple, analogWrite is just a convenience alias for +:ref:`pwmWrite`. This is because PWM is not true analog output (i.e., +is not the output of a DAC), so the name was badly-chosen; however, +for the sake of compatibility, the alias was provided. + +.. doxygenfunction:: pwmWrite + +Description +----------- + +Writes an analog value +(`PWM wave `_) to a pin. Can be +used to light a LED at varying brightnesses or drive a motor at +various speeds. After a call to **analogWrite()**, the pin will +generate a steady square wave of the specified duty cycle until the +next call to **analogWrite()** (or a call to **digitalRead()** or +**digitalWrite()** on the same pin). The frequency of the PWM +signal is approximately 490 Hz. + + + +On most Arduino boards (those with the ATmega168 or ATmega328), +this function works on pins 3, 5, 6, 9, 10, and 11. On the Arduino +Mega, it works on pins 2 through 13. Older Arduino boards with an +ATmega8 only support analogWrite() on pins 9, 10, and 11. You do +not need to call pinMode() to set the pin as an output before +calling analogWrite(). + + + +The *analogWrite* function has nothing whatsoever to do with the +analog pins or the *analogRead* function. + + + +Syntax +------ + +analogWrite(pin, value) + + + +Parameters +---------- + +pin: the pin to write to. + + + +value: the duty cycle: between 0 (always off) and 255 (always on). + + + +Returns +------- + +nothing + + + +Notes and Known Issues +---------------------- + +The PWM outputs generated on pins 5 and 6 will have +higher-than-expected duty cycles. This is because of interactions +with the millis() and delay() functions, which share the same +internal timer used to generate those PWM outputs. This will be +noticed mostly on low duty-cycle settings (e.g 0 - 10) and may +result in a value of 0 not fully turning off the output on pins 5 +and 6. + + + +Example +------- + +Sets the output to the LED proportional to the value read from the +potentiometer. + + + +:: + + + int ledPin = 9; // LED connected to digital pin 9 + int analogPin = 3; // potentiometer connected to analog pin 3 + int val = 0; // variable to store the read value + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the pin as output + } + + void loop() + { + val = analogRead(analogPin); // read the input pin + analogWrite(ledPin, val / 4); // analogRead values go from 0 to 1023, analogWrite values from 0 to 255 + } + + + +See also +-------- + + +- `analogRead `_\ () +- `Tutorial: PWM `_ + + diff --git a/source/arduino/arithmetic.rst b/source/arduino/arithmetic.rst new file mode 100644 index 0000000..cbe3059 --- /dev/null +++ b/source/arduino/arithmetic.rst @@ -0,0 +1,104 @@ +.. highlight:: cpp + +.. _arduino-arithmetic: + +Addition, Subtraction, Multiplication, & Division +================================================= + +Description +----------- + +These operators return the sum, difference, product, or quotient +(respectively) of the two operands. The operation is conducted using +the data type of the operands, so, for example, ``9 / 4`` gives ``2`` +since 9 and 4 are ints. + +This also means that the operation can overflow if the result is +larger than that which can be stored in the data type (e.g. adding 1 +to an :ref:`arduino-int` with the value 2147483647 gives +-2147483648). If the operands are of different types, the "larger" +type is used for the calculation. + +(The specifics of these rules are beyond the scope of this +documentation; for more information, see `The C++ Programming Language +`_\ , by Bjarne +Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks +entry on C++ type conversion +`_\ +. For more information on how computers represent integers, see the +Wikipedia page on `two's complement +`_\ ). + +If one of the numbers (operands) are of the type **float** or of type +**double**, floating point math will be used for the +calculation. + +Examples +-------- + + :: + + y = y + 3; + x = x - 7; + i = j * 6; + r = r / 5; + + +Syntax +------ + + :: + + result = value1 + value2; + result = value1 - value2; + result = value1 * value2; + result = value1 / value2; + + +Parameters: +----------- + +**value1**: any numeric variable or constant + +**value2**: any numeric variable or constant + + +Arduino Compatibility Note +-------------------------- + +Since the STM32 processor on the Maple is a 32-bit machine, the int +type overflows at a much higher value on Maple than on Arduino. In +particular, on Maple, ints do not overflow (become negative) until +they reach 2,147,483,648; on the Arduino, they overflow at 32,767. +Because of this, programs running on Maple are much less likely to run +into overflow issues. + + +Programming Tips: +----------------- + +- Know that :ref:`integer constants ` + default to :ref:`int `, so some constant calculations + may overflow (e.g., 200000 * 5000000 will yield a negative result). + +- Choose variable sizes that are large enough to hold the largest + results from your calculations. + +- Know at what point your variable will "roll over" and also what + happens in the other direction e.g. (0 - 1) for unsigned arithmetic, + or (0 - -2,147,483,648) for signed arithmetic. + +- For math that requires fractions, float variables may be used, but + be aware of their drawbacks: large size and slow computation speeds + (the STM32 has no floating point hardware, so all floating point + calculations have to be done in software). + +- Use the cast operator e.g. (int)myFloat to convert one variable type + to another on the fly. + + +See Also +-------- + +- `libmaple_types.h `_ + diff --git a/source/arduino/array.rst b/source/arduino/array.rst new file mode 100644 index 0000000..f6bc141 --- /dev/null +++ b/source/arduino/array.rst @@ -0,0 +1,114 @@ +.. highlight:: cpp + +.. _arduino-array: + +Arrays +====== + +An array is a collection of variables that are accessed with an index +number. Arrays in the C++ programming language, in which the Maple is +programmed, can be complicated, but using simple arrays is relatively +straightforward. + + +Creating (Declaring) an Array +----------------------------- + +All of the methods below are valid ways to create (declare) an +array. :: + + int myInts[6]; + int myPins[] = {2, 4, 8, 3, 6}; + int mySensVals[6] = {2, 4, -8, 3, 2}; + char message[6] = "hello"; + +You can declare an array without initializing it, as with myInts. In +the line referring to myPins, we declare an array without explicitly +choosing a size. The compiler counts the elements and creates an +array of the appropriate size. + +Finally, you can both initialize and size your array, as in +mySensVals. Note that when declaring an array with elements of type +char, one more element than your initialization is required, to hold +the required `null character `_. + + +Accessing an Array +------------------ + + +.. compound:: + + Arrays are **zero indexed**; that is, referring to the array + initialization above, the first element of the array is at index 0, + hence :: + + mySensVals[0] == 2; + mySensVals[1] == 4 + + and so forth. + +It also means that in an array with ten elements, index nine is the +last element. Hence:: + + int myArray[10]={9,3,2,4,3,2,7,8,9,11}; + // myArray[9] contains 11 + // myArray[10] is invalid and contains random information (other memory address) + +For this reason, you should be careful in accessing arrays. Accessing +past the end of an array (using an index number greater than your +declared array size - 1) is reading from memory that is in use for +other purposes. Reading from these locations is probably not going to +do much except yield invalid data. Writing to random memory locations +is definitely a bad idea, and can often lead to unhappy results such +as crashes or program malfunction. This can also be a difficult bug to +track down. + +Unlike Basic or Java, the C compiler does no checking to see if array +access is within legal bounds of the array size that you have +declared. + + +To assign a value to an array: +------------------------------ + :: + + mySensVals[0] = 10; + + +To retrieve a value from an array: +---------------------------------- + + :: + + x = mySensVals[4]; + + +Arrays and ``for`` Loops +------------------------ + +Arrays are often manipulated inside :ref:`for loops `, where +the loop counter is used as the index for each array element. For +example, to print the elements of an array over the serial port, you +could do something like this:: + + int i; + for (i = 0; i < 5; i = i + 1) { + SerialUSB.println(myPins[i]); + } + + +Example +------- + +For a complete program that demonstrates the use of arrays, see the +Arduino `Knight Rider example +`_\ (which will run +unmodified on the Maple). + + +See also +-------- + +- :ref:`Storing arrays in FLASH memory ` + diff --git a/source/arduino/assignment.rst b/source/arduino/assignment.rst new file mode 100644 index 0000000..8b851e8 --- /dev/null +++ b/source/arduino/assignment.rst @@ -0,0 +1,63 @@ +.. highlight:: cpp + +.. _arduino-assignment: + += assignment operator (single equal sign) +========================================= + +Stores the value to the right of the equal sign in the variable to +the left of the equal sign. + + +The single equal sign in the C++ programming language is called the +assignment operator. It has a different meaning than in algebra +class where it indicated an equation or equality. The assignment +operator tells the microcontroller to evaluate whatever value or +expression is on the right side of the equal sign, and store it in +the variable to the left of the equal sign [#fgross]_. + + + +Example +------- + +:: + + int sensVal; // declare an integer variable named sensVal + senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal + + + +Programming Tips +---------------- + +The variable on the left side of the assignment operator ( = sign ) +needs to be able to hold the value stored in it. If it is not large +enough to hold a value, the value stored in the variable will be +incorrect. + + + +Don't confuse the assignment operator [ = ] (single equal sign) +with the comparison operator [ == ] (double equal signs), which +evaluates whether two expressions are equal. + + + +See Also +-------- + + +- `if (comparison operators) `_ +- `char `_ +- `int `_ +- `long `_ + + +.. rubric:: Footnotes + + Experienced C++ programmers know this to be an oversimplification + of what happens when the variable on the left hand side is an + object. See Richard Gillam's wonderful and scary `The Anatomy of + the Assignment Operator + `_ diff --git a/source/arduino/attachinterrupt.rst b/source/arduino/attachinterrupt.rst new file mode 100644 index 0000000..27a1d77 --- /dev/null +++ b/source/arduino/attachinterrupt.rst @@ -0,0 +1,114 @@ +.. _arduino-attachinterrupt: + +attachInterrupt(interrupt, function, mode) +========================================== + + + +Description +----------- + +Specifies a function to call when an external interrupt occurs. +Replaces any previous function that was attached to the interrupt. +Most Arduino boards have two external interrupts: numbers 0 (on +digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an +additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 +(pin 18). + + + +Parameters +---------- + +**interrupt**: the number of the interrupt (*int*) + + + +**function**: the function to call when the interrupt occurs; this +function must take no parameters and return nothing. This function +is sometimes referred to as an *interrupt service routine.* + + + +**mode** defines when the interrupt should be triggered. Four +contstants are predefined as valid values: + + +- **LOW** to trigger the interrupt whenever the pin is low, +- **CHANGE** to trigger the interrupt whenever the pin changes + value +- **RISING** to trigger when the pin goes from low to high, +- **FALLING** for when the pin goes from high to low. + + + +Returns +------- + +none + + + +Note +---- + +*Inside the attached function, delay() won't work and the value returned by millis() will not increment. Serial data received while in the function may be lost. You should declare as volatile any variables that you modify within the attached function.* + + + +Using Interrupts +---------------- + +Interrupts are useful for making things happen automatically in +microcontroller programs, and can help solve timing problems. A +good task for using an interrupt might be reading a rotary encoder, +monitoring user input. + + + +If you wanted to insure that a program always caught the pulses +from a rotary encoder, never missing a pulse, it would make it very +tricky to write a program to do anything else, because the program +would need to constantly poll the sensor lines for the encoder, in +order to catch pulses when they occurred. Other sensors have a +similar interface dynamic too, such as trying to read a sound +sensor that is trying to catch a click, or an infrared slot sensor +(photo-interrupter) trying to catch a coin drop. In all of these +situations, using an interrupt can free the microcontroller to get +some other work done while not missing the doorbell. + + + +Example +------- + +:: + + int pin = 13; + volatile int state = LOW; + + void setup() + { + pinMode(pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() + { + digitalWrite(pin, state); + } + + void blink() + { + state = !state; + } + + + +See also +-------- + + +- `detachInterrupt `_ + + diff --git a/source/arduino/bit.rst b/source/arduino/bit.rst new file mode 100644 index 0000000..f8241a5 --- /dev/null +++ b/source/arduino/bit.rst @@ -0,0 +1,42 @@ +.. _arduino-bit: + +bit() +===== + +Description +----------- + +Computes the value of the specified bit (bit 0 is 1, bit 1 is 2, +bit 2 is 4, etc.). + + + +Syntax +------ + +bit(n) + + + +Parameters +---------- + +n: the bit whose value to compute + + + +Returns +------- + +the value of the bit + + + +See also +-------- + + +- `bitRead `_\ () +- `bitWrite `_\ () +- `bitSet `_\ () +- `bitClear `_\ () diff --git a/source/arduino/bitclear.rst b/source/arduino/bitclear.rst new file mode 100644 index 0000000..e86dbc5 --- /dev/null +++ b/source/arduino/bitclear.rst @@ -0,0 +1,48 @@ +.. _arduino-bitclear: + +bitClear() +========== + +Description +----------- + +Clears (writes a 0 to) a bit of a numeric variable. + + + +Syntax +------ + +bitClear(x, n) + + + +Parameters +---------- + +x: the numeric variable whose bit to clear + + + +n: which bit to clear, starting at 0 for the least-significant +(rightmost) bit + + + +Returns +------- + +none + + + +See also +-------- + + +- `bit `_\ () +- `bitRead `_\ () +- `bitWrite `_\ () +- `bitSet `_\ () + + diff --git a/source/arduino/bitread.rst b/source/arduino/bitread.rst new file mode 100644 index 0000000..3d0b1a4 --- /dev/null +++ b/source/arduino/bitread.rst @@ -0,0 +1,48 @@ +.. _arduino-bitread: + +bitRead() +========= + +Description +----------- + +Reads a bit of a number. + + + +Syntax +------ + +bitRead(x, n) + + + +Parameters +---------- + +x: the number from which to read + + + +n: which bit to read, starting at 0 for the least-significant +(rightmost) bit + + + +Returns +------- + +the value of the bit (0 or 1). + + + +See also +-------- + + +- `bit `_\ () +- `bitWrite `_\ () +- `bitSet `_\ () +- `bitClear `_\ () + + diff --git a/source/arduino/bitset.rst b/source/arduino/bitset.rst new file mode 100644 index 0000000..882ec92 --- /dev/null +++ b/source/arduino/bitset.rst @@ -0,0 +1,47 @@ +.. _arduino-bitset: + +bitSet() +======== + +Description +----------- + +Sets (writes a 1 to) a bit of a numeric variable. + + + +Syntax +------ + +bitSet(x, n) + + + +Parameters +---------- + +x: the numeric variable whose bit to set + + + +n: which bit to set, starting at 0 for the least-significant +(rightmost) bit + + + +Returns +------- + +none + + + +See also +-------- + + +- `bit `_\ () +- `bitRead `_\ () +- `bitWrite `_\ () +- `bitClear `_\ () + diff --git a/source/arduino/bitshift.rst b/source/arduino/bitshift.rst new file mode 100644 index 0000000..f59b489 --- /dev/null +++ b/source/arduino/bitshift.rst @@ -0,0 +1,127 @@ +.. _arduino-bitshift: + +bitshift left (<<), bitshift right (>>) +======================================= + +Description +----------- + +From *The Bitmath Tutorial* in The Playground + + + +There are two bit shift operators in C++: the left shift operator +<< and the right shift operator >>. These operators cause the bits +in the left operand to be shifted left or right by the number of +positions specified by the right operand. +More on bitwise math may be found +`here. `_ + + + +Syntax +------ + +variable << number\_of\_bits + + + +variable >> number\_of\_bits + + + +Parameters +---------- + +variable - (byte, int, long) number\_of\_bits integer <= 32 + + + +Example: +-------- + +:: + + int a = 5; // binary: 0000000000000101 + int b = a << 3; // binary: 0000000000101000, or 40 in decimal + int c = b >> 3; // binary: 0000000000000101, or back to 5 like we started with + + + +When you shift a value x by y bits (x << y), the leftmost y bits in +x are lost, literally shifted out of existence: + + + +:: + + int a = 5; // binary: 0000000000000101 + int b = a << 14; // binary: 0100000000000000 - the first 1 in 101 was discarded + + + +If you are certain that none of the ones in a value are being +shifted into oblivion, a simple way to think of the left-shift +operator is that it multiplies the left operand by 2 raised to the +right operand power. For example, to generate powers of 2, the +following expressions can be employed: + + + +:: + + 1 << 0 == 1 + 1 << 1 == 2 + 1 << 2 == 4 + 1 << 3 == 8 + ... + 1 << 8 == 256 + 1 << 9 == 512 + 1 << 10 == 1024 + ... + + + +When you shift x right by y bits (x >> y), and the highest bit in x +is a 1, the behavior depends on the exact data type of x. If x is +of type int, the highest bit is the sign bit, determining whether x +is negative or not, as we have discussed above. In that case, the +sign bit is copied into lower bits, for esoteric historical +reasons: + + + +:: + + int x = -16; // binary: 1111111111110000 + int y = x >> 3; // binary: 1111111111111110 + + + +This behavior, called sign extension, is often not the behavior you +want. Instead, you may wish zeros to be shifted in from the left. +It turns out that the right shift rules are different for unsigned +int expressions, so you can use a typecast to suppress ones being +copied from the left: + + + +:: + + int x = -16; // binary: 1111111111110000 + int y = (unsigned int)x >> 3; // binary: 0001111111111110 + + + +If you are careful to avoid sign extension, you can use the +right-shift operator >> as a way to divide by powers of 2. For +example: + + + +:: + + int x = 1000; + int y = x >> 3; // integer division of 1000 by 8, causing y = 125. + + diff --git a/source/arduino/bitwiseand.rst b/source/arduino/bitwiseand.rst new file mode 100644 index 0000000..8d4eb3f --- /dev/null +++ b/source/arduino/bitwiseand.rst @@ -0,0 +1,230 @@ +.. _arduino-bitwiseand: + +Bitwise AND (&), Bitwise OR (\|), Bitwise XOR (^) +================================================= + +Bitwise AND (&) +--------------- + +The bitwise operators perform their calculations at the bit level +of variables. They help solve a wide range of common programming +problems. Much of the material below is from an excellent tutorial +on bitwise math wihch may be found +`here. `_ + + + +Description and Syntax +---------------------- + +Below are descriptions and syntax for all of the operators. Further +details may be found in the referenced tutorial. + + + +Bitwise AND (&) +--------------- + +The bitwise AND operator in C++ is a single ampersand, &, used +between two other integer expressions. Bitwise AND operates on each +bit position of the surrounding expressions independently, +according to this rule: if both input bits are 1, the resulting +output is 1, otherwise the output is 0. Another way of expressing +this is: + + + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) - returned result + + + +In Arduino, the type int is a 16-bit value, so using & between two +int expressions causes 16 simultaneous AND operations to occur. In +a code fragment like: + + + +:: + + int a = 92; // in binary: 0000000001011100 + int b = 101; // in binary: 0000000001100101 + int c = a & b; // result: 0000000001000100, or 68 in decimal. + + + +Each of the 16 bits in a and b are processed by using the bitwise +AND, and all 16 resulting bits are stored in c, resulting in the +value 01000100 in binary, which is 68 in decimal. + + + +One of the most common uses of bitwise AND is to select a +particular bit (or bits) from an integer value, often called +masking. See below for an example + + + +Bitwise OR (\|) +--------------- + +The bitwise OR operator in C++ is the vertical bar symbol, \|. Like +the & operator, \| operates independently each bit in its two +surrounding integer expressions, but what it does is different (of +course). The bitwise OR of two bits is 1 if either or both of the +input bits is 1, otherwise it is 0. In other words: + + + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) - returned result + + + +Here is an example of the bitwise OR used in a snippet of C++ +code: + + + +:: + + int a = 92; // in binary: 0000000001011100 + int b = 101; // in binary: 0000000001100101 + int c = a | b; // result: 0000000001111101, or 125 in decimal. + + + +Example Program +--------------- + +A common job for the bitwise AND and OR operators is what +programmers call Read-Modify-Write on a port. On microcontrollers, +a port is an 8 bit number that represents something about the +condition of the pins. Writing to a port controls all of the pins +at once. + + + +PORTD is a built-in constant that refers to the output states of +digital pins 0,1,2,3,4,5,6,7. If there is 1 in an bit position, +then that pin is HIGH. (The pins already need to be set to outputs +with the pinMode() command.) So if we write ``PORTD = B00110001;`` +we have made pins 2,3 & 7 HIGH. One slight hitch here is that we +*may* also have changeed the state of Pins 0 & 1, which are used by +the Arduino for serial communications so we may have interfered +with serial communication. + + + +:: + + Our algorithm for the program is: + + +- Get PORTD and clear out only the bits corresponding to the pins + we wish to control (with bitwise AND). +- Combine the modified PORTD value with the new value for the pins + under control (with biwise OR). + + + +:: + + int i; // counter variable + int j; + + void setup(){ + DDRD = DDRD | B11111100; // set direction bits for pins 2 to 7, leave 0 and 1 untouched (xx | 00 == xx) + // same as pinMode(pin, OUTPUT) for pins 2 to 7 + Serial.begin(9600); + } + + void loop(){ + for (i=0; i<64; i++){ + + PORTD = PORTD & B00000011; // clear out bits 2 - 7, leave pins 0 and 1 untouched (xx & 11 == xx) + j = (i << 2); // shift variable up to pins 2 - 7 - to avoid pins 0 and 1 + PORTD = PORTD | j; // combine the port information with the new information for LED pins + Serial.println(PORTD, BIN); // debug to show masking + delay(100); + } + } + + + +Bitwise XOR (^) +--------------- + +There is a somewhat unusual operator in C++ called bitwise +EXCLUSIVE OR, also known as bitwise XOR. (In English this is +usually pronounced "eks-or".) The bitwise XOR operator is written +using the caret symbol ^. This operator is very similar to the +bitwise OR operator \|, only it evaluates to 0 for a given bit +position when both of the input bits for that position are 1: + + + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) - returned result + + + +Another way to look at bitwise XOR is that each bit in the result +is a 1 if the input bits are different, or 0 if they are the same. + + + +Here is a simple code example: + + + +:: + + int x = 12; // binary: 1100 + int y = 10; // binary: 1010 + int z = x ^ y; // binary: 0110, or decimal 6 + + + +The ^ operator is often used to toggle (i.e. change from 0 to 1, or +1 to 0) some of the bits in an integer expression. In a bitwise OR +operation if there is a 1 in the mask bit, that bit is inverted; if +there is a 0, the bit is not inverted and stays the same. Below is +a program to blink digital pin 5. + + + +:: + + // Blink_Pin_5 + // demo for Exclusive OR + void setup(){ + DDRD = DDRD | B00100000; // set digital pin five as OUTPUT + Serial.begin(9600); + } + + void loop(){ + PORTD = PORTD ^ B00100000; // invert bit 5 (digital pin 5), leave others untouched + delay(100); + } + + + +See Also + + +- `&& `_ (Boolean AND) +- `\|\| `_ (Boolean OR) + diff --git a/source/arduino/bitwisecompound.rst b/source/arduino/bitwisecompound.rst new file mode 100644 index 0000000..c3c808f --- /dev/null +++ b/source/arduino/bitwisecompound.rst @@ -0,0 +1,227 @@ +.. _arduino-bitwisecompound: + +compound bitwise AND (&=), compound bitwise OR (\|=) +==================================================== + +The compound bitwise operators perform their calculations at the +bit level of variables. They are often used to clear and set +specific bits of a variable. + + + +See the +`bitwise AND (&) `_ and +`bitwise OR (\|) `_ +operators for the details of their operation, and also the +`Bitmath Tutorial `_ +for more information on bitwise operators. + + + +compound bitwise AND (&=) +========================= + +Description +----------- + +The compound bitwise AND operator (&=) is often used with a +variable and a constant to force particular bits in a variable to +the LOW state (to 0). This is often referred to in programming +guides as "clearing" or "resetting" bits. + + + +Syntax: +------- + +:: + + x &= y; // equivalent to x = x & y; + + + +Parameters +---------- + +x: a char, int or long variable +y: an integer constant or char, int, or long + + + +Example: +-------- + +First, a review of the Bitwise AND (&) operator + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) - returned result + + + +Bits that are "bitwise ANDed" with 0 are cleared to 0 so, if myByte +is a byte variable, +``myByte & B00000000 = 0;`` + + + +Bits that are "bitwise ANDed" with 1 are unchanged so, +``myByte & B11111111 = myByte;`` + + + +Note: because we are dealing with bits in a bitwise operator - it +is convenient to use the binary formatter with +`constants. `_ The +numbers are still the same value in other representations, they are +just not as easy to understand. Also, B00000000 is shown for +clarity, but zero in any number format is zero (hmmm something +philosophical there?) + + + +Consequently - to clear (set to zero) bits 0 & 1 of a variable, +while leaving the rest of the variable unchanged, use the compound +bitwise AND operator (&=) with the constant B11111100 + +:: + + 1 0 1 0 1 0 1 0 variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + 1 0 1 0 1 0 0 0 + + variable unchanged + bits cleared + + +Here is the same representation with the variable's bits replaced +with the symbol x + + + +:: + + x x x x x x x x variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + x x x x x x 0 0 + + variable unchanged + bits cleared + + +So if: + +:: + + myByte = 10101010; + + myByte &= B1111100 == B10101000; + + + +compound bitwise OR (\|=) +========================= + +Description +----------- + +The compound bitwise OR operator (\|=) is often used with a +variable and a constant to "set" (set to 1) particular bits in a +variable. + + + +Syntax: +------- + +:: + + x |= y; // equivalent to x = x | y; + + + +Parameters +---------- + +x: a char, int or long variable +y: an integer constant or char, int, or long + + + +Example: +-------- + +First, a review of the Bitwise OR (\|) operator + +:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) - returned result + +Bits that are "bitwise ORed" with 0 are unchanged, so if myByte is +a byte variable, +myByte \| B00000000 = myByte; + + + +Bits that are "bitwise ORed" with 1 are set to 1 so: +myByte & B11111111 = B11111111; + + + +Consequently - to set bits 0 & 1 of a variable, while leaving the +rest of the variable unchanged, use the compound bitwise AND +operator (&=) with the constant B00000011 + +:: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + + variable unchanged + bits set + + +Here is the same representation with the variables bits replaced +with the symbol x + + + +:: + + x x x x x x x x variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + x x x x x x 1 1 + + variable unchanged + bits set + +So if: + +:: + + myByte = B10101010; + + myByte |= B00000011 == B10101011; + + + +See Also + + +- `& `_ (bitwise AND) +- `\| `_ (bitwise OR) +- `&& `_ (Boolean AND) +- `\|\| `_ (Boolean OR) + + diff --git a/source/arduino/bitwisexornot.rst b/source/arduino/bitwisexornot.rst new file mode 100644 index 0000000..25389cb --- /dev/null +++ b/source/arduino/bitwisexornot.rst @@ -0,0 +1,51 @@ +.. _arduino-bitwisexornot: + +Bitwise NOT (~) +=============== + +The bitwise NOT operator in C++ is the tilde character ~. Unlike & +and \|, the bitwise NOT operator is applied to a single operand to +its right. Bitwise NOT changes each bit to its opposite: 0 becomes +1, and 1 becomes 0. For example: + + + +:: + + 0 1 operand1 + + + +:: + + ---------- + 1 0 ~ operand1 + + + +:: + + int a = 103; // binary: 0000000001100111 + int b = ~a; // binary: 1111111110011000 = -104 + + + +You might be surprised to see a negative number like -104 as the +result of this operation. This is because the highest bit in an int +variable is the so-called sign bit. If the highest bit is 1, the +number is interpreted as negative. This encoding of positive and +negative numbers is referred to as two's complement. For more +information, see the Wikipedia article on +`two's complement. `_ + + + +As an aside, it is interesting to note that for any integer x, ~x +is the same as -x-1. + + + +At times, the sign bit in a signed integer expression can cause +some unwanted surprises. + + diff --git a/source/arduino/bitwrite.rst b/source/arduino/bitwrite.rst new file mode 100644 index 0000000..5d95506 --- /dev/null +++ b/source/arduino/bitwrite.rst @@ -0,0 +1,52 @@ +.. _arduino-bitwrite: + +bitWrite() +========== + +Description +----------- + +Writes a bit of a numeric variable. + + + +Syntax +------ + +bitWrite(x, n, b) + + + +Parameters +---------- + +x: the numeric variable to which to write + + + +n: which bit of the number to write, starting at 0 for the +least-significant (rightmost) bit + + + +b: the value to write to the bit (0 or 1) + + + +Returns +------- + +none + + + +See also +-------- + + +- `bit `_\ () +- `bitRead `_\ () +- `bitSet `_\ () +- `bitClear `_\ () + + diff --git a/source/arduino/boolean.rst b/source/arduino/boolean.rst new file mode 100644 index 0000000..f109bdb --- /dev/null +++ b/source/arduino/boolean.rst @@ -0,0 +1,94 @@ +.. _arduino-boolean: + +Boolean Operators +================= + +These can be used inside the condition of an +`if `_ statement. + + + +&& (logical and) +~~~~~~~~~~~~~~~~ + +True only if both operands are true, e.g. + +:: + + if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches + // ... + } + +is true only if both inputs are high. + + + +\|\| (logical or) +~~~~~~~~~~~~~~~~~ + +True if either operand is true, e.g. + +:: + + if (x > 0 || y > 0) { + // ... + } + +is true if either x or y is greater than 0. + + + +! (not) +~~~~~~~ + +True if the operand is false, e.g. + +:: + + if (!x) { + // ... + } + +is true if x is false (i.e. if x equals 0). + + + +Warning +------- + +Make sure you don't mistake the boolean AND operator, && (double +ampersand) for the bitwise AND operator & (single ampersand). They +are entirely different beasts. + + + +Similarly, do not confuse the boolean \|\| (double pipe) operator +with the bitwise OR operator \| (single pipe). + + + +The bitwise not ~ (tilde) looks much different than the boolean not +! (exclamation point or "bang" as the programmers say) but you +still have to be sure which one you want where. + + + +Examples +-------- + +:: + + if (a >= 10 && a <= 20){} // true if a is between 10 and 20 + + + +See also +-------- + + +- `& `_ (bitwise AND) +- `\| `_ (bitwise OR) +- `~ `_ (bitwise NOT +- `if `_ + + diff --git a/source/arduino/booleanvariables.rst b/source/arduino/booleanvariables.rst new file mode 100644 index 0000000..3bbe72a --- /dev/null +++ b/source/arduino/booleanvariables.rst @@ -0,0 +1,53 @@ +.. _arduino-booleanvariables: + +boolean +======= + +A **boolean** holds one of two values, +`true `_ or +`false `_. (Each boolean +variable occupies one byte of memory.) + + + +Example +------- + +:: + + int LEDpin = 5; // LED on pin 5 + int switchPin = 13; // momentary switch on 13, other side connected to ground + + boolean running = false; + + void setup() + { + pinMode(LEDpin, OUTPUT); + pinMode(switchPin, INPUT); + digitalWrite(switchPin, HIGH); // turn on pullup resistor + } + + void loop() + { + if (digitalRead(switchPin) == LOW) + { // switch is pressed - pullup keeps pin high normally + delay(100); // delay to debounce switch + running = !running; // toggle running variable + digitalWrite(LEDpin, running) // indicate via LED + } + } + + + + + + +See also +-------- + + +- `constants `_ +- `boolean operators `_ +- `Variable Declaration `_ + + diff --git a/source/arduino/braces.rst b/source/arduino/braces.rst new file mode 100644 index 0000000..c7bd148 --- /dev/null +++ b/source/arduino/braces.rst @@ -0,0 +1,113 @@ +.. _arduino-braces: + +{} Curly Braces +=============== + +Curly braces (also referred to as just "braces" or as "curly +brackets") are a major part of the C programming language. They are +used in several different constructs, outlined below, and this can +sometimes be confusing for beginners. + + + +An opening curly brace "{" must always be followed by a closing +curly brace "}". This is a condition that is often referred to as +the braces being balanced. The Arduino IDE (integrated development +environment) includes a convenient feature to check the balance of +curly braces. Just select a brace, or even click the insertion +point immediately following a brace, and its logical companion will +be highlighted. + + + +At present this feature is slightly buggy as the IDE will often +find (incorrectly) a brace in text that has been "commented out." + + + +Beginning programmers, and programmers coming to C from the BASIC +language often find using braces confusing or daunting. After all, +the same curly braces replace the RETURN statement in a subroutine +(function), the ENDIF statement in a conditional and the NEXT +statement in a FOR loop. + + + +Because the use of the curly brace is so varied, it is good +programming practice to type the closing brace immediately after +typing the opening brace when inserting a construct which requires +curly braces. Then insert some carriage returns between your braces +and begin inserting statements. Your braces, and your attitude, +will never become unbalanced. + + + +Unbalanced braces can often lead to cryptic, impenetrable compiler +errors that can sometimes be hard to track down in a large program. +Because of their varied usages, braces are also incredibly +important to the syntax of a program and moving a brace one or two +lines will often dramatically affect the meaning of a program. + + + +**The main uses of curly braces** +--------------------------------- + +Functions +--------- + +:: + + void myfunction(datatype argument){ + statements(s) + } + + + +Loops +----- + +:: + + while (boolean expression) + { + statement(s) + } + + do + { + statement(s) + } while (boolean expression); + + for (initialisation; termination condition; incrementing expr) + { + statement(s) + } + + + +Conditional statements +---------------------- + + + +:: + + if (boolean expression) + { + statement(s) + } + + else if (boolean expression) + { + statement(s) + } + else + { + statement(s) + } + + + +`Reference Home `_ + diff --git a/source/arduino/break.rst b/source/arduino/break.rst new file mode 100644 index 0000000..d951c52 --- /dev/null +++ b/source/arduino/break.rst @@ -0,0 +1,28 @@ +.. _arduino-break: + +break +===== + +**break** is used to exit from a **do**, **for**, or **while** +loop, bypassing the normal loop condition. It is also used to exit +from a **switch** statement. + + + +Example +------- + +:: + + for (x = 0; x < 255; x ++) + { + digitalWrite(PWMpin, x); + sens = analogRead(sensorPin); + if (sens > threshold){ // bail out on sensor detect + x = 0; + break; + } + delay(50); + } + + diff --git a/source/arduino/byte.rst b/source/arduino/byte.rst new file mode 100644 index 0000000..5e94bd4 --- /dev/null +++ b/source/arduino/byte.rst @@ -0,0 +1,29 @@ +.. _arduino-byte: + +byte +==== + +Description +----------- + +A byte stores an 8-bit unsigned number, from 0 to 255. + + + +Example +------- + +:: + + byte b = B10010; // "B" is the binary formatter (B10010 = 18 decimal) + + + +See also +-------- + + +- `word `_ +- `byte `_\ () +- `Variable Declaration `_ + diff --git a/source/arduino/bytecast.rst b/source/arduino/bytecast.rst new file mode 100644 index 0000000..71ab4aa --- /dev/null +++ b/source/arduino/bytecast.rst @@ -0,0 +1,41 @@ +.. _arduino-bytecast: + +byte() +====== + +Description +----------- + +Converts a value to the +`byte `_ data type. + + + +Syntax +------ + +byte(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +byte + + + +See also +-------- + + +- `byte `_ + + diff --git a/source/arduino/changes.rst b/source/arduino/changes.rst new file mode 100644 index 0000000..75cd65d --- /dev/null +++ b/source/arduino/changes.rst @@ -0,0 +1,93 @@ +.. _arduino-changes: + +Changes +======= + +This page lists major changes to the Arduino core, libraries, and +environment. For details, see the +`release notes `_. + + + +Changes in Arduino 0017 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- **Environment**: The code base for the Arduino development + environment was largely re-written to bring it back into sync with + Processing (1.0.3). The main differences include support for + multiple sketch windows open simultaneously and a dedicated window + for the serial monitor. + + +- **Icons**: The icons and about images were updated. + + +- **Arduino.app**: The Mac OS X version of Arduino is now a .app + file packaged in a .dmg. + + +- **Libraries**: Support was added for third-party libraries in + the *SKETCHBOOK*/libraries directory. This allows user-installed + libraries to persist across upgrades of the Arduino software. + + +- **Servo**: The servo library was rewritten to allow support for + up to 12 servos (on any pins) and up to 48 on the Mega. + + +- **LiquidCrystal**: The begin(), cursor(), noCursor(), blink(), + noBlink(), display(), noDisplay(), scrollDisplayLeft(), + scrollDisplayRight(), autoscroll(), noAutoscroll(), leftToRight(), + rightToLeft(), and createChar() functions were added. + + + +Changes in Arduino 0016 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- New functions for writing a string, write(str), or buffer, + write(buf, len), were added to the Print, Serial, and Ethernet + library Client and Server classes. + + + +Changes in Arduino 0015 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- Support for the Arduino Mega. + + + +Changes in Arduino 0013 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- Support for printing floats was added to the Print, Serial, and + Ethernet library Client and Server classes. + + +- The word type and word(), bitRead(), bitWrite(), bitSet(), + bitClear(), bit(), lowByte(), and highByte() functions were added. + + + +Changes in Arduino 0012 +~~~~~~~~~~~~~~~~~~~~~~~ + + +- Added the Firmata library, which provides a standard protocol + for serial communication. + + +- Added Ethernet library. + + +- Added Servo library. + + +- Added LiquidCrystal library. + + diff --git a/source/arduino/char.rst b/source/arduino/char.rst new file mode 100644 index 0000000..e783ed6 --- /dev/null +++ b/source/arduino/char.rst @@ -0,0 +1,51 @@ +.. _arduino-char: + +char +==== + +Description +----------- + +A data type that takes up 1 byte of memory that stores a character +value. Character literals are written in single quotes, like this: +'A' (for multiple characters - strings - use double quotes: +"ABC"). + + + +Characters are stored as numbers however. You can see the specific +encoding in the +`ASCII chart `_. This +means that it is possible to do arithmetic on characters, in which +the ASCII value of the character is used (e.g. 'A' + 1 has the +value 66, since the ASCII value of the capital letter A is 65). See +`Serial.println `_ reference +for more on how characters are translated to numbers. + + + +The char datatype is a signed type, meaning that it encodes numbers +from -128 to 127. For an unsigned, one-byte (8 bit) data type, use +the *byte* data type. + + + +Example +------- + +:: + + char myChar = 'A'; + char myChar = 65; // both are equivalent + + + +See also +-------- + + +- `byte `_ +- `int `_ +- `array `_ +- `Serial.println `_ + diff --git a/source/arduino/charcast.rst b/source/arduino/charcast.rst new file mode 100644 index 0000000..daa7c92 --- /dev/null +++ b/source/arduino/charcast.rst @@ -0,0 +1,41 @@ +.. _arduino-charcast: + +char() +====== + +Description +----------- + +Converts a value to the +`char `_ data type. + + + +Syntax +------ + +char(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +char + + + +See also +-------- + + +- `char `_ + + diff --git a/source/arduino/comments.rst b/source/arduino/comments.rst new file mode 100644 index 0000000..189ead5 --- /dev/null +++ b/source/arduino/comments.rst @@ -0,0 +1,45 @@ +.. _arduino-comments: + +Comments +======== + +Comments are lines in the program that are used to inform yourself +or others about the way the program works. They are ignored by the +compiler, and not exported to the processor, so they don't take up +any space on the Atmega chip. + + + +Comments only purpose are to help you understand (or remember) how +your program works or to inform others how your program works. +There are two different ways of marking a line as a comment: + + + +Example +------- + +:: + + x = 5; // This is a single line comment. Anything after the slashes is a comment + // to the end of the line + + /* this is multiline comment - use it to comment out whole blocks of code + + if (gwb == 0){ // single line comment is OK inside a multiline comment + x = 3; /* but not another multiline comment - this is invalid */ + } + // don't forget the "closing" comment - they have to be balanced! + */ + + + +**Tip** +When experimenting with code, "commenting out" parts of your +program is a convenient way to remove lines that may be buggy. This +leaves the lines in the code, but turns them into comments, so the +compiler just ignores them. This can be especially useful when +trying to locate a problem, or when a program refuses to compile +and the compiler error is cryptic or unhelpful. + + diff --git a/source/arduino/comparison.rst b/source/arduino/comparison.rst new file mode 100644 index 0000000..b87e05b --- /dev/null +++ b/source/arduino/comparison.rst @@ -0,0 +1,54 @@ +.. _arduino-comparison: + +Arduino/Processing Language Comparison +====================================== + +The Arduino language (based on Wiring) is implemented in C/C++, and +therefore has some differences from the Processing language, which +is based on Java. + + + +Arrays +~~~~~~ + +*Arduino* +*Processing* +int bar[8]; +bar[0] = 1; +int[] bar = new int[8]; +bar[0] = 1; +int foo[] = { 0, 1, 2 }; +int foo[] = { 0, 1, 2 }; +*or* +int[] foo = { 0, 1, 2 }; + + +Loops +~~~~~ + +*Arduino* +*Processing* +int i; +for (i = 0; i < 5; i++) { ... } +for (int i = 0; i < 5; i++) { ... } + + +Printing +~~~~~~~~ + +*Arduino* +*Processing* +Serial.println("hello world"); +println("hello world"); +int i = 5; +Serial.println(i); +int i = 5; +println(i); +int i = 5; +Serial.print("i = "); +Serial.print(i); +Serial.println(); +int i = 5; +println("i = " + i); + diff --git a/source/arduino/const.rst b/source/arduino/const.rst new file mode 100644 index 0000000..295b817 --- /dev/null +++ b/source/arduino/const.rst @@ -0,0 +1,55 @@ +.. _arduino-const: + +const keyword +============= + +The **const** keyword stands for constant. It is a variable +*qualifier* that modifies the behavior of the variable, making a +variable "*read-only*". This means that the variable can be used +just as any other variable of its type, but its value cannot be +changed. You will get a compiler error if you try to assign a value +to a **const** variable. + + + +Constants defined with the *const* keyword obey the rules of +*`variable scoping `_* that +govern other variables. This, and the pitfalls of using*#define*, +makes the *const* keyword a superior method for defining constants +and is preferred over using +*`#define `_*. + + + +Example +------- + +:: + + const float pi = 3.14; + float x; + + // .... + + x = pi * 2; // it's fine to use const's in math + + pi = 7; // illegal - you can't write to (modify) a constant + + +**#define** or **const** +------------------------ + +You can use either **const** or **#define** for creating numeric or +string constants. For +`arrays `_, you will need to +use **const**. In general *const* is preferred over *#define* for +defining constants. + + + +See also: + + +- `#define `_ +- `volatile `_ + diff --git a/source/arduino/constants.rst b/source/arduino/constants.rst new file mode 100644 index 0000000..49f3933 --- /dev/null +++ b/source/arduino/constants.rst @@ -0,0 +1,144 @@ +.. _arduino-constants: + +constants +========= + +Constants are predefined variables in the Arduino language. They +are used to make the programs easier to read. We classify constants +in groups. + + + +Defining Logical Levels, true and false (Boolean Constants) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two constants used to represent truth and falsity in the +Arduino language: **true**, and **false**. + + + +false +----- + +false is the easier of the two to define. false is defined as 0 +(zero). + + + +true +---- + +true is often said to be defined as 1, which is correct, but true +has a wider definition. Any integer which is *non-zero* is TRUE, in +a Boolean sense. So -1, 2 and -200 are all defined as true, too, in +a Boolean sense. + + + +Note that the *true* and *false* constants are typed in lowercase +unlike HIGH, LOW, INPUT, & OUTPUT. + + + +Defining Pin Levels, HIGH and LOW +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When reading or writing to a digital pin there are only two +possible values a pin can take/be-set-to: **HIGH** and **LOW**. + + + +**HIGH** + + + +The meaning of HIGH (in reference to a pin) is somewhat different +depending on whether a pin is set to an INPUT or OUTPUT. When a pin +is configured as an INPUT with pinMode, and read with digitalRead, +the microcontroller will report HIGH if a voltage of 3 volts or +more is present at the pin. + + + +A pin may also be configured as an INPUT with pinMode, and +subsequently made HIGH with digitalWrite, this will set the +internal 20K pullup resistors, which will *steer* the input pin to +a HIGH reading unless it is pulled LOW by external circuitry. + + + +When a pin is configured to OUTPUT with pinMode, and set to HIGH +with digitalWrite, the pin is at 5 volts. In this state it can +*source* current, e.g. light an LED that is connected through a +series resistor to ground, or to another pin configured as an +output, and set to LOW. + + + +**LOW** + + + +The meaning of LOW also has a different meaning depending on +whether a pin is set to INPUT or OUTPUT. When a pin is configured +as an INPUT with pinMode, and read with digitalRead, the +microcontroller will report LOW if a voltage of 2 volts or less is +present at the pin. + + + +When a pin is configured to OUTPUT with pinMode, and set to LOW +with digitalWrite, the pin is at 0 volts. In this state it can +*sink* current, e.g. light an LED that is connected through a +series resistor to, +5 volts, or to another pin configured as an +output, and set to HIGH. + + + +Defining Digital Pins, INPUT and OUTPUT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Digital pins can be used either as **INPUT** or **OUTPUT**. +Changing a pin from INPUT TO OUTPUT with pinMode() drastically +changes the electrical behavior of the pin. + + + +Pins Configured as Inputs +------------------------- + +Arduino (Atmega) pins configured as **INPUT** with pinMode() are +said to be in a high-impedance state. One way of explaining this is +that pins configured as INPUT make extremely small demands on the +circuit that they are sampling, say equivalent to a series resistor +of 100 Megohms in front of the pin. This makes them useful for +reading a sensor, but not powering an LED. + + + +Pins Configured as Outputs +-------------------------- + +Pins configured as **OUTPUT** with pinMode() are said to be in a +low-impedance state. This means that they can provide a substantial +amount of current to other circuits. Atmega pins can source +(provide positive current) or sink (provide negative current) up to +40 mA (milliamps) of current to other devices/circuits. This makes +them useful for powering LED's but useless for reading sensors. +Pins configured as outputs can also be damaged or destroyed if +short circuited to either ground or 5 volt power rails. The amount +of current provided by an Atmega pin is also not enough to power +most relays or motors, and some interface circuitry will be +required. + + + +See also +-------- + + +- `pinMode() `_ +- `Integer Constants `_ +- `boolean variables `_ + + diff --git a/source/arduino/constrain.rst b/source/arduino/constrain.rst new file mode 100644 index 0000000..2769219 --- /dev/null +++ b/source/arduino/constrain.rst @@ -0,0 +1,60 @@ +.. _arduino-constrain: + +constrain(x, a, b) +================== + +Description +----------- + +Constrains a number to be within a range. + + + +Parameters +---------- + +x: the number to constrain, all data types + + + +a: the lower end of the range, all data types + + + +b: the upper end of the range, all data types + + + +Returns +------- + +**x**: if **x** is between **a** and **b** + + + +**a**: if **x** is less than **a** + + + +**b**: if **x** is greater than **b** + + + +Example +------- + +:: + + sensVal = constrain(sensVal, 10, 150); + // limits range of sensor values to between 10 and 150 + + + +See also +-------- + + +- `min `_\ () +- `max `_\ () + + diff --git a/source/arduino/continue.rst b/source/arduino/continue.rst new file mode 100644 index 0000000..66c7e60 --- /dev/null +++ b/source/arduino/continue.rst @@ -0,0 +1,29 @@ +.. _arduino-continue: + +continue +======== + +The continue statement skips the rest of the current iteration of a +loop (**do**, **for**, or **while**). It continues by checking the +conditional expression of the loop, and proceeding with any +subsequent iterations. + + + +Example +------- + +:: + + + for (x = 0; x < 255; x ++) + { + if (x > 40 && x < 120){ // create jump in values + continue; + } + + digitalWrite(PWMpin, x); + delay(50); + } + + diff --git a/source/arduino/cos.rst b/source/arduino/cos.rst new file mode 100644 index 0000000..7fed4bb --- /dev/null +++ b/source/arduino/cos.rst @@ -0,0 +1,33 @@ +.. _arduino-cos: + +cos(rad) +======== + +Description +----------- + +Calculates the cos of an angle (in radians). The result will be +between -1 and 1. + +Parameters +---------- + +rad: the angle in radians (*float*) + + + +Returns +------- + +The cos of the angle ("double") + + + +See also +-------- + + +- `sin `_\ () +- `tan `_\ () +- `float `_ +- `double `_ diff --git a/source/arduino/define.rst b/source/arduino/define.rst new file mode 100644 index 0000000..6190cb9 --- /dev/null +++ b/source/arduino/define.rst @@ -0,0 +1,83 @@ +.. _arduino-define: + +Define +====== + +``#define`` is a useful C component that allows the programmer to +give a name to a constant value before the program is compiled. +Defined constants in arduino don't take up any program memory space +on the chip. The compiler will replace references to these +constants with the defined value at compile time. + + + +This can have some unwanted side effects though, if for example, a +constant name that had been #defined is included in some other +constant or variable name. In that case the text would be replaced +by the #defined number (or text). + + + +In general, the *`const `_* +keyword is preferred for defining constants and should be used +instead of #define. + + + +Arduino defines have the same syntax as C defines: + + + +Syntax +------ + +``#define constantName value`` + + + +Note that the # is necessary. + + + +Example +------- + +:: + + #define ledPin 3 + // The compiler will replace any mention of ledPin with the value 3 at compile time. + + + +Tip +--- + +There is no semicolon after the #define statement. If you include +one, the compiler will throw cryptic errors further down the page. + + + +:: + + #define ledPin 3; // this is an error + + + +Similarly, including an equal sign after the #define statement will +also generate a cryptic compiler error further down the page. + + + +:: + + #define ledPin = 3 // this is also an error + + + +See +--- + + +- `const `_ +- `Constants `_ + diff --git a/source/arduino/delay.rst b/source/arduino/delay.rst new file mode 100644 index 0000000..973c75b --- /dev/null +++ b/source/arduino/delay.rst @@ -0,0 +1,94 @@ +.. _arduino-delay: + +delay() +======= + +Description +----------- + +Pauses the program for the amount of time (in miliseconds) +specified as parameter. (There are 1000 milliseconds in a second.) + + + +Syntax +------ + +delay(ms) + + + +Parameters +---------- + +ms: the number of milliseconds to pause (*unsigned long*) + + + +Returns +------- + +nothing + + + +Example +------- + +:: + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Caveat +------ + +While it is easy to create a blinking LED with the delay() +function, and many sketches use short delays for such tasks as +switch debouncing, the use of delay() in a sketch has significant +drawbacks. No other reading of sensors, mathematical calculations, +or pin manipulation can go on during the delay function, so in +effect, it brings most other activity to a halt. For alternative +approaches to controlling timing see the +`millis() `_ function and +the sketch sited below. More knowledgeable programmers usually +avoid the use of delay() for timing of events longer than 10's of +milliseconds unless the Arduino sketch is very simple. + + + +Certain things *do* go on while the delay() function is controlling +the Atmega chip however, because the delay function does not +disable interrupts. Serial communication that appears at the RX pin +is recorded, PWM +(`analogWrite `_) +values and pin states are maintained, and +`interrupts `_ will +work as they should. + + + +See also +-------- + + +- `millis `_\ () +- `micros `_\ () +- `delayMicroseconds `_\ () +- `Blink Without Delay `_ + example + diff --git a/source/arduino/delaymicroseconds.rst b/source/arduino/delaymicroseconds.rst new file mode 100644 index 0000000..0feaba7 --- /dev/null +++ b/source/arduino/delaymicroseconds.rst @@ -0,0 +1,93 @@ +.. _arduino-delaymicroseconds: + +delayMicroseconds() +=================== + +Description +----------- + +Pauses the program for the amount of time (in microseconds) +specified as parameter. There are a thousand microseconds in a +millisecond, and a million microseconds in a second. + + + +Currently, the largest value that will produce an accurate delay is +16383. This could change in future Arduino releases. For delays +longer than a few thousand microseconds, you should use delay() +instead. + + + +Syntax +------ + +delayMicroseconds(us) + + + +Parameters +---------- + +us: the number of microseconds to pause (*unsigned int*) + + + +Returns +------- + +None + + + +Example +------- + +:: + + + int outPin = 8; // digital pin 8 + + void setup() + { + pinMode(outPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(outPin, HIGH); // sets the pin on + delayMicroseconds(50); // pauses for 50 microseconds + digitalWrite(outPin, LOW); // sets the pin off + delayMicroseconds(50); // pauses for 50 microseconds + } + + + +configures pin number 8 to work as an output pin. It sends a train +of pulses with 100 microseconds period. + + + +Caveats and Known Issues +------------------------ + +This function works very accurately in the range 3 microseconds and +up. We cannot assure that delayMicroseconds will perform precisely +for smaller delay-times. + + + +As of Arduino 0018, delayMicroseconds() no longer disables +interrupts. + + + +See also +-------- + + +- `millis `_\ () +- `micros `_\ () +- `delay `_\ () + + diff --git a/source/arduino/detachinterrupt.rst b/source/arduino/detachinterrupt.rst new file mode 100644 index 0000000..f0342df --- /dev/null +++ b/source/arduino/detachinterrupt.rst @@ -0,0 +1,26 @@ +.. _arduino-detachinterrupt: + +detachInterrupt(interrupt) +========================== + +Description +----------- + +Turns off the given interrupt. + + + +Parameters +---------- + +interrupt: the number of interrupt to disable (0 or 1). + + + +See also +-------- + + +- `attachInterrupt `_\ () + + diff --git a/source/arduino/digitalread.rst b/source/arduino/digitalread.rst new file mode 100644 index 0000000..ec64fb0 --- /dev/null +++ b/source/arduino/digitalread.rst @@ -0,0 +1,86 @@ +.. _arduino-digitalread: + +digitalRead() +============= + +Description +----------- + +Reads the value from a specified digital pin, either +`HIGH `_ or +`LOW `_. + + + +Syntax +------ + +digitalRead(pin) + + + +Parameters +---------- + +pin: the number of the digital pin you want to read (*int*) + + + +Returns +------- + +`HIGH `_ or +`LOW `_ + + + +Example +------- + +:: + + + int ledPin = 13; // LED connected to digital pin 13 + int inPin = 7; // pushbutton connected to digital pin 7 + int val = 0; // variable to store the read value + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin 13 as output + pinMode(inPin, INPUT); // sets the digital pin 7 as input + } + + void loop() + { + val = digitalRead(inPin); // read the input pin + digitalWrite(ledPin, val); // sets the LED to the button's value + } + + + +Sets pin 13 to the same value as the pin 7, which is an input. + + + +Note +---- + +If the pin isn't connected to anything, digitalRead() can return +either HIGH or LOW (and this can change randomly). + + + +The analog input pins can be used as digital pins, referred to as +A0, A1, etc. + + + +See also +-------- + + +- `pinMode `_\ () +- `digitalWrite `_\ () +- `Tutorial: Digital Pins `_ + + diff --git a/source/arduino/digitalwrite.rst b/source/arduino/digitalwrite.rst new file mode 100644 index 0000000..82e1813 --- /dev/null +++ b/source/arduino/digitalwrite.rst @@ -0,0 +1,113 @@ +.. _arduino-digitalwrite: + +digitalWrite() +============== + +Description +----------- + +Write a `HIGH `_ or a +`LOW `_ value to a +digital pin. + + + +If the pin has been configured as an OUTPUT with +`pinMode `_\ (), its voltage +will be set to the corresponding value: 5V (or 3.3V on 3.3V boards) +for HIGH, 0V (ground) for LOW. + + + +If the pin is configured as an INPUT, writing a HIGH value with +digitalWrite() will enable an internal 20K pullup resistor (see the +`tutorial on digital pins `_). +Writing LOW will disable the pullup. The pullup resistor is enough +to light an LED dimly, so if LEDs appear to work, but very dimly, +this is a likely cause. The remedy is to set the pin to an output +with the pinMode() function. + + + +**NOTE:** Digital pin 13 is harder to use as a digital input than +the other digital pins because it has an LED and resistor attached +to it that's soldered to the board on most boards. If you enable +its internal 20k pull-up resistor, it will hang at around 1.7 V +instead of the expected 5V because the onboard LED and series +resistor pull the voltage level down, meaning it always returns +LOW. If you must use pin 13 as a digital input, use an external +pull down resistor. + + + +Syntax +------ + +digitalWrite(pin, value) + + + +Parameters +---------- + +pin: the pin number + + + +value: `HIGH `_ or +`LOW `_ + + + +Returns +------- + +none + + + +Example +------- + +:: + + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Sets pin 13 to HIGH, makes a one-second-long delay, and sets the +pin back to LOW. + + + +Note +---- + +The analog input pins can be used as digital pins, referred to as +A0, A1, etc. + + + +See also +-------- + + +- `pinMode `_\ () +- `digitalRead `_\ () +- `Tutorial: Digital Pins `_ + + diff --git a/source/arduino/double.rst b/source/arduino/double.rst new file mode 100644 index 0000000..4e7f20c --- /dev/null +++ b/source/arduino/double.rst @@ -0,0 +1,32 @@ +.. _arduino-double: + +double +====== + +Desciption +---------- + +Double precision floating point number. Occupies 4 bytes. + + + +The double implementation on the Arduino is currently exactly the +same as the float, with no gain in precision. + + + +Tip +--- + +Users who borrow code from other sources that includes double +variables may wish to examine the code to see if the implied +precision is different from that actually achieved on the Arduino. + + + +See: +---- + + +- `float `_ + diff --git a/source/arduino/dowhile.rst b/source/arduino/dowhile.rst new file mode 100644 index 0000000..48fe75b --- /dev/null +++ b/source/arduino/dowhile.rst @@ -0,0 +1,33 @@ +.. _arduino-dowhile: + +do - while +========== + +The **do** loop works in the same manner as the **while** loop, +with the exception that the condition is tested at the end of the +loop, so the **do** loop will *always* run at least once. + + + +:: + + do + { + // statement block + } while (test condition); + + + +Example +------- + +:: + + do + { + delay(50); // wait for sensors to stabilize + x = readSensors(); // check the sensors + + } while (x < 100); + + diff --git a/source/arduino/else.rst b/source/arduino/else.rst new file mode 100644 index 0000000..f278a0d --- /dev/null +++ b/source/arduino/else.rst @@ -0,0 +1,73 @@ +.. _arduino-else: + +if / else +========= + +**if/else** allows greater control over the flow of code than the +basic **if** statement, by allowing multiple tests to be grouped +together. For example, an analog input could be tested and one +action taken if the input was less than 500, and another action +taken if the input was 500 or greater. The code would look like +this: + + + +:: + + if (pinFiveInput < 500) + { + // action A + } + else + { + // action B + } + + + +**else** can proceed another **if** test, so that multiple, +mutually exclusive tests can be run at the same time. + + + +Each test will proceed to the next one until a true test is +encountered. When a true test is found, its associated block of +code is run, and the program then skips to the line following the +entire if/else construction. If no test proves to be true, the +default **else** block is executed, if one is present, and sets the +default behavior. + + + +Note that an **else if** block may be used with or without a +terminating **else** block and vice versa. An unlimited number of +such **else if** branches is allowed. + + + +:: + + if (pinFiveInput < 500) + { + // do Thing A + } + else if (pinFiveInput >= 1000) + { + // do Thing B + } + else + { + // do Thing C + } + +Another way to express branching, mutually exclusive tests, is with +the `switch case `_ +statement. + + + +See also: +--------- + +`switch case `_ + diff --git a/source/arduino/float.rst b/source/arduino/float.rst new file mode 100644 index 0000000..2f83a67 --- /dev/null +++ b/source/arduino/float.rst @@ -0,0 +1,88 @@ +.. _arduino-float: + +float +===== + +Description +----------- + +Datatype for floating-point numbers, a number that has a decimal +point. Floating-point numbers are often used to approximate analog +and continuous values because they have greater resolution than +integers. Floating-point numbers can be as large as 3.4028235E+38 +and as low as -3.4028235E+38. They are stored as 32 bits (4 bytes) +of information. + + + +Floats have only 6-7 decimal digits of precision. That means the +total number of digits, not the number to the right of the decimal +point. Unlike other platforms, where you can get more precision by +using a double (e.g. up to 15 digits), on the Arduino, double is +the same size as float. + + + +Floating point numbers are not exact, and may yield strange results +when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You +should instead check that the absolute value of the difference +between the numbers is less than some small number. + + + +Floating point math is also much slower than integer math in +performing calculations, so should be avoided if, for example, a +loop has to run at top speed for a critical timing function. +Programmers often go to some lengths to convert floating point +calculations to integer math to increase speed. + + + +Examples +-------- + +:: + + float myfloat; + float sensorCalbrate = 1.117; + + + +Syntax +------ + +:: + + float var = val; + + + + +- var - your float variable name +- val - the value you assign to that variable + + + +Example Code +------------ + +:: + + int x; + int y; + float z; + + x = 1; + y = x / 2; // y now contains 0, ints can't hold fractions + z = (float)x / 2.0; // z now contains .5 (you have to use 2.0, not 2) + + + +See Also +-------- + + +- `int `_ +- `double `_ +- `Variable Declaration `_ + diff --git a/source/arduino/floatcast.rst b/source/arduino/floatcast.rst new file mode 100644 index 0000000..6b85727 --- /dev/null +++ b/source/arduino/floatcast.rst @@ -0,0 +1,51 @@ +.. _arduino-floatcast: + +float() +======= + +Description +----------- + +Converts a value to the +`float `_ data type. + + + +Syntax +------ + +float(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +float + + + +Notes +----- + +See the reference for +`float `_ for details about +the precision and limitations of floating point numbers on +Arduino. + + + +See also +-------- + + +- `float `_ + + diff --git a/source/arduino/for.rst b/source/arduino/for.rst new file mode 100644 index 0000000..b7e2e95 --- /dev/null +++ b/source/arduino/for.rst @@ -0,0 +1,117 @@ +.. _arduino-for: + +for statements +============== + +Desciption +---------- + +The **for** statement is used to repeat a block of statements +enclosed in curly braces. An increment counter is usually used to +increment and terminate the loop. The **for** statement is useful +for any repetitive operation, and is often used in combination with +arrays to operate on collections of data/pins. + + + +There are three parts to the **for** loop header: + + + +``for (initialization; condition; increment) {`` + + + +``//statement(s);`` + + + +``}`` + +|image0| + + +The **initialization** happens first and exactly once. Each time +through the loop, the **condition** is tested; if it's true, the +statement block, and the **increment** is executed, then the +**condition** is tested again. When the **condition** becomes +false, the loop ends. + + + +Example +------- + +:: + + // Dim an LED using a PWM pin + int PWMpin = 10; // LED in series with 470 ohm resistor on pin 10 + + void setup() + { + // no setup needed + } + + void loop() + { + for (int i=0; i <= 255; i++){ + analogWrite(PWMpin, i); + delay(10); + } + } + + + +Coding Tips +----------- + +The C **for** loop is much more flexible than **for** loops found +in some other computer languages, including BASIC. Any or all of +the three header elements may be omitted, although the semicolons +are required. Also the statements for initialization, condition, +and increment can be any valid C statements with unrelated +variables, and use any C datatypes including floats. These types of +unusual **for** statements may provide solutions to some rare +programming problems. + + + +For example, using a multiplication in the increment line will +generate a logarithmic progression: + +:: + + for(int x = 2; x < 100; x = x * 1.5){ + println(x); + } + + + +Generates: 2,3,4,6,9,13,19,28,42,63,94 + + + +Another example, fade an LED up and down with one **for** loop: + + + +:: + + void loop() + { + int x = 1; + for (int i = 0; i > -1; i = i + x){ + analogWrite(PWMpin, i); + if (i = 255) x = -1; // switch direction at peak + delay(10); + } + } + + + +See also +-------- + + +- `while `_ + diff --git a/source/arduino/fpconstants.rst b/source/arduino/fpconstants.rst new file mode 100644 index 0000000..284342b --- /dev/null +++ b/source/arduino/fpconstants.rst @@ -0,0 +1,36 @@ +.. _arduino-fpconstants: + +floating point constants +======================== + +Similar to integer constants, floating point constants are used to +make code more readable. Floating point constants are swapped at +compile time for the value to which the expression evaluates. + + + +Examples: + + + +``n = .005;`` + + + +Floating point constants can also be expressed in a variety of +scientific notation. 'E' and 'e' are both accepted as valid +exponent indicators. + + + +:: + + + floating-point evaluates to: also evaluates to: + constant + + 10.0 10 + 2.34E5 2.34 * 10^5 234000 + 67e-12 67.0 * 10^-12 .000000000067 + + diff --git a/source/arduino/goto.rst b/source/arduino/goto.rst new file mode 100644 index 0000000..1fcceb7 --- /dev/null +++ b/source/arduino/goto.rst @@ -0,0 +1,55 @@ +.. _arduino-goto: + +goto +==== + +Transfers program flow to a labeled point in the program + + + +Syntax +------ + +label: + + + +goto label; // sends program flow to the label + + + +Tip +--- + +The use of *goto* is discouraged in C programming, and some authors +of C programming books claim that the *goto* statement is never +necessary, but used judiciously, it can simplify certain programs. +The reason that many programmers frown upon the use of *goto* is +that with the unrestrained use of *goto* statements, it is easy to +create a program with undefined program flow, which can never be +debugged. + + + +With that said, there are instances where a goto statement can come +in handy, and simplify coding. One of these situations is to break +out of deeply nested *for* loops, or *if* logic blocks, on a +certain condition. + + + +Example +------- + +:: + + for(byte r = 0; r < 255; r++){ + for(byte g = 255; g > -1; g--){ + for(byte b = 0; b < 255; b++){ + if (analogRead(0) > 250){ goto bailout;} + // more statements ... + } + } + } + bailout: + diff --git a/source/arduino/highbyte.rst b/source/arduino/highbyte.rst new file mode 100644 index 0000000..dc6a1d6 --- /dev/null +++ b/source/arduino/highbyte.rst @@ -0,0 +1,42 @@ +.. _arduino-highbyte: + +highByte() +========== + +Description +----------- + +Extracts the high-order (leftmost) byte of a word (or the second +lowest byte of a larger data type). + + + +Syntax +------ + +highByte(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +byte + + + +See also +-------- + + +- `lowByte `_\ () +- `word `_\ () + + diff --git a/source/arduino/if.rst b/source/arduino/if.rst new file mode 100644 index 0000000..d75f6d3 --- /dev/null +++ b/source/arduino/if.rst @@ -0,0 +1,95 @@ +.. _arduino-if: + +if (conditional) and ==, !=, <, > (comparison operators) +======================================================== + +**``if``**, which is used in conjunction with a comparison +operator, tests whether a certain condition has been reached, such +as an input being above a certain number. The format for an if test +is: + + + +:: + + if (someVariable > 50) + { + // do something here + } + + + +The program tests to see if someVariable is greater than 50. If it +is, the program takes a particular action. Put another way, if the +statement in parentheses is true, the statements inside the +brackets are run. If not, the program skips over the code. + + + +The brackets may be omitted after an *if* statement. If this is +done, the next line (defined by the semicolon) becomes the only +conditional statement. + +:: + + + if (x > 120) digitalWrite(LEDpin, HIGH); + + if (x > 120) + digitalWrite(LEDpin, HIGH); + + if (x > 120){ digitalWrite(LEDpin, HIGH); } + + if (x > 120){ + digitalWrite(LEDpin1, HIGH); + digitalWrite(LEDpin2, HIGH); + } // all are correct + + + +The statements being evaluated inside the parentheses require the +use of one or more operators: + + + +Comparison Operators: +~~~~~~~~~~~~~~~~~~~~~ + +:: + + x == y (x is equal to y) + x != y (x is not equal to y) + x < y (x is less than y) + x > y (x is greater than y) + x <= y (x is less than or equal to y) + x >= y (x is greater than or equal to y) + + + +Warning: +-------- + +Beware of accidentally using the single equal sign +(e.g.``if (x = 10)`` ). The single equal sign is the assignment +operator, and sets x to 10 (puts the value 10 into the variable x). +Instead use the double equal sign (e.g.``if (x == 10)``), which is +the comparison operator, and tests *whether* x is equal to 10 or +not. The latter statement is only true if x equals 10, but the +former statement will always be true. + + + +This is because C evaluates the statement ``if (x=10)`` as follows: +10 is assigned to x (remember that the single equal sign is the +`assignment operator `_), +so x now contains 10. Then the 'if' conditional evaluates 10, which +always evaluates to TRUE, since any non-zero number evaluates to +TRUE. Consequently, ``if (x = 10)`` will always evaluate to TRUE, +which is not the desired result when using an 'if' statement. +Additionally, the variable x will be set to 10, which is also not a +desired action. + + + +**if** can also be part of a branching control structure using the +`if...else `_] construction. diff --git a/source/arduino/include.rst b/source/arduino/include.rst new file mode 100644 index 0000000..6d53801 --- /dev/null +++ b/source/arduino/include.rst @@ -0,0 +1,42 @@ +.. _arduino-include: + +#include +======== + +**#include** is used to include outside libraries in your sketch. +This gives the programmer access to a large group of standard C +libraries (groups of pre-made functions), and also libraries +written especially for Arduino. + + + +The main reference page for AVR C libraries (AVR is a reference to +the Atmel chips on which the Arduino is based) is +`here. `_ + + + +Note that **#include**, similar to **#define**, has no semicolon +terminator, and the compiler will yield cryptic error messages if +you add one. + + + +Example +------- + +This example includes a library that is used to put data into the +program space *flash* instead of *ram*. This saves the ram space +for dynamic memory needs and makes large lookup tables more +practical. + + + +:: + + #include + + prog_uint16_t myConstants[] PROGMEM = {0, 21140, 702 , 9128, 0, 25764, 8456, + 0,0,0,0,0,0,0,0,29810,8968,29762,29762,4500}; + + diff --git a/source/arduino/increment.rst b/source/arduino/increment.rst new file mode 100644 index 0000000..f9e87c9 --- /dev/null +++ b/source/arduino/increment.rst @@ -0,0 +1,58 @@ +.. _arduino-increment: + +++ (increment) / -- (decrement) +=============================== + +Description +----------- + +Increment or decrement a variable + + + +Syntax +------ + +:: + + x++; // increment x by one and returns the old value of x + ++x; // increment x by one and returns the new value of x + + x-- ; // decrement x by one and returns the old value of x + --x ; // decrement x by one and returns the new value of x + + + +Parameters +---------- + +x: an integer or long (possibly unsigned) + + + +Returns +------- + +The original or newly incremented / decremented value of the +variable. + + + +Examples +-------- + +:: + + x = 2; + y = ++x; // x now contains 3, y contains 3 + y = x--; // x contains 2 again, y still contains 3 + + + +See also +-------- + +`+= `_ +`-= `_ + + diff --git a/source/arduino/incrementcompound.rst b/source/arduino/incrementcompound.rst new file mode 100644 index 0000000..0005fbc --- /dev/null +++ b/source/arduino/incrementcompound.rst @@ -0,0 +1,49 @@ +.. _arduino-incrementcompound: + ++= , -= , \*= , /= +================== + +Description +----------- + +Perform a mathematical operation on a variable with another +constant or variable. The += (et al) operators are just a +convenient shorthand for the expanded syntax, listed below. + + + +Syntax +------ + +:: + + x += y; // equivalent to the expression x = x + y; + x -= y; // equivalent to the expression x = x - y; + x *= y; // equivalent to the expression x = x * y; + x /= y; // equivalent to the expression x = x / y; + + + +Parameters +---------- + +x: any variable type + + + +y: any variable type or constant + + + +Examples +-------- + +:: + + x = 2; + x += 4; // x now contains 6 + x -= 3; // x now contains 3 + x *= 10; // x now contains 30 + x /= 2; // x now contains 15 + + diff --git a/source/arduino/int.rst b/source/arduino/int.rst new file mode 100644 index 0000000..2bb3bef --- /dev/null +++ b/source/arduino/int.rst @@ -0,0 +1,84 @@ +.. _arduino-int: + +int +=== + +Description +----------- + +Integers are your primary datatype for number storage, and store a +2 byte value. This yields a range of -32,768 to 32,767 (minimum +value of -2^15 and a maximum value of (2^15) - 1). + + + +Int's store negative numbers with a technique called +`2's complement math. `_ +The highest bit, sometimes refered to as the "sign" bit, flags the +number as a negative number. The rest of the bits are inverted and +1 is added. + + + +The Arduino takes care of dealing with negative numbers for you, so +that arithmetic operations work transparently in the expected +manner. There can be an unexpected complication in dealing with the +`bitshift right operator (>>) `_ +however. + + + +Example +------- + +:: + + int ledPin = 13; + + + +Syntax +------ + +:: + + int var = val; + + + + +- var - your int variable name +- val - the value you assign to that variable + + + +Coding Tip +---------- + +When variables are made to exceed their maximum capacity they "roll +over" back to their minimum capacitiy, note that this happens in +both directions. + + + +:: + + int x + x = -32,768; + x = x - 1; // x now contains 32,767 - rolls over in neg. direction + + x = 32,767; + x = x + 1; // x now contains -32,768 - rolls over + + + +See Also +-------- + + +- `byte `_ +- `unsigned int `_ +- `long `_ +- `unsigned long `_ +- `Integer Constants `_ +- `Variable Declaration `_ diff --git a/source/arduino/intcast.rst b/source/arduino/intcast.rst new file mode 100644 index 0000000..d6bcca4 --- /dev/null +++ b/source/arduino/intcast.rst @@ -0,0 +1,41 @@ +.. _arduino-intcast: + +int() +===== + +Description +----------- + +Converts a value to the `int `_ +data type. + + + +Syntax +------ + +int(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +int + + + +See also +-------- + + +- `int `_ + + diff --git a/source/arduino/integerconstants.rst b/source/arduino/integerconstants.rst new file mode 100644 index 0000000..d60ed24 --- /dev/null +++ b/source/arduino/integerconstants.rst @@ -0,0 +1,130 @@ +.. _arduino-integerconstants: + +Integer Constants +================= + +Integer constants are numbers used directly in a sketch, like +``123``. By default, these numbers are treated as +`int `_'s but you can change +this with the U and L modifiers (see below). + + + +Normally, integer constants are treated as base 10 (decimal) +integers, but special notation (formatters) may be used to enter +numbers in other bases. + + + +:: + + Base Example Formatter Comment + + 10 (decimal) 123 none + + 2 (binary) B1111011 leading 'B' only works with 8 bit values (0 to 255) + characters 0-1 valid + + 8 (octal) 0173 leading "0" characters 0-7 valid + + 16 (hexadecimal) 0x7B leading "0x" characters 0-9, A-F, a-f valid + + + +**Decimal** is base 10. This is the common-sense math with which +you are acquainted. Constants without other prefixes are assumed to +be in decimal format. + + + +Example: +:: + + 101 // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) + +**Binary** is base two. Only characters 0 and 1 are valid. + + + +Example: +:: + + B101 // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) + +The binary formatter only works on bytes (8 bits) between 0 (B0) +and 255 (B11111111). If it is convenient to input an int (16 bits) +in binary form you can do it a two-step procedure such as: + + + +:: + + myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte + + + +**Octal** is base eight. Only characters 0 through 7 are valid. +Octal values are indicated by the prefix "0" + + + +Example: + +:: + + 0101 // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) + +Warning +It is possible to generate a hard-to-find bug by (unintentionally) +including a leading zero before a constant and having the compiler +unintentionally interpret your constant as octal. +**Hexadecimal (or hex)** is base sixteen. Valid characters are 0 +through 9 and letters A through F; A has the value 10, B is 11, up +to F, which is 15. Hex values are indicated by the prefix "0x". +Note that A-F may be syted in upper or lower case (a-f). + + + +Example: + +:: + + 0x101 // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) + + + +U & L formatters +---------------- + +By default, an integer constant is treated as an +`int `_ with the attendant +limitations in values. To specify an integer constant with another +data type, follow it with: + + + + +- a 'u' or 'U' to force the constant into an unsigned data format. + Example: ``33u`` +- a 'l' or 'L' to force the constant into a long data format. + Example: ``100000L`` +- a 'ul' or 'UL' to force the constant into an unsigned long + constant. Example: ``32767ul`` + + + + + +See also +-------- + + +- `constants `_ +- `#define `_ +- `byte `_ +- `int `_ +- `unsigned int `_ +- `long `_ +- `unsigned long `_ + + diff --git a/source/arduino/interrupts.rst b/source/arduino/interrupts.rst new file mode 100644 index 0000000..282362b --- /dev/null +++ b/source/arduino/interrupts.rst @@ -0,0 +1,59 @@ +.. _arduino-interrupts: + +interrupts() +============ + +Description +----------- + +Re-enables interrupts (after they've been disabled by +`noInterrupts `_\ ()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None + + + +Returns +------- + +None + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `noInterrupts `_\ () +- `attachInterrupt `_\ () +- `detachInterrupt `_\ () + + diff --git a/source/arduino/long.rst b/source/arduino/long.rst new file mode 100644 index 0000000..3d59896 --- /dev/null +++ b/source/arduino/long.rst @@ -0,0 +1,50 @@ +.. _arduino-long: + +long +==== + +Description +----------- + +Long variables are extended size variables for number storage, and +store 32 bits (4 bytes), from -2,147,483,648 to 2,147,483,647. + + + +Example +------- + + + +:: + + long speedOfLight = 186000L; // see Integer Constants for explanation of the 'L' + + + +Syntax +------ + +:: + + long var = val; + + + + +- var - the long variable name +- val - the value assigned to the variable + + + +See Also +-------- + + +- `byte `_ +- `int `_ +- `unsigned int `_ +- `unsigned long `_ +- `Integer Constants `_ +- `Variable Declaration `_ + diff --git a/source/arduino/longcast.rst b/source/arduino/longcast.rst new file mode 100644 index 0000000..9f31443 --- /dev/null +++ b/source/arduino/longcast.rst @@ -0,0 +1,41 @@ +.. _arduino-longcast: + +long() +====== + +Description +----------- + +Converts a value to the +`long `_ data type. + + + +Syntax +------ + +long(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +long + + + +See also +-------- + + +- `long `_ + + diff --git a/source/arduino/loop.rst b/source/arduino/loop.rst new file mode 100644 index 0000000..165b7b0 --- /dev/null +++ b/source/arduino/loop.rst @@ -0,0 +1,39 @@ +.. _arduino-loop: + +loop() +====== + +After creating a setup() function, which initializes and sets the +initial values, the loop() function does precisely what its name +suggests, and loops consecutively, allowing your program to change +and respond. Use it to actively control the Arduino board. + + + +Example +~~~~~~~ + +:: + + + int buttonPin = 3; + + // setup initializes serial and the button pin + void setup() + { + beginSerial(9600); + pinMode(buttonPin, INPUT); + } + + // loop checks the button pin each time, + // and will send serial if it is pressed + void loop() + { + if (digitalRead(buttonPin) == HIGH) + serialWrite('H'); + else + serialWrite('L'); + + delay(1000); + } + diff --git a/source/arduino/lowbyte.rst b/source/arduino/lowbyte.rst new file mode 100644 index 0000000..d69f66a --- /dev/null +++ b/source/arduino/lowbyte.rst @@ -0,0 +1,42 @@ +.. _arduino-lowbyte: + +lowByte() +========= + +Description +----------- + +Extracts the low-order (rightmost) byte of a variable (e.g. a +word). + + + +Syntax +------ + +lowByte(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +byte + + + +See also +-------- + + +- `highByte `_\ () +- `word `_\ () + + diff --git a/source/arduino/map.rst b/source/arduino/map.rst new file mode 100644 index 0000000..65647fa --- /dev/null +++ b/source/arduino/map.rst @@ -0,0 +1,119 @@ +.. _arduino-map: + +map(value, fromLow, fromHigh, toLow, toHigh) +============================================ + +Description +----------- + +Re-maps a number from one range to another. That is, a **value** of +**fromLow** would get mapped to **toLow**, a value of **fromHigh** +to **toHigh**, values in-between to values in-between, etc. + + + +Does not constrain values to within the range, because out-of-range +values are sometimes intended and useful. The constrain() function +may be used either before or after this function, if limits to the +ranges are desired. + + + +Note that the "lower bounds" of either range may be larger or +smaller than the "upper bounds" so the map() function may be used +to reverse a range of numbers, for example + + + +``y = map(x, 1, 50, 50, 1);`` + + + +The function also handles negative numbers well, so that this +example + + + +``y = map(x, 1, 50, 50, -100);`` + + + +is also valid and works well. + + + +The map() function uses integer math so will not generate +fractions, when the math might indicate that it should do so. +Fractional remainders are truncated, and are not rounded or +averaged. + + + +Parameters +---------- + +value: the number to map + + + +fromLow: the lower bound of the value's current range + + + +fromHigh: the upper bound of the value's current range + + + +toLow: the lower bound of the value's target range + + + +toHigh: the upper bound of the value's target range + + + +Returns +------- + +The mapped value. + + + +Example +------- + +:: + + /* Map an analog value to 8 bits (0 to 255) */ + void setup() {} + + void loop() + { + int val = analogRead(0); + val = map(val, 0, 1023, 0, 255); + analogWrite(9, val); + } + + + +Appendix +~~~~~~~~ + +For the mathematically inclined, here's the whole function + + + +:: + + long map(long x, long in_min, long in_max, long out_min, long out_max) + { + return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; + } + + + +See Also +-------- + + +- `constrain `_\ () diff --git a/source/arduino/max.rst b/source/arduino/max.rst new file mode 100644 index 0000000..375625c --- /dev/null +++ b/source/arduino/max.rst @@ -0,0 +1,71 @@ +.. _arduino-max: + +max(x, y) +========= + +Description +----------- + +Calculates the maximum of two numbers. + + + +Parameters +---------- + +x: the first number, any data type + + + +y: the second number, any data type + + + +Returns +------- + +The larger of the two parameter values. + + + +Example +------- + +:: + + sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 + // (effectively ensuring that it is at least 20) + +Note +---- + +Perhaps counter-intuitively, max() is often used to constrain the +lower end of a variable's range, while min() is used to constrain +the upper end of the range. + + + +Warning +------- + +Because of the way the max() function is implemented, avoid using +other functions inside the brackets, it may lead to incorrect +results + + + +:: + + max(a--, 0); // avoid this - yields incorrect results + + a--; // use this instead - + max(a, 0); // keep other math outside the function + + + +See also +-------- + + +- `min `_\ () +- `constrain `_\ () diff --git a/source/arduino/micros.rst b/source/arduino/micros.rst new file mode 100644 index 0000000..cdee497 --- /dev/null +++ b/source/arduino/micros.rst @@ -0,0 +1,66 @@ +.. _arduino-micros: + +micros() +======== + +Description +----------- + +Returns the number of microseconds since the Arduino board began +running the current program. This number will overflow (go back to +zero), after approximately 70 minutes. On 16 MHz Arduino boards +(e.g. Duemilanove and Nano), this function has a resolution of four +microseconds (i.e. the value returned is always a multiple of +four). On 8 MHz Arduino boards (e.g. the LilyPad), this function +has a resolution of eight microseconds. + + + +*Note*: there are 1,000 microseconds in a millisecond and 1,000,000 +microseconds in a second. + + + +Parameters +---------- + +None + + + +Returns +------- + +Number of microseconds since the program started (*unsigned long*) + + + +Example +------- + +:: + + unsigned long time; + + void setup(){ + Serial.begin(9600); + } + void loop(){ + Serial.print("Time: "); + time = micros(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + + + +See also +-------- + + +- `millis `_\ () +- `delay `_\ () +- `delayMicroseconds `_\ () + diff --git a/source/arduino/millis.rst b/source/arduino/millis.rst new file mode 100644 index 0000000..009517d --- /dev/null +++ b/source/arduino/millis.rst @@ -0,0 +1,67 @@ +.. _arduino-millis: + +millis() +======== + +Description +----------- + +Returns the number of milliseconds since the Arduino board began +running the current program. This number will overflow (go back to +zero), after approximately 50 days. + + + +Parameters +---------- + +None + + + +Returns +------- + +Number of milliseconds since the program started (*unsigned long*) + + + +Example +------- + +:: + + unsigned long time; + + void setup(){ + Serial.begin(9600); + } + void loop(){ + Serial.print("Time: "); + time = millis(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + + + +Tip: +---- + +Note that the parameter for millis is an unsigned long, errors may +be generated if a programmer tries to do math with other datatypes +such as ints. + + + +See also +-------- + + +- `micros `_\ () +- `delay `_\ () +- `delayMicroseconds `_\ () +- `Tutorial: Blink Without Delay `_ + diff --git a/source/arduino/min.rst b/source/arduino/min.rst new file mode 100644 index 0000000..fdd7a5f --- /dev/null +++ b/source/arduino/min.rst @@ -0,0 +1,71 @@ +.. _arduino-min: + +min(x, y) +========= + +Description +----------- + +Calculates the minimum of two numbers. + + + +Parameters +---------- + +x: the first number, any data type + + + +y: the second number, any data type + + + +Returns +------- + +The smaller of the two numbers. + + + +Examples +-------- + +:: + + sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 + // ensuring that it never gets above 100. + +Note +---- + +Perhaps counter-intuitively, max() is often used to constrain the +lower end of a variable's range, while min() is used to constrain +the upper end of the range. + + + +Warning +------- + +Because of the way the min() function is implemented, avoid using +other functions inside the brackets, it may lead to incorrect +results + + + +:: + + min(a++, 100); // avoid this - yields incorrect results + + a++; + min(a, 100); // use this instead - keep other math outside the function + + + +See also +-------- + + +- `max `_\ () +- `constrain `_\ () diff --git a/source/arduino/modulo.rst b/source/arduino/modulo.rst new file mode 100644 index 0000000..195d15b --- /dev/null +++ b/source/arduino/modulo.rst @@ -0,0 +1,84 @@ +.. _arduino-modulo: + +% (modulo) +========== + +Description +----------- + +Calculates the remainder when one integer is divided by another. It +is useful for keeping a variable within a particular range (e.g. +the size of an array). + + + +Syntax +------ + +result = dividend % divisor + + + +Parameters +---------- + +dividend: the number to be divided + + + +divisor: the number to divide by + + + +Returns +------- + +the remainder + + + +Examples +-------- + +:: + + x = 7 % 5; // x now contains 2 + x = 9 % 5; // x now contains 4 + x = 5 % 5; // x now contains 0 + x = 4 % 5; // x now contains 4 + + + +Example Code +------------ + +:: + + /* update one value in an array each time through a loop */ + + int values[10]; + int i = 0; + + void setup() {} + + void loop() + { + values[i] = analogRead(0); + i = (i + 1) % 10; // modulo operator rolls over variable + } + + + +Tip +--- + +The modulo operator does not work on floats. + + + +See also +-------- + + +- `division `_ + diff --git a/source/arduino/nointerrupts.rst b/source/arduino/nointerrupts.rst new file mode 100644 index 0000000..10d504d --- /dev/null +++ b/source/arduino/nointerrupts.rst @@ -0,0 +1,56 @@ +.. _arduino-nointerrupts: + +noInterrupts() +============== + +Description +----------- + +Disables interrupts (you can re-enable them with interrupts()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None. + + + +Returns +------- + +None. + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `interrupts `_\ () + + diff --git a/source/arduino/notone.rst b/source/arduino/notone.rst new file mode 100644 index 0000000..4390b52 --- /dev/null +++ b/source/arduino/notone.rst @@ -0,0 +1,47 @@ +.. _arduino-notone: + +noTone() +======== + +Description +----------- + +Stops the generation of a square wave triggered by +`tone `_\ (). Has no effect if +no tone is being generated. + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +noTone(pin) + + + +Parameters +---------- + +pin: the pin on which to stop generating the tone + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `tone `_ () + diff --git a/source/arduino/pinmode.rst b/source/arduino/pinmode.rst new file mode 100644 index 0000000..34c7998 --- /dev/null +++ b/source/arduino/pinmode.rst @@ -0,0 +1,67 @@ +.. highlight:: cpp + +.. _arduino-pinmode: + +pinMode() +========= + +.. doxygenfunction:: pinMode + +.. doxygenenum:: WiringPinMode + +Discussion +---------- + +pinMode() is usually called within :ref:`arduino-setup` in order to +configure a pin for a certain usage (although it may be called from +anywhere). + + +Example +------- + + :: + + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Arduino Compatibility Note +-------------------------- + +The libmaple implementation of pinMode() supports OUTPUT and INPUT +modes with a meaning identical to that of the Arduino function. + +INPUT_ANALOG and PWM modes were added because the Maple does not +distinguish between analog and digital pins the same way the Arduino +does. Unlike the Arduino, you **must call pinMode**\ () to set up a pin +for these purposes before a call to, e.g., :ref:`arduino-analogRead`. +In practice, this should only add a few lines of pinMode() calls to +your :ref:`arduino-setup` function. + +OUTPUT_OPEN_DRAIN, INPUT_PULLUP, INPUT_PULLDOWN, and PWM_OPEN_DRAIN +modes represent functionality not currently available on Arduino +boards. + +See also +-------- + +- :ref:`arduino-constants` +- :ref:`arduino-digitalwrite` +- :ref:`arduino-digitalread` +- Maple :ref:`GPIO ` reference page +- Arduino `pinMode() `_ reference diff --git a/source/arduino/pointer.rst b/source/arduino/pointer.rst new file mode 100644 index 0000000..4e4b9e5 --- /dev/null +++ b/source/arduino/pointer.rst @@ -0,0 +1,16 @@ +.. _arduino-pointer: + +The pointer operators +===================== + +& (reference) and \* (dereference) +================================== + +Pointers are one of the more complicated subjects for beginners in +learning C, and it is possible to write the vast majority of +Arduino sketches without ever encountering pointers. However for +manipulating certain data structures, the use of pointers can +simplify the code, and and knowledge of manipulating pointers is +handy to have in one's toolkit. + + diff --git a/source/arduino/pow.rst b/source/arduino/pow.rst new file mode 100644 index 0000000..3a09481 --- /dev/null +++ b/source/arduino/pow.rst @@ -0,0 +1,47 @@ +.. _arduino-pow: + +pow(base, exponent) +=================== + +Description +----------- + +Calculates the value of a number raised to a power. Pow() can be +used to raise a number to a fractional power. This is useful for +generating exponential mapping of values or curves. + + + +Parameters +---------- + +base: the number (*float*) + + + +exponent: the power to which the base is raised (*float*) + + + +Returns +------- + +The result of the exponentiation (*double*) + + + +Example +------- + +See the `fscale `_ +function in the code library. + + + +See also +-------- + + +- `sqrt `_\ () +- `float `_ +- `double `_ diff --git a/source/arduino/pulsein.rst b/source/arduino/pulsein.rst new file mode 100644 index 0000000..568d992 --- /dev/null +++ b/source/arduino/pulsein.rst @@ -0,0 +1,79 @@ +.. _arduino-pulsein: + +pulseIn() +========= + +Description +----------- + +Reads a pulse (either HIGH or LOW) on a pin. For example, if +**value** is **HIGH**, **pulseIn()** waits for the pin to go +**HIGH**, starts timing, then waits for the pin to go **LOW** and +stops timing. Returns the length of the pulse in microseconds. +Gives up and returns 0 if no pulse starts within a specified time +out. + + + +The timing of this function has been determined empirically and +will probably show errors in longer pulses. Works on pulses from 10 +microseconds to 3 minutes in length. + + + +Syntax +------ + +pulseIn(pin, value) +pulseIn(pin, value, timeout) + + + +Parameters +---------- + +pin: the number of the pin on which you want to read the pulse. +(*int*) + + + +value: type of pulse to read: either +`HIGH `_ or +`LOW `_. (*int*) + + + +timeout (optional): the number of microseconds to wait for the +pulse to start; default is one second (*unsigned long*) + + + +Returns +------- + +the length of the pulse (in microseconds) or 0 if no pulse started +before the timeout (*unsigned long*) + + + +Example +------- + +:: + + + + int pin = 7; + unsigned long duration; + + void setup() + { + pinMode(pin, INPUT); + } + + void loop() + { + duration = pulseIn(pin, HIGH); + } + + diff --git a/source/arduino/random.rst b/source/arduino/random.rst new file mode 100644 index 0000000..44f122a --- /dev/null +++ b/source/arduino/random.rst @@ -0,0 +1,92 @@ +.. _arduino-random: + +random() +======== + +Description +----------- + +The random function generates pseudo-random numbers. + + + +Syntax +------ + +random(max) +random(min, max) + + + +Parameters +---------- + +min - lower bound of the random value, inclusive *(optional)* + + + +max - upper bound of the random value, exclusive + + + +Returns +------- + +a random number between min and max-1 (*long*) + + + +Note: +----- + +If it is important for a sequence of values generated by random() +to differ, on subsequent executions of a sketch, use randomSeed() +to initialize the random number generator with a fairly random +input, such as analogRead() on an unconnected pin. + + + +Conversely, it can occasionally be useful to use pseudo-random +sequences that repeat exactly. This can be accomplished by calling +randomSeed() with a fixed number, before starting the random +sequence. + + + +Example +------- + +:: + + long randNumber; + + void setup(){ + Serial.begin(9600); + + // if analog input pin 0 is unconnected, random analog + // noise will cause the call to randomSeed() to generate + // different seed numbers each time the sketch runs. + // randomSeed() will then shuffle the random function. + randomSeed(analogRead(0)); + } + + void loop() { + // print a random number from 0 to 299 + randNumber = random(300); + Serial.println(randNumber); + + // print a random number from 10 to 19 + randNumber = random(10, 20); + Serial.println(randNumber); + + delay(50); + } + + + +See also +-------- + + +- `randomSeed `_\ () + diff --git a/source/arduino/randomseed.rst b/source/arduino/randomseed.rst new file mode 100644 index 0000000..b0b5d71 --- /dev/null +++ b/source/arduino/randomseed.rst @@ -0,0 +1,70 @@ +.. _arduino-randomseed: + +randomSeed(seed) +================ + +Description +----------- + +randomSeed() initializes the pseudo-random number generator, +causing it to start at an arbitrary point in its random sequence. +This sequence, while very long, and random, is always the same. + + + +If it is important for a sequence of values generated by random() +to differ, on subsequent executions of a sketch, use randomSeed() +to initialize the random number generator with a fairly random +input, such as analogRead() on an unconnected pin. + + + +Conversely, it can occasionally be useful to use pseudo-random +sequences that repeat exactly. This can be accomplished by calling +randomSeed() with a fixed number, before starting the random +sequence. + + + +Parameters +---------- + +long, int - pass a number to generate the seed. + + + +Returns +------- + +no returns + + + +Example +------- + +:: + + long randNumber; + + void setup(){ + Serial.begin(9600); + randomSeed(analogRead(0)); + } + + void loop(){ + randNumber = random(300); + Serial.println(randNumber); + + delay(50); + } + + + +See also +-------- + + +- `random `_ + + diff --git a/source/arduino/return.rst b/source/arduino/return.rst new file mode 100644 index 0000000..ae3b37d --- /dev/null +++ b/source/arduino/return.rst @@ -0,0 +1,69 @@ +.. _arduino-return: + +return +====== + +Terminate a function and return a value from a function to the +calling function, if desired. + + + +Syntax: +------- + +return; + + + +return value; // both forms are valid + + + +Parameters +---------- + +value: any variable or constant type + + + +Examples: +--------- + +A function to compare a sensor input to a threshold + +:: + + int checkSensor(){ + if (analogRead(0) > 400) { + return 1; + else{ + return 0; + } + } + + + +The return keyword is handy to test a section of code without +having to "comment out" large sections of possibly buggy code. + + + +:: + + void loop(){ + + // brilliant code idea to test here + + return; + + // the rest of a dysfunctional sketch here + // this code will never be executed + } + + + +See also +-------- + +`comments `_ + diff --git a/source/arduino/scope.rst b/source/arduino/scope.rst new file mode 100644 index 0000000..bb56246 --- /dev/null +++ b/source/arduino/scope.rst @@ -0,0 +1,56 @@ +.. _arduino-scope: + +Variable Scope +============== + +Variables in the C programming language, which Arduino uses, have a +property called *scope*. This is in contrast to languages such as +BASIC where every variable is a *global* variable. + + + +A global variable is one that can be *seen* by every function in a +program. Local variables are only visible to the function in which +they are declared. In the Arduino environment, any variable +declared outside of a function (e.g. setup(), loop(), etc. ), is a +global variable. + + + +When programs start to get larger and more complex, local variables +are a useful way to insure that only one function has access to its +own variables. This prevents programming errors when one function +inadvertently modifies variables used by another function. + + + +It is also sometimes handy to declare and initialize a variable +inside a *for* loop. This creates a variable that can only be +accessed from inside the for-loop brackets. + + + +Example: +-------- + +:: + + int gPWMval; // any function will see this variable + + void setup() + { + // ... + } + + void loop() + { + int i; // "i" is only "visible" inside of "loop" + float f; // "f" is only "visible" inside of "loop" + // ... + + for (int j = 0; j <100; j++){ + // variable j can only be accessed inside the for-loop brackets + } + + } + diff --git a/source/arduino/semicolon.rst b/source/arduino/semicolon.rst new file mode 100644 index 0000000..b3cc8c4 --- /dev/null +++ b/source/arduino/semicolon.rst @@ -0,0 +1,27 @@ +.. _arduino-semicolon: + +; semicolon +=========== + +Used to end a statement. + + + +Example +~~~~~~~ + +:: + + int a = 13; + +Tip +--- + +Forgetting to end a line in a semicolon will result in a compiler +error. The error text may be obvious, and refer to a missing +semicolon, or it may not. If an impenetrable or seemingly illogical +compiler error comes up, one of the first things to check is a +missing semicolon, in the immediate vicinity, preceding the line at +which the compiler complained. + + diff --git a/source/arduino/serial.rst b/source/arduino/serial.rst new file mode 100644 index 0000000..31ce06c --- /dev/null +++ b/source/arduino/serial.rst @@ -0,0 +1,62 @@ +.. _arduino-serial: + +Serial +====== + +Used for communication between the Arduino board and a computer or +other devices. All Arduino boards have at least one serial port +(also known as a UART or USART): **Serial**. It communicates on +digital pins 0 (RX) and 1 (TX) as well as with the computer via +USB. Thus, if you use these functions, you cannot also use pins 0 +and 1 for digital input or output. + + + +You can use the Arduino environment's built-in serial monitor to +communicate with an Arduino board. Click the serial monitor button +in the toolbar and select the same baud rate used in the call to +begin(). + + + +The Arduino Mega has three additional serial ports: **Serial1** on +pins 19 (RX) and 18 (TX), **Serial2** on pins 17 (RX) and 16 (TX), +**Serial3** on pins 15 (RX) and 14 (TX). To use these pins to +communicate with your personal computer, you will need an +additional USB-to-serial adaptor, as they are not connected to the +Mega's USB-to-serial adaptor. To use them to communicate with an +external TTL serial device, connect the TX pin to your device's RX +pin, the RX to your device's TX pin, and the ground of your Mega to +your device's ground. (Don't connect these pins directly to an +RS232 serial port; they operate at +/- 12V and can damage your +Arduino board.) + + + +Functions +--------- + + +- `begin `_\ () +- `end `_\ () +- `available `_\ () +- `read `_\ () +- `flush `_\ () +- `print `_\ () +- `println `_\ () +- `write `_\ () + + + +Examples +-------- + + +- `ASCII Table `_ +- `Dimmer `_ +- `Graph `_ +- `Physical Pixel `_ +- `Virtual Color Mixer `_ +- `Serial Call Response `_ +- `Serial Call Response ASCII `_ + diff --git a/source/arduino/setup.rst b/source/arduino/setup.rst new file mode 100644 index 0000000..05911ed --- /dev/null +++ b/source/arduino/setup.rst @@ -0,0 +1,31 @@ +.. _arduino-setup: + +setup() +======= + +The setup() function is called when a sketch starts. Use it to +initialize variables, pin modes, start using libraries, etc. The +setup function will only run once, after each powerup or reset of +the Arduino board. + + + +Example +~~~~~~~ + +:: + + + int buttonPin = 3; + + void setup() + { + Serial.begin(9600); + pinMode(buttonPin, INPUT); + } + + void loop() + { + // ... + } + diff --git a/source/arduino/shiftout.rst b/source/arduino/shiftout.rst new file mode 100644 index 0000000..2277cf1 --- /dev/null +++ b/source/arduino/shiftout.rst @@ -0,0 +1,133 @@ +.. _arduino-shiftout: + +shiftOut() +========== + +Description +----------- + +Shifts out a byte of data one bit at a time. Starts from either the +most (i.e. the leftmost) or least (rightmost) significant bit. Each +bit is written in turn to a data pin, after which a clock pin is +pulsed to indicate that the bit is available. + + + +This is a software implementation; Arduino (as of 0019) also +provides an `SPI library `_ +that uses the hardware implementation. + + + +Syntax +------ + +shiftOut(dataPin, clockPin, bitOrder, value) + + + +Parameters +---------- + +dataPin: the pin on which to output each bit (*int*) + + + +clockPin: the pin to toggle once the **dataPin** has been set to +the correct value (*int*) + + + +bitOrder: which order to shift out the bits; either **MSBFIRST** or +**LSBFIRST**. +(Most Significant Bit First, or, Least Significant Bit First) + + + +value: the data to shift out. (*byte*) + + + +Returns +------- + +None + + + +Note +---- + +The **dataPin** and **clockPin** must already be configured as +outputs by a call to +`pinMode `_\ (). + + + +**shiftOut** is currently written to output 1 byte (8 bits) so it +requires a two step operation to output values larger than 255. + +:: + + // Do this for MSBFIRST serial + int data = 500; + // shift out highbyte + shiftOut(dataPin, clock, MSBFIRST, (data >> 8)); + // shift out lowbyte + shiftOut(data, clock, MSBFIRST, data); + + // Or do this for LSBFIRST serial + data = 500; + // shift out lowbyte + shiftOut(dataPin, clock, LSBFIRST, data); + // shift out highbyte + shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); + + + +Example +------- + +*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register `_.* + + + +:: + + //**************************************************************// + // Name : shiftOutCode, Hello World // + // Author : Carlyn Maw,Tom Igoe // + // Date : 25 Oct, 2006 // + // Version : 1.0 // + // Notes : Code for using a 74HC595 Shift Register // + // : to count from 0 to 255 // + //**************************************************************** + + //Pin connected to ST_CP of 74HC595 + int latchPin = 8; + //Pin connected to SH_CP of 74HC595 + int clockPin = 12; + ////Pin connected to DS of 74HC595 + int dataPin = 11; + + void setup() { + //set pins to output because they are addressed in the main loop + pinMode(latchPin, OUTPUT); + pinMode(clockPin, OUTPUT); + pinMode(dataPin, OUTPUT); + } + + void loop() { + //count up routine + for (int j = 0; j < 256; j++) { + //ground latchPin and hold low for as long as you are transmitting + digitalWrite(latchPin, LOW); + shiftOut(dataPin, clockPin, LSBFIRST, j); + //return the latch pin high to signal chip that it + //no longer needs to listen for information + digitalWrite(latchPin, HIGH); + delay(1000); + } + } + + diff --git a/source/arduino/sin.rst b/source/arduino/sin.rst new file mode 100644 index 0000000..3a06a8f --- /dev/null +++ b/source/arduino/sin.rst @@ -0,0 +1,35 @@ +.. _arduino-sin: + +sin(rad) +======== + +Description +----------- + +Calculates the sine of an angle (in radians). The result will be +between -1 and 1. + + + +Parameters +---------- + +rad: the angle in radians (*float*) + + + +Returns +------- + +the sine of the angle (*double*) + + + +See also +-------- + + +- `cos `_\ () +- `tan `_\ () +- `float `_ +- `double `_ diff --git a/source/arduino/sizeof.rst b/source/arduino/sizeof.rst new file mode 100644 index 0000000..a95dfbf --- /dev/null +++ b/source/arduino/sizeof.rst @@ -0,0 +1,71 @@ +.. _arduino-sizeof: + +sizeof +====== + +Description +----------- + +The sizeof operator returns the number of bytes in a variable type, +or the number of bytes occupied by an array. + + + +Syntax +------ + +sizeof(variable) + + + +Parameters +---------- + +variable: any variable type or array (e.g. int, float, byte) + + + +Example code +------------ + +The sizeof operator is useful for dealing with arrays (such as +strings) where it is convenient to be able to change the size of +the array without breaking other parts of the program. + + + +This program prints out a text string one character at a time. Try +changing the text phrase. + + + +:: + + char myStr[] = "this is a test"; + int i; + + void setup(){ + Serial.begin(9600); + } + + void loop() { + for (i = 0; i < sizeof(myStr) - 1; i++){ + Serial.print(i, DEC); + Serial.print(" = "); + Serial.println(myStr[i], BYTE); + } + } + + +Note that sizeof returns the total number of bytes. So for larger +variable types such as ints, the for loop would look something like +this. + + + +:: + + for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { + // do something with myInts[i] + } + diff --git a/source/arduino/sqrt.rst b/source/arduino/sqrt.rst new file mode 100644 index 0000000..5b8a73e --- /dev/null +++ b/source/arduino/sqrt.rst @@ -0,0 +1,33 @@ +.. _arduino-sqrt: + +sqrt(x) +======= + +Description +----------- + +Calculates the square root of a number. + + + +Parameters +---------- + +x: the number, any data type + + + +Returns +------- + +double, the number's square root. + + + +See also +-------- + + +- `pow `_\ () +- `sq `_\ () + diff --git a/source/arduino/static.rst b/source/arduino/static.rst new file mode 100644 index 0000000..1c0340e --- /dev/null +++ b/source/arduino/static.rst @@ -0,0 +1,71 @@ +.. _arduino-static: + +Static +====== + +The static keyword is used to create variables that are visible to +only one function. However unlike local variables that get created +and destroyed every time a function is called, static variables +persist beyond the function call, preserving their data between +function calls. + + + +Variables declared as static will only be created and initialized +the first time a function is called. + + + +Example +------- + +:: + + + + /* RandomWalk + * Paul Badger 2007 + * RandomWalk wanders up and down randomly between two + * endpoints. The maximum move in one loop is governed by + * the parameter "stepsize". + * A static variable is moved up and down a random amount. + * This technique is also known as "pink noise" and "drunken walk". + */ + + #define randomWalkLowRange -20 + #define randomWalkHighRange 20 + int stepsize; + + int thisTime; + int total; + + void setup() + { + Serial.begin(9600); + } + + void loop() + { // tetst randomWalk function + stepsize = 5; + thisTime = randomWalk(stepsize); + Serial.println(thisTime); + delay(10); + } + + int randomWalk(int moveSize){ + static int place; // variable to store value in random walk - declared static so that it stores + // values in between function calls, but no other functions can change its value + + place = place + (random(-moveSize, moveSize + 1)); + + if (place < randomWalkLowRange){ // check lower and upper limits + place = place + (randomWalkLowRange - place); // reflect number back in positive direction + } + else if(place > randomWalkHighRange){ + place = place - (place - randomWalkHighRange); // reflect number back in negative direction + } + + return place; + } + + diff --git a/source/arduino/string.rst b/source/arduino/string.rst new file mode 100644 index 0000000..b841728 --- /dev/null +++ b/source/arduino/string.rst @@ -0,0 +1,158 @@ +.. _arduino-string: + +string +====== + +Description +----------- + +Text strings can be represented in two ways. you can use the String +data type, which is part of the core as of version 0019, or you can +make a string out of an array of type char and null-terminate it. +This page described the latter method. For more details on the +String object, which gives you more functionality at the cost of +more memory, see the +`String object `_ +page. + + + +Examples +-------- + +All of the following are valid declarations for strings. + +:: + + char Str1[15]; + char Str2[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o'}; + char Str3[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o', '\0'}; + char Str4[ ] = "arduino"; + char Str5[8] = "arduino"; + char Str6[15] = "arduino"; + + + +**Possibilities for declaring strings** + + + + +- Declare an array of chars without initializing it as in Str1 +- Declare an array of chars (with one extra char) and the compiler + will add the required null character, as in Str2 +- Explicitly add the null character, Str3 +- Initialize with a string constant in quotation marks; the + compiler will size the array to fit the string constant and a + terminating null character, Str4 +- Initialize the array with an explicit size and string constant, + Str5 +- Initialize the array, leaving extra space for a larger string, + Str6 + + + +**Null termination** + + + +Generally, strings are terminated with a null character (ASCII code +0). This allows functions (like Serial.print()) to tell where the +end of a string is. Otherwise, they would continue reading +subsequent bytes of memory that aren't actually part of the +string. + + + +This means that your string needs to have space for one more +character than the text you want it to contain. That is why Str2 +and Str5 need to be eight characters, even though "arduino" is only +seven - the last position is automatically filled with a null +character. Str4 will be automatically sized to eight characters, +one for the extra null. In Str3, we've explicitly included the null +character (written '\\0') ourselves. + + + +Note that it's possible to have a string without a final null +character (e.g. if you had specified the length of Str2 as seven +instead of eight). This will break most functions that use strings, +so you shouldn't do it intentionally. If you notice something +behaving strangely (operating on characters not in the string), +however, this could be the problem. + + + +**Single quotes or double quotes?** + + + +Strings are always defined inside double quotes ("Abc") and +characters are always defined inside single quotes('A'). + + + +**Wrapping long strings** + + + +You can wrap long strings like this: + +:: + + char myString[] = "This is the first line" + " this is the second line" + " etcetera"; + + + +**Arrays of strings** + + + +It is often convenient, when working with large amounts of text, +such as a project with an LCD display, to setup an array of +strings. Because strings themselves are arrays, this is in actually +an example of a two-dimensional array. + + + +In the code below, the asterisk after the datatype char "char\*" +indicates that this is an array of "pointers". All array names are +actually pointers, so this is required to make an array of arrays. +Pointers are one of the more esoteric parts of C for beginners to +understand, but it isn't necessary to understand pointers in detail +to use them effectively here. + + + +Example +------- + +:: + + + char* myStrings[]={"This is string 1", "This is string 2", "This is string 3", + "This is string 4", "This is string 5","This is string 6"}; + + void setup(){ + Serial.begin(9600); + } + + void loop(){ + for (int i = 0; i < 6; i++){ + Serial.println(myStrings[i]); + delay(500); + } + } + + + +See Also +-------- + + +- `array `_ +- `PROGMEM `_ +- `Variable Declaration `_ + diff --git a/source/arduino/stringobject.rst b/source/arduino/stringobject.rst new file mode 100644 index 0000000..ffee295 --- /dev/null +++ b/source/arduino/stringobject.rst @@ -0,0 +1,88 @@ +.. _arduino-stringobject: + +String +====== + +Description +----------- + +The String class, part of the core as of version 0019, allows you +to use and manipulate strings of text in more complex ways than +`character arrays `_ do. You +can concatenate Strings, append to them, search for and replace +substrings, and more. It takes more memory than a simple character +array, but it is also more useful. + + + +For reference, character arrays are referred to as strings with a +small s, and instances of the String class are referred to as +Strings with a capital S. Note that constant strings, specified in +"double quotes" are treated as char arrays, not instances of the +String class. + + + +Functions +--------- + + +- `String `_\ () +- `charAt `_\ () +- `compareTo `_\ () +- `concat `_\ () +- `endsWith `_\ () +- `equals `_\ () +- `equalsIgnoreCase `_\ () +- `getBytes `_\ () +- `indexOf `_\ () +- `lastIndexOf `_\ () +- `length `_\ () +- `replace `_\ () +- `setCharAt `_\ () +- `startsWith `_\ () +- `substring `_\ () +- `toCharArray `_\ () +- `toLowerCase `_\ () +- `toUpperCase `_\ () +- `trim `_\ () + + + +Operators +--------- + + +- `[] (element access) `_ +- `+ (concatenation) `_ +- `== (comparison) `_ + + + +Examples +-------- + + +- `StringConstructors `_ +- `StringAdditionOperator `_ +- `StringIndexOf `_ +- `StringAppendOperator `_ +- `StringLengthTrim `_ +- `StringCaseChanges `_ +- `StringReplace `_ +- `StringCharacters `_ +- `StringStartsWithEndsWith `_ +- `StringComparisonOperators `_ +- `StringSubstring `_ + + + +See Also +-------- + + +- `string `_: character + arrays +- `Variable Declaration `_ + + diff --git a/source/arduino/switchcase.rst b/source/arduino/switchcase.rst new file mode 100644 index 0000000..28791eb --- /dev/null +++ b/source/arduino/switchcase.rst @@ -0,0 +1,77 @@ +.. _arduino-switchcase: + +switch / case statements +======================== + +Like **if** statements, **switch...case** controls the flow of +programs by allowing programmers to specify different code that +should be executed in various conditions. In particular, a switch +statement compares the value of a variable to the values specified +in case statements. When a case statement is found whose value +matches that of the variable, the code in that case statement is +run. + + + +The **break** keyword exits the switch statement, and is typically +used at the end of each case. Without a break statement, the switch +statement will continue executing the following expressions +("falling-through") until a break, or the end of the switch +statement is reached. + + + +Example +~~~~~~~ + +:: + + switch (var) { + case 1: + //do something when var equals 1 + break; + case 2: + //do something when var equals 2 + break; + default: + // if nothing else matches, do the default + // default is optional + } + + + +Syntax +~~~~~~ + +:: + + switch (var) { + case label: + // statements + break; + case label: + // statements + break; + default: + // statements + } + + + +Parameters +~~~~~~~~~~ + +var: the variable whose value to compare to the various cases + + + +label: a value to compare the variable to + + + +See also: +--------- + +`if...else `_ + + diff --git a/source/arduino/tan.rst b/source/arduino/tan.rst new file mode 100644 index 0000000..f31b357 --- /dev/null +++ b/source/arduino/tan.rst @@ -0,0 +1,35 @@ +.. _arduino-tan: + +tan(rad) +======== + +Description +----------- + +Calculates the tangent of an angle (in radians). The result will be +between negative infinity and infinity. + + + +Parameters +---------- + +rad: the angle in radians (*float*) + + + +Returns +------- + +The tangent of the angle (*double*) + + + +See also +-------- + + +- `sin `_\ () +- `cos `_\ () +- `float `_ +- `double `_ diff --git a/source/arduino/tone.rst b/source/arduino/tone.rst new file mode 100644 index 0000000..c7b1e44 --- /dev/null +++ b/source/arduino/tone.rst @@ -0,0 +1,78 @@ +.. _arduino-tone: + +tone() +====== + +Description +----------- + +Generates a square wave of the specified frequency (and 50% duty +cycle) on a pin. A duration can be specified, otherwise the wave +continues until a call to +`noTone `_\ (). The pin can be +connected to a piezo buzzer or other speaker to play tones. + + + +Only one tone can be generated at a time. If a tone is already +playing on a different pin, the call to tone() will have no effect. +If the tone is playing on the same pin, the call will set its +frequency. + + + +Use of the tone() function will interfere with PWM output on pins 3 +and 11 (on boards other than the Mega). + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +tone(pin, frequency) +tone(pin, frequency, duration) + + + +Parameters +---------- + +pin: the pin on which to generate the tone + + + +frequency: the frequency of the tone in hertz + + + +duration: the duration of the tone in milliseconds (optional) + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `noTone `_\ () +- `analogWrite `_\ () +- `Tutorial:Tone `_ +- `Tutorial:Pitch follower `_ +- `Tutorial:Simple Keyboard `_ +- `Tutorial: multiple tones `_ + + +- `Tutorial: PWM `_ + diff --git a/source/arduino/unsignedchar.rst b/source/arduino/unsignedchar.rst new file mode 100644 index 0000000..f846105 --- /dev/null +++ b/source/arduino/unsignedchar.rst @@ -0,0 +1,41 @@ +.. _arduino-unsignedchar: + +unsigned char +============= + +Description +----------- + +An unsigned data type that occupies 1 byte of memory. Same as the +`byte `_ datatype. + + + +The unsigned char datatype encodes numbers from 0 to 255. + + + +For consistency of Arduino programming style, the *byte* data type +is to be preferred. + + + +Example +------- + +:: + + unsigned char myChar = 240; + + + +See also +-------- + + +- `byte `_ +- `int `_ +- `array `_ +- `Serial.println `_ + + diff --git a/source/arduino/unsignedint.rst b/source/arduino/unsignedint.rst new file mode 100644 index 0000000..10835fe --- /dev/null +++ b/source/arduino/unsignedint.rst @@ -0,0 +1,77 @@ +.. _arduino-unsignedint: + +unsigned int +============ + +Description +----------- + +Unsigned ints (unsigned integers) are the same as ints in that they +store a 2 byte value. Instead of storing negative numbers however +they only store positive values, yielding a useful range of 0 to +65,535 (2^16) - 1). + + + +The difference between unsigned ints and (signed) ints, lies in the +way the highest bit, sometimes refered to as the "sign" bit, is +interpreted. In the Arduino int type (which is signed), if the high +bit is a "1", the number is interpreted as a negative number, and +the other 15 bits are interpreted with +`2's complement math. `_ + + + +Example +------- + +:: + + unsigned int ledPin = 13; + + + +Syntax +------ + +:: + + unsigned int var = val; + + + + +- var - your unsigned int variable name +- val - the value you assign to that variable + + + +Coding Tip +---------- + +When variables are made to exceed their maximum capacity they "roll +over" back to their minimum capacitiy, note that this happens in +both directions + + + +:: + + unsigned int x + x = 0; + x = x - 1; // x now contains 65535 - rolls over in neg direction + x = x + 1; // x now contains 0 - rolls over + + + +See Also +-------- + + +- `byte `_ +- `int `_ +- `long `_ +- `unsigned long `_ +- `Variable Declaration `_ + + diff --git a/source/arduino/unsignedlong.rst b/source/arduino/unsignedlong.rst new file mode 100644 index 0000000..1bdb434 --- /dev/null +++ b/source/arduino/unsignedlong.rst @@ -0,0 +1,63 @@ +.. _arduino-unsignedlong: + +unsigned long +============= + +Description +----------- + +Unsigned long variables are extended size variables for number +storage, and store 32 bits (4 bytes). Unlike standard longs +unsigned longs won't store negative numbers, making their range +from 0 to 4,294,967,295 (2^32 - 1). + + + +Example +------- + +:: + + unsigned long time; + + void setup() + { + Serial.begin(9600); + } + + void loop() + { + Serial.print("Time: "); + time = millis(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + +Syntax +------ + +:: + + unsigned long var = val; + + + + +- var - your long variable name +- val - the value you assign to that variable + + + +See Also +-------- + + +- `byte `_ +- `int `_ +- `unsigned int `_ +- `long `_ +- `Variable Declaration `_ + + diff --git a/source/arduino/void.rst b/source/arduino/void.rst new file mode 100644 index 0000000..00166b6 --- /dev/null +++ b/source/arduino/void.rst @@ -0,0 +1,37 @@ +.. _arduino-void: + +void +==== + +The void keyword is used only in function declarations. It +indicates that the function is expected to return no information to +the function from which it was called. + + + +Example: +-------- + +:: + + // actions are performed in the functions "setup" and "loop" + // but no information is reported to the larger program + + void setup() + { + // ... + } + + void loop() + { + // ... + } + + + + +See also +-------- + +`function declaration `_ + diff --git a/source/arduino/volatile.rst b/source/arduino/volatile.rst new file mode 100644 index 0000000..4212ac5 --- /dev/null +++ b/source/arduino/volatile.rst @@ -0,0 +1,70 @@ +.. _arduino-volatile: + +volatile keyword +================ + +volatile is a keyword known as a variable *qualifier*, it is +usually used before the datatype of a variable, to modify the way +in which the compiler and subsequent program treats the variable. + + + +Declaring a variable volatile is a directive to the compiler. The +compiler is software which translates your C/C++ code into the +machine code, which are the real instructions for the Atmega chip +in the Arduino. + + + +Specifically, it directs the compiler to load the variable from RAM +and not from a storage register, which is a temporary memory +location where program variables are stored and manipulated. Under +certain conditions, the value for a variable stored in registers +can be inaccurate. + + + +A variable should be declared volatile whenever its value can be +changed by something beyond the control of the code section in +which it appears, such as a concurrently executing thread. In the +Arduino, the only place that this is likely to occur is in sections +of code associated with interrupts, called an interrupt service +routine. + + + +Example +------- + +:: + + // toggles LED when interrupt pin changes state + + int pin = 13; + volatile int state = LOW; + + void setup() + { + pinMode(pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() + { + digitalWrite(pin, state); + } + + void blink() + { + state = !state; + } + + + +See also +-------- + + +- `AttachInterrupt `_ + + diff --git a/source/arduino/while.rst b/source/arduino/while.rst new file mode 100644 index 0000000..5155f09 --- /dev/null +++ b/source/arduino/while.rst @@ -0,0 +1,46 @@ +.. _arduino-while: + +while loops +=========== + +Description +----------- + +**while** loops will loop continuously, and infinitely, until the +expression inside the parenthesis, () becomes false. Something must +change the tested variable, or the **while** loop will never exit. +This could be in your code, such as an incremented variable, or an +external condition, such as testing a sensor. + + + +Syntax +------ + +:: + + while(expression){ + // statement(s) + } + + + +Parameters +---------- + +expression - a (boolean) C statement that evaluates to true or +false + + + +Example +------- + +:: + + var = 0; + while(var < 200){ + // do something repetitive 200 times + var++; + } + diff --git a/source/arduino/word.rst b/source/arduino/word.rst new file mode 100644 index 0000000..39b3a0d --- /dev/null +++ b/source/arduino/word.rst @@ -0,0 +1,29 @@ +.. _arduino-word: + +word +==== + +Description +----------- + +A word stores a 16-bit unsigned number, from 0 to 65535. Same as an +unsigned int. + + + +Example +------- + +:: + + word w = 10000; + + + +See also +-------- + + +- `byte `_ +- `word `_\ () + diff --git a/source/arduino/wordcast.rst b/source/arduino/wordcast.rst new file mode 100644 index 0000000..5ef821c --- /dev/null +++ b/source/arduino/wordcast.rst @@ -0,0 +1,51 @@ +.. _arduino-wordcast: + +word() +====== + +Description +----------- + +Convert a value to the +`word `_ data type or create a +word from two bytes. + + + +Syntax +------ + +word(x) +word(h, l) + + + +Parameters +---------- + +x: a value of any type + + + +h: the high-order (leftmost) byte of the word + + + +l: the low-order (rightmost) byte of the word + + + +Returns +------- + +word + + + +See also +-------- + + +- `word `_ + + diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst new file mode 100644 index 0000000..21379db --- /dev/null +++ b/source/arm-gcc.rst @@ -0,0 +1,13 @@ + +.. _arm-gcc: +.. _arm-gcc-attribute-flash: + +============ + GCC on ARM +============ + +Stub. + +Include special things, differences with AVR-GCC, using +``__attribute__`` to stick things in flash, etc. + diff --git a/source/conf.py b/source/conf.py index 26147fd..e1aa3a4 100644 --- a/source/conf.py +++ b/source/conf.py @@ -14,6 +14,7 @@ import sys, os + # 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. diff --git a/source/epilog.rst b/source/epilog.rst index 7805362..73aab6d 100644 --- a/source/epilog.rst +++ b/source/epilog.rst @@ -2,11 +2,19 @@ .. it's useful for common references, etc. .. Common URL references + .. _forum: http://forums.leaflabs.com .. _contact: http://leaflabs.com/contact/ +.. _stm32-all: http://www.st.com/mcu/devicedocs-STM32F103RB-110.html +.. _stm32-programming: http://www.st.com/stonline/products/literature/pm/15491.pdf +.. _stm32-adc-modes: http://www.st.com/stonline/products/literature/an/16840.pdf +.. _stm32-adc-oversampling: http://www.st.com/stonline/products/literature/an/14183.pdf +.. _full-manual: http://www.st.com/stonline/products/literature/rm/13902.pdf +.. _datasheet: http://www.st.com/stonline/products/literature/ds/13587.pdf .. Arduino built-in functions + .. _setup(): http://arduino.cc/en/Reference/Setup .. _loop(): http://arduino.cc/en/Reference/Loop diff --git a/source/foo.rst b/source/foo.rst new file mode 100644 index 0000000..d2ac4c6 --- /dev/null +++ b/source/foo.rst @@ -0,0 +1,114 @@ +.. _foo: + +================================== +[temporary] Converted Arduino docs +================================== + +This is the index of the imported Arduino docs. + +.. toctree:: + :maxdepth: 2 + + abs() + analogRead() + pinMode() + Arithmetic + Arrays + Assignment + +.. attachinterrupt +.. bit +.. bitclear +.. bitread +.. bitset +.. bitshift +.. bitwiseand +.. bitwisecompound +.. bitwisexornot +.. bitwrite +.. boolean +.. booleanvariables +.. braces +.. break +.. byte +.. bytecast +.. changes +.. char +.. charcast +.. comments +.. comparison +.. const +.. constants +.. constrain +.. continue +.. cos +.. define +.. delay +.. delaymicroseconds +.. detachinterrupt +.. digitalread +.. digitalwrite +.. double +.. dowhile +.. else +.. float +.. floatcast +.. for +.. fpconstants +.. goto +.. highbyte +.. homepage +.. if +.. include +.. increment +.. incrementcompound +.. int +.. intcast +.. integerconstants +.. interrupts +.. libraries +.. long +.. longcast +.. loop +.. lowbyte +.. map +.. max +.. micros +.. millis +.. min +.. modulo +.. nointerrupts +.. notone +.. pointer +.. pow +.. pulsein +.. random +.. randomseed +.. return +.. scope +.. semicolon +.. serial +.. setup +.. shiftout +.. sin +.. sizeof +.. sqrt +.. static +.. string +.. stringobject +.. switchcase +.. tan +.. tone +.. unsignedchar +.. unsignedint +.. unsignedlong +.. void +.. volatile +.. while +.. word +.. wordcast + +.. TODO later + +.. analogreference() +.. analogWrite() diff --git a/source/gpio.rst b/source/gpio.rst index 9104fed..bd562a7 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -80,77 +80,18 @@ above). GPIO Modes ---------- -``OUTPUT`` - - Basic digital output: when the pin set high the voltage is held at - +3.3V (|vcc|) and when set low it is pulled down to ground. - -``OUTPUT_OPEN_DRAIN`` - - In open drain mode, the pin indicates "low" by accepting current - flow to ground and "high" by providing increased impedance. An - example use would be to connect a pin to a bus line (which is - pulled up to a positive voltage by a separate supply through a - large resistor). When the pin is high, not much current flows - through to ground and the line stays at positive voltage; when the - pin is low the bus "drains" to ground with a small amount of - current constantly flowing through the large resistor from the - external supply. In this mode no current is ever actually - *sourced* from the pin. - -``INPUT`` (or ``INPUT_FLOATING``) - - Basic digital input. The pin voltage is sampled; when it is closer - to 3.3V (|vcc|) the pin status is high, and when it is closer to - 0V (ground) it is low. If no external circuit is pulling the pin - voltage to high or low, it will tend to randomly oscillate and be - very sensitive to noise (e.g., a breath of air across the pin will - cause the state to flip). - -``INPUT_PULLUP`` - - The state of the pin in this mode is reported the same way as with - INPUT, but the pin voltage is gently "pulled up" towards - +3.3V. This means the state will be high unless an external device - is specifically pulling the pin down to ground, in which case the - "gentle" pull up will not effect the state of the input. - -``INPUT_PULLDOWN`` - - The state of the pin in this mode is reported the same way as with - INPUT, but the pin voltage is gently "pulled down" towards - 0V. This means the state will be low unless an external device is - specifically pulling the pin up to 3.3V, in which case the - "gentle" pull down will not effect the state of the input. - -``INPUT_ANALOG`` - - This is a special mode for when the pin will be used for analog - (not digital) reads. See the :ref:`ADC ` page. - -``PWM`` - - This is a special mode for when the pin will be used for PWM - output (a special case of digital output). See the :ref:`PWM - ` page. - -.. TODO PWM_OPEN_DRAIN needs documentation +.. doxygenenum:: WiringMode Function Reference ------------------ -``pinMode(pin_number, MODE)`` - - Usually called from within `setup()`_ to configure the pin. MODE - is one of the set listed :ref:`above `. - -``digitalRead(pin_number)`` +.. doxygenfunction:: pinMode - Returns ``HIGH`` (|vcc|) or ``LOW`` (0V). +.. doxygenfunction:: digitalRead -``digitalWrite(pin_number, value)`` +.. doxygenfunction:: digitalWrite - Sets the pin to ``HIGH`` or ``LOW``. +.. doxygenfunction:: analogRead .. _gpio-recommended-reading: @@ -159,6 +100,6 @@ Recommended Reading STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/i2c.rst b/source/i2c.rst index 564ca0e..764a342 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -80,13 +80,9 @@ Recommended Reading * `Arduino i2c/TWI reference `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet - `_ - (pdf) - * `Reference Manual - `_ - (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) * `Application Note on Advanced I2C Usage `_ (pdf) diff --git a/source/index.rst b/source/index.rst index e5af08f..3e72e85 100644 --- a/source/index.rst +++ b/source/index.rst @@ -27,11 +27,12 @@ Table of contents: Maple/Arduino Compatibility Reference Maple Language Reference Maple Library Reference - libmaple Documentation and APIs + libmaple Command-Line Tools and APIs Troubleshooting Hardware-Specific Documentation Maple bootloader Known Problems + [Temporary] Arduino docs TOC Indices and tables ================== diff --git a/source/jtag.rst b/source/jtag.rst index 5301a18..4ef417d 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -66,6 +66,6 @@ Recommended Reading * `STM32/gdb/OpenOCD HOWTO `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet (pdf) `_ - * `Reference Manual (pdf) `_ + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/language.rst b/source/language.rst index 36cb801..d3c7895 100644 --- a/source/language.rst +++ b/source/language.rst @@ -483,11 +483,8 @@ Recommended Reading * `newlib Documentation `_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents `_ - * `Datasheet (pdf) - `_ - * `Reference Manual (pdf) - `_ - * `Programming Manual (pdf) - `_ - (assembly language and register reference) + * `All documents `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Programming Manual `_ (assembly language and + register reference) diff --git a/source/pwm.rst b/source/pwm.rst index 8d3a8d9..0f77781 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -159,6 +159,6 @@ Recommended Reading * `So You Want To Use PWM, Eh? `_ at Non-Lexical Vocables * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet (pdf) `_ - * `Reference Manual (pdf) `_ + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/spi.rst b/source/spi.rst index 3c29b79..91c165a 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -63,9 +63,7 @@ Recommended Reading * `Hardcore SPI on Arduino `_ by kik64 * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet (pdf) - `_ - * `Reference Manual (pdf) - `_ + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/usart.rst b/source/usart.rst index 19b054f..d6343e6 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -94,6 +94,6 @@ Recommended Reading * `Arduino reference on Serial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/usb.rst b/source/usb.rst index 1ce91f0..93d476e 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -185,7 +185,8 @@ Recommended Reading * Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (pdf; assembly language and register reference) + * `All documents `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Programming Manual `_ (pdf; assembly + language and register reference) -- cgit v1.2.3 From 30ac55d80c18e93f9c39a6dd850c10f9e7fd92ac Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 22 Oct 2010 21:10:34 -0400 Subject: docs --- 1 | 91 +++++++++++++++++++++++++++ Makefile | 2 +- source/adc.rst | 10 +-- source/arduino/assignment.rst | 13 ++-- source/arduino/attachinterrupt.rst | 69 +++++++------------- source/epilog.rst | 52 +++++++-------- source/external-interrupts.rst | 126 +++++++++++++++++++++++++++++++++++++ source/foo.rst | 4 +- source/gpio.rst | 6 +- source/i2c.rst | 6 +- source/index.rst | 1 + source/jtag.rst | 6 +- source/language.rst | 10 ++- source/maple-ide-install.rst | 2 +- source/maple-quickstart.rst | 2 +- source/pwm.rst | 6 +- source/spi.rst | 6 +- source/unix-toolchain.rst | 2 +- source/usart.rst | 6 +- source/usb.rst | 8 +-- 20 files changed, 309 insertions(+), 119 deletions(-) create mode 100644 1 create mode 100644 source/external-interrupts.rst diff --git a/1 b/1 new file mode 100644 index 0000000..1658600 --- /dev/null +++ b/1 @@ -0,0 +1,91 @@ +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/analogreference.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/analogwrite.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bit.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitclear.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitread.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitset.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitshift.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwiseand.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwisecompound.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwisexornot.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwrite.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/boolean.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/booleanvariables.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/braces.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/break.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/byte.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bytecast.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/changes.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/char.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/charcast.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/comments.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/comparison.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/const.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/constants.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/constrain.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/continue.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/cos.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/define.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/delay.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/delaymicroseconds.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/detachinterrupt.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/digitalread.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/digitalwrite.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/double.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/dowhile.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/else.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/float.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/floatcast.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/for.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/fpconstants.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/goto.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/highbyte.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/if.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/include.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/increment.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/incrementcompound.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/int.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/intcast.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/integerconstants.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/interrupts.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/long.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/longcast.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/loop.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/lowbyte.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/map.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/max.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/micros.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/millis.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/min.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/modulo.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/nointerrupts.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/notone.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/pointer.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/pow.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/pulsein.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/random.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/randomseed.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/return.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/scope.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/semicolon.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/serial.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/setup.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/shiftout.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/sin.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/sizeof.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/sqrt.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/static.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/string.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/stringobject.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/switchcase.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/tan.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/tone.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/unsignedchar.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/unsignedint.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/unsignedlong.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/void.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/volatile.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/while.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/word.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/wordcast.rst:: WARNING: document isn't included in any toctree +/Users/mbolivar/hack/leaf/libmaple/docs/source/arm-gcc.rst:: WARNING: document isn't included in any toctree diff --git a/Makefile b/Makefile index c182a90..eb14c90 100644 --- a/Makefile +++ b/Makefile @@ -36,7 +36,7 @@ help: clean: -rm -rf $(BUILDDIR)/* -html: doxygen +html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/source/adc.rst b/source/adc.rst index c1281be..c088652 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -70,8 +70,8 @@ Recommended Reading * `Arduino Analog Input Tutorial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Application Note on ADC Modes (pdf) `_ - * `Application Note on ADC Oversampling (pdf) `_ + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Application Note on ADC Modes (pdf) `_ + * `Application Note on ADC Oversampling (pdf) `_ diff --git a/source/arduino/assignment.rst b/source/arduino/assignment.rst index 8b851e8..1c790bb 100644 --- a/source/arduino/assignment.rst +++ b/source/arduino/assignment.rst @@ -11,7 +11,7 @@ the left of the equal sign. The single equal sign in the C++ programming language is called the assignment operator. It has a different meaning than in algebra -class where it indicated an equation or equality. The assignment +class, where it indicated an equation or equality. The assignment operator tells the microcontroller to evaluate whatever value or expression is on the right side of the equal sign, and store it in the variable to the left of the equal sign [#fgross]_. @@ -23,7 +23,7 @@ Example :: - int sensVal; // declare an integer variable named sensVal + int sensVal; // declare an integer variable named sensVal senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal @@ -56,8 +56,9 @@ See Also .. rubric:: Footnotes - Experienced C++ programmers know this to be an oversimplification - of what happens when the variable on the left hand side is an - object. See Richard Gillam's wonderful and scary `The Anatomy of - the Assignment Operator +.. [#fgross] Experienced C++ programmers know this to be an + oversimplification of what happens when the variable on the left + hand side is an object. See Richard Gillam's wonderful and scary + `The Anatomy of the Assignment Operator `_ + for more information. diff --git a/source/arduino/attachinterrupt.rst b/source/arduino/attachinterrupt.rst index 27a1d77..189141b 100644 --- a/source/arduino/attachinterrupt.rst +++ b/source/arduino/attachinterrupt.rst @@ -1,59 +1,30 @@ +.. highlight:: cpp + .. _arduino-attachinterrupt: attachInterrupt(interrupt, function, mode) ========================================== +.. doxygenfunction:: attachInterrupt +.. doxygenenum:: ExtIntTriggerMode -Description ------------ - -Specifies a function to call when an external interrupt occurs. -Replaces any previous function that was attached to the interrupt. -Most Arduino boards have two external interrupts: numbers 0 (on -digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an -additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 -(pin 18). - +.. doxygentypedef:: voidFuncPtr - -Parameters +Discussion ---------- -**interrupt**: the number of the interrupt (*int*) - - - -**function**: the function to call when the interrupt occurs; this -function must take no parameters and return nothing. This function -is sometimes referred to as an *interrupt service routine.* - - - -**mode** defines when the interrupt should be triggered. Four -contstants are predefined as valid values: - - -- **LOW** to trigger the interrupt whenever the pin is low, -- **CHANGE** to trigger the interrupt whenever the pin changes - value -- **RISING** to trigger when the pin goes from low to high, -- **FALLING** for when the pin goes from high to low. - - - -Returns -------- - -none - - +Specifies a function to call when an external interrupt occurs. +Replaces any previous function that was attached to the interrupt. +For more information on external interrupts on the Maple Note ---- -*Inside the attached function, delay() won't work and the value returned by millis() will not increment. Serial data received while in the function may be lost. You should declare as volatile any variables that you modify within the attached function.* - +Inside the attached function, delay() won't work, and the value +returned by millis() will not increment. Serial data received while in +the function may be lost. You should declare as volatile any variables +that you modify within the attached function. Using Interrupts @@ -84,18 +55,18 @@ Example :: - int pin = 13; + int maple_led_pin = 13; volatile int state = LOW; void setup() { - pinMode(pin, OUTPUT); + pinMode(maple_led_pin, OUTPUT); attachInterrupt(0, blink, CHANGE); } void loop() { - digitalWrite(pin, state); + digitalWrite(maple_led_pin, state); } void blink() @@ -104,6 +75,14 @@ Example } +Arduino Compatibility Note +-------------------------- + +Most Arduino boards have two external interrupts: numbers 0 (on +digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an +additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 +(pin 18). + See also -------- diff --git a/source/epilog.rst b/source/epilog.rst index 73aab6d..4234dd9 100644 --- a/source/epilog.rst +++ b/source/epilog.rst @@ -5,44 +5,38 @@ .. _forum: http://forums.leaflabs.com .. _contact: http://leaflabs.com/contact/ - -.. _stm32-all: http://www.st.com/mcu/devicedocs-STM32F103RB-110.html -.. _stm32-programming: http://www.st.com/stonline/products/literature/pm/15491.pdf -.. _stm32-adc-modes: http://www.st.com/stonline/products/literature/an/16840.pdf -.. _stm32-adc-oversampling: http://www.st.com/stonline/products/literature/an/14183.pdf -.. _full-manual: http://www.st.com/stonline/products/literature/rm/13902.pdf -.. _datasheet: http://www.st.com/stonline/products/literature/ds/13587.pdf +.. _contact us directly: http://leaflabs.com/contact/ .. Arduino built-in functions .. _setup(): http://arduino.cc/en/Reference/Setup -.. _loop(): http://arduino.cc/en/Reference/Loop +.. _loop(): http://arduino.cc/en/Reference/Loop -.. _pinMode(): http://arduino.cc/en/Reference/PinMode +.. _pinMode(): http://arduino.cc/en/Reference/PinMode .. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite -.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead +.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead .. _analogReference(): http://arduino.cc/en/Reference/AnalogReference -.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead -.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite +.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead +.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite -.. _tone(): http://arduino.cc/en/Reference/Tone -.. _noTone(): http://arduino.cc/en/Reference/NoTone +.. _tone(): http://arduino.cc/en/Reference/Tone +.. _noTone(): http://arduino.cc/en/Reference/NoTone .. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut -.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn +.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn -.. _millis(): http://arduino.cc/en/Reference/Millis -.. _micros(): http://arduino.cc/en/Reference/Micros -.. _delay(): http://arduino.cc/en/Reference/Delay +.. _millis(): http://arduino.cc/en/Reference/Millis +.. _micros(): http://arduino.cc/en/Reference/Micros +.. _delay(): http://arduino.cc/en/Reference/Delay .. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds -.. _min(): http://arduino.cc/en/Reference/Min -.. _max(): http://arduino.cc/en/Reference/Max -.. _abs(): http://arduino.cc/en/Reference/Abs +.. _min(): http://arduino.cc/en/Reference/Min +.. _max(): http://arduino.cc/en/Reference/Max +.. _abs(): http://arduino.cc/en/Reference/Abs .. _constrain(): http://arduino.cc/en/Reference/Constrain -.. _map(): http://arduino.cc/en/Reference/Map -.. _pow(): http://arduino.cc/en/Reference/Pow +.. _map(): http://arduino.cc/en/Reference/Map +.. _pow(): http://arduino.cc/en/Reference/Pow .. _sqrt(): http://arduino.cc/en/Reference/Sqrt .. _sin(): http://arduino.cc/en/Reference/Sin @@ -50,18 +44,18 @@ .. _tan(): http://arduino.cc/en/Reference/Tan .. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed -.. _random(): http://arduino.cc/en/Reference/Random +.. _random(): http://arduino.cc/en/Reference/Random -.. _lowByte(): http://arduino.cc/en/Reference/LowByte +.. _lowByte(): http://arduino.cc/en/Reference/LowByte .. _highByte(): http://arduino.cc/en/Reference/HighByte -.. _bitRead(): http://arduino.cc/en/Reference/BitRead +.. _bitRead(): http://arduino.cc/en/Reference/BitRead .. _bitWrite(): http://arduino.cc/en/Reference/BitWrite -.. _bitSet(): http://arduino.cc/en/Reference/BitSet +.. _bitSet(): http://arduino.cc/en/Reference/BitSet .. _bitClear(): http://arduino.cc/en/Reference/BitClear -.. _bit(): http://arduino.cc/en/Reference/Bit +.. _bit(): http://arduino.cc/en/Reference/Bit .. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt .. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt -.. _interrupts(): http://arduino.cc/en/Reference/Interrupts +.. _interrupts(): http://arduino.cc/en/Reference/Interrupts .. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst new file mode 100644 index 0000000..bc9d6cd --- /dev/null +++ b/source/external-interrupts.rst @@ -0,0 +1,126 @@ +.. highlight:: cpp + +.. _external-interrupts: + +External Interrupts +=================== + +External interrupts can be used to trigger routines to run in response +to changes in voltage on a pin. Each GPIO pin on the Maple can be used +to detect transitions such as when the voltage goes from low to high, +or from high to low. This technique can be used to avoid unnecessary +polling of the state of a pin. + +.. _contents: Contents + :local: + + +Overview +-------- + +External interrupts are often used to detect when events happen +outside of the microcontroller. These can be used to tell the Maple +when events happen, such as when a sensor has data ready to be read, +or when a button has been pushed. When such an event happens, an +interrupt is raised and the Maple can react to it with a preset +*interrupt handler*. + +Every GPIO pin on the Maple can be used as an external interrupt, +subject to certain constraints; there can be a maximum of 16 different +external interrupts set up at a time on the Maple. This is because the +external interrupt lines on the STM32 are multiplexed between GPIO +ports. In effect, this means that every pin on the Maple maps to a +certain EXTI line, and within that EXTI line, only one of the pins +that maps to it can be used as an external interrupt at a time. + +The following table shows which pins can be used on which lines. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Maple pins + * - EXTI0 + - 2, 15, 27 + * - EXTI1 + - 3, 16, 28 + * - EXTI2 + - 1, 17, 25 + * - EXTI3 + - 0, 18 + * - EXTI4 + - 10, 19 + * - EXTI5 + - 4, 13, 20 + * - EXTI6 + - 5, 12, 35 + * - EXTI7 + - 9, 11, 36 + * - EXTI8 + - 6, 14, 37 + * - EXTI9 + - 7, 25, 28 + * - EXTI10 + - 8, 26, 29 + * - EXTI11 + - 30 + * - EXTI12 + - 31 + * - EXTI13 + - 21, 32 + * - EXTI14 + - 22, 33 + * - EXTI15 + - 23, 34 + +.. note:: + + You should set the :ref:`pin mode ` of your + desired pin to an input mode (e.g ``INPUT`` or ``INPUT_FLOATING``, + ``INPUT_PULLUP``, ``INPUT_PULLDOWN``). + + +Function Reference +------------------ + +.. doxygenfunction:: attachInterrupt + +.. doxygenfunction:: detachInterrupt + +.. doxygenenum:: ExtIntTriggerMode + +.. doxygentypedef:: voidFuncPtr + + +Code example +------------ + +Blink the LED on every transition:: + + int pin = 13; + volatile int state = LOW; + + void setup() { + pinMode(pin, OUTPUT); + pinMode(0, INPUT_FLOATING); + attachInterrupt(0, blink, CHANGE); + } + + void loop() { + digitalWrite(pin, state); + } + + void blink() { + state = !state; + } + + +Recommended Reading +------------------- + +* STMicro documentation for STM32F103RB microcontroller: + + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/foo.rst b/source/foo.rst index d2ac4c6..769e666 100644 --- a/source/foo.rst +++ b/source/foo.rst @@ -15,9 +15,9 @@ This is the index of the imported Arduino docs. Arithmetic Arrays Assignment + attachInterrupt() + bit -.. attachinterrupt -.. bit .. bitclear .. bitread .. bitset diff --git a/source/gpio.rst b/source/gpio.rst index bd562a7..7a9031a 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -100,6 +100,6 @@ Recommended Reading STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/i2c.rst b/source/i2c.rst index 764a342..ddb2ac9 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -80,9 +80,9 @@ Recommended Reading * `Arduino i2c/TWI reference `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) * `Application Note on Advanced I2C Usage `_ (pdf) diff --git a/source/index.rst b/source/index.rst index 3e72e85..ac92d4b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -30,6 +30,7 @@ Table of contents: libmaple Command-Line Tools and APIs Troubleshooting Hardware-Specific Documentation + External Interrupts Maple bootloader Known Problems [Temporary] Arduino docs TOC diff --git a/source/jtag.rst b/source/jtag.rst index 4ef417d..9b8ee14 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -66,6 +66,6 @@ Recommended Reading * `STM32/gdb/OpenOCD HOWTO `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/language.rst b/source/language.rst index d3c7895..5a2efad 100644 --- a/source/language.rst +++ b/source/language.rst @@ -213,7 +213,6 @@ Arduino Documentation Links typedef uint16 word; -.. setup()/loop() are part of the standard rst_epilog in conf.py .. _if: http://arduino.cc/en/Reference/If .. _if...else: http://arduino.cc/en/Reference/Else .. _for: http://arduino.cc/en/Reference/For @@ -483,8 +482,7 @@ Recommended Reading * `newlib Documentation `_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (assembly language and - register reference) + * `All documents `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Programming Manual `_ (assembly language and register reference) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 3c3fffe..ce50c49 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -9,7 +9,7 @@ If you still can't get the IDE installed after reading this page, check the :ref:`troubleshooting page ` for help with some common problems. If all else fails, try our `forum`_, or `contact -us directly `_! +us directly`_\ ! .. contents:: Contents :local: diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 4d646d7..6d99a4a 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -13,7 +13,7 @@ that computer. If you have trouble along the way, try the :ref:`troubleshooting page ` for help with some common problems. If all else -fails, try our `forum`_, or `contact us directly `_! +fails, try our `forum`_, or `contact`_ us directly! .. contents:: Contents :local: diff --git a/source/pwm.rst b/source/pwm.rst index 0f77781..178d103 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -159,6 +159,6 @@ Recommended Reading * `So You Want To Use PWM, Eh? `_ at Non-Lexical Vocables * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/spi.rst b/source/spi.rst index 91c165a..4cfd7e7 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -63,7 +63,7 @@ Recommended Reading * `Hardcore SPI on Arduino `_ by kik64 * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 295090e..b595f70 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -19,7 +19,7 @@ editing your shell startup script (.bashrc, .tcshrc, etc.) and using generic installation/setup issues, the `IDE install `_ and :ref:`troubleshooting` pages may be helpful. If all else fails, try -our `forum`_, or `contact us directly `_! +our `forum`_, or `contact us directly`_\ ! We currently have instructions for 32- and 64-bit Linux and OS X Snow Leopard. If you're on another Unix platform, Windows, or an earlier diff --git a/source/usart.rst b/source/usart.rst index d6343e6..19b054f 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -94,6 +94,6 @@ Recommended Reading * `Arduino reference on Serial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `All `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/usb.rst b/source/usb.rst index 93d476e..baabde5 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -185,8 +185,8 @@ Recommended Reading * Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (pdf; assembly + * `All documents `_ + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Programming Manual `_ (pdf; assembly language and register reference) -- cgit v1.2.3 From 2d429e75ce69e77f8c95490ac03881ec9aa0354a Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 25 Oct 2010 21:15:28 -0400 Subject: arduino language reference nearing completion, properly CC-BY-SA 3.0 attributed --- 1 | 91 ----------- Doxyfile | 2 +- source/adc.rst | 6 +- source/arduino/abs.rst | 18 +- source/arduino/analogread.rst | 109 +++++++------ source/arduino/analogreference.rst | 66 -------- source/arduino/analogwrite.rst | 223 +++++++++++++++---------- source/arduino/arithmetic.rst | 84 ++++++---- source/arduino/arithmeticcompound.rst | 43 +++++ source/arduino/array.rst | 14 +- source/arduino/assignment.rst | 9 +- source/arduino/attachinterrupt.rst | 66 ++++---- source/arduino/bit.rst | 29 ++-- source/arduino/bitclear.rst | 34 ++-- source/arduino/bitread.rst | 32 ++-- source/arduino/bitset.rst | 33 ++-- source/arduino/bitshift.rst | 148 +++++++++-------- source/arduino/bitwiseand.rst | 230 -------------------------- source/arduino/bitwisecompound.rst | 299 +++++++++++++++++----------------- source/arduino/bitwisemath.rst | 183 +++++++++++++++++++++ source/arduino/bitwisexornot.rst | 51 ------ source/arduino/bitwrite.rst | 45 ++--- source/arduino/boolean.rst | 106 ++++++------ source/arduino/booleanvariables.rst | 59 ++++--- source/arduino/braces.rst | 135 +++++++-------- source/arduino/break.rst | 12 +- source/arduino/byte.rst | 26 +-- source/arduino/bytecast.rst | 35 ++-- source/arduino/cc-attribution.txt | 9 + source/arduino/changes.rst | 93 ----------- source/arduino/char.rst | 50 +++--- source/arduino/charcast.rst | 29 ++-- source/arduino/comments.rst | 69 +++++--- source/arduino/comparison.rst | 110 ++++++++----- source/arduino/const.rst | 52 +++--- source/arduino/constants.rst | 189 +++++++++++++++++++-- source/arduino/constrain.rst | 46 +++--- source/arduino/continue.rst | 16 +- source/arduino/cos.rst | 31 ++-- source/arduino/define.rst | 94 ++++------- source/arduino/delay.rst | 95 ++++------- source/arduino/delaymicroseconds.rst | 81 +++------ source/arduino/detachinterrupt.rst | 32 ++-- source/arduino/digitalread.rst | 76 +++------ source/arduino/double.rst | 36 ++-- source/arduino/dowhile.rst | 33 ++-- source/arduino/else.rst | 84 ++++------ source/arduino/float.rst | 85 +++------- source/arduino/floatcast.rst | 53 ++---- source/arduino/for.rst | 194 ++++++++++++---------- source/arduino/fpconstants.rst | 36 ---- source/arduino/goto.rst | 158 +++++++++++++----- source/arduino/highbyte.rst | 46 +++--- source/arduino/if.rst | 125 ++++++-------- source/arduino/include.rst | 88 ++++++---- source/arduino/increment.rst | 63 +++---- source/arduino/incrementcompound.rst | 49 ------ source/arduino/int.rst | 105 +++++------- source/arduino/intcast.rst | 38 ++--- source/arduino/integerconstants.rst | 130 --------------- source/arduino/long.rst | 62 +++---- source/arduino/longcast.rst | 40 ++--- source/arduino/loop.rst | 49 +++--- source/arduino/max.rst | 47 ++---- source/arduino/min.rst | 50 +++--- source/arduino/modulo.rst | 60 +++---- source/arduino/pinmode.rst | 14 +- source/arduino/pointer.rst | 17 +- source/arduino/pow.rst | 45 ++--- source/arduino/return.rst | 65 +++----- source/arduino/scope.rst | 63 +++---- source/arduino/semicolon.rst | 15 +- source/arduino/serial.rst | 3 + source/arduino/sin.rst | 40 ++--- source/arduino/sizeof.rst | 69 ++++---- source/arduino/sq.rst | 39 +++++ source/arduino/sqrt.rst | 33 ++-- source/arduino/static.rst | 91 +++++------ source/arduino/string.rst | 186 +++++++++------------ source/arduino/stringclass.rst | 6 + source/arduino/switchcase.rst | 89 +++++----- source/arduino/variables.rst | 188 +++++++++++++++++++++ source/arduino/while.rst | 2 +- source/arm-gcc.rst | 27 ++- source/bootloader.rst | 10 +- source/compatibility.rst | 2 +- source/conf.py | 2 +- source/foo.rst | 195 +++++++++++----------- source/gpio.rst | 7 +- source/ide.rst | 11 ++ source/index.rst | 7 +- source/language.rst | 8 +- source/libmaple.rst | 1 + source/pwm.rst | 26 ++- source/timers.rst | 5 + source/wirish.rst | 9 + source/wirish/pwmwrite.rst | 52 ++++++ source/wirish/types.rst | 6 + 98 files changed, 3059 insertions(+), 3165 deletions(-) delete mode 100644 1 delete mode 100644 source/arduino/analogreference.rst create mode 100644 source/arduino/arithmeticcompound.rst delete mode 100644 source/arduino/bitwiseand.rst create mode 100644 source/arduino/bitwisemath.rst delete mode 100644 source/arduino/bitwisexornot.rst create mode 100644 source/arduino/cc-attribution.txt delete mode 100644 source/arduino/changes.rst delete mode 100644 source/arduino/fpconstants.rst delete mode 100644 source/arduino/incrementcompound.rst delete mode 100644 source/arduino/integerconstants.rst create mode 100644 source/arduino/sq.rst create mode 100644 source/arduino/stringclass.rst create mode 100644 source/arduino/variables.rst create mode 100644 source/ide.rst create mode 100644 source/wirish.rst create mode 100644 source/wirish/pwmwrite.rst create mode 100644 source/wirish/types.rst diff --git a/1 b/1 deleted file mode 100644 index 1658600..0000000 --- a/1 +++ /dev/null @@ -1,91 +0,0 @@ -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/analogreference.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/analogwrite.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bit.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitclear.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitread.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitset.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitshift.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwiseand.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwisecompound.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwisexornot.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bitwrite.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/boolean.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/booleanvariables.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/braces.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/break.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/byte.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/bytecast.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/changes.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/char.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/charcast.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/comments.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/comparison.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/const.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/constants.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/constrain.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/continue.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/cos.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/define.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/delay.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/delaymicroseconds.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/detachinterrupt.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/digitalread.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/digitalwrite.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/double.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/dowhile.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/else.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/float.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/floatcast.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/for.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/fpconstants.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/goto.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/highbyte.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/if.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/include.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/increment.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/incrementcompound.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/int.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/intcast.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/integerconstants.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/interrupts.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/long.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/longcast.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/loop.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/lowbyte.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/map.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/max.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/micros.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/millis.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/min.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/modulo.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/nointerrupts.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/notone.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/pointer.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/pow.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/pulsein.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/random.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/randomseed.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/return.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/scope.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/semicolon.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/serial.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/setup.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/shiftout.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/sin.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/sizeof.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/sqrt.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/static.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/string.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/stringobject.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/switchcase.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/tan.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/tone.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/unsignedchar.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/unsignedint.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/unsignedlong.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/void.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/volatile.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/while.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/word.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino/wordcast.rst:: WARNING: document isn't included in any toctree -/Users/mbolivar/hack/leaf/libmaple/docs/source/arm-gcc.rst:: WARNING: document isn't included in any toctree diff --git a/Doxyfile b/Doxyfile index 4016c05..88b8764 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1369,7 +1369,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = __cplusplus # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/source/adc.rst b/source/adc.rst index c088652..6bbbac2 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -59,7 +59,11 @@ range; opamps and other powered components can also be used. Function Reference ------------------ -TODO function reference (figure out Doxygen first) +.. doxygenfunction:: analogRead + +.. doxygenfunction:: pinMode + +.. doxygenenum:: WiringPinMode .. _adc-recommended-reading: diff --git a/source/arduino/abs.rst b/source/arduino/abs.rst index 5d699ae..ed7296a 100644 --- a/source/arduino/abs.rst +++ b/source/arduino/abs.rst @@ -11,7 +11,7 @@ Description Parameters ---------- -**x**: the number +**x**: the number. Returns ------- @@ -24,10 +24,16 @@ Warning ------- Because of the way ``abs()`` is implemented, avoid using other -functions or causing side effects inside the brackets, as it may lead -to incorrect results :: +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: abs(a++); // avoid this - yields incorrect results - - a++; // use this instead - - abs(a); // keep other math outside the function + + abs(a); // use this instead - + a++; // keep other operations outside abs() + + +Arduino Compatibility +--------------------- + +Maple's implementation of ``abs()`` is compatible with Arduino. diff --git a/source/arduino/analogread.rst b/source/arduino/analogread.rst index d0fa5a1..9577c62 100644 --- a/source/arduino/analogread.rst +++ b/source/arduino/analogread.rst @@ -5,15 +5,18 @@ analogRead() ============ +Used to perform ADC conversion. -Signature ---------- +.. contents:: Contents + :local: -``int analogRead(int pin);`` +Library Documentation +--------------------- +.. doxygenfunction:: analogRead -Description ------------ +Discussion +---------- Reads the value from the specified analog pin. The Maple board contains a 16-channel, 12-bit analog to digital converter. This means @@ -24,36 +27,26 @@ interfere with getting full accuracy and precision. For more information, see :ref:`adc`. Before calling analogRead() on a pin, that pin must first be -configured for analog input, using :ref:`arduino-pinMode`. - -The input range and resolution can be changed using -:ref:`arduino-analogReference`. +configured for analog input, using :ref:`arduino-pinMode` (you only +have to do this once, so it's usually done in :ref:`arduino-setup`\ ). It takes about 0.8 microseconds (.0000008 seconds) to read an analog input, so the maximum sample rate using this function is approximately -1.3 million samples per second [#fsamp]_. +1.3 million samples per second\ [#fsamp]_. -Parameters ----------- +Parameter Discussion +-------------------- -**pin** +The pin parameter is the number of the analog input pin to read from. +Header pins on the Maple with ADC functionality (marked as "AIN" on +the silkscreen) are: - The number of the analog input pin to read from. Header pins on the - Maple with ADC functionality (marked as "AIN" on the silkscreen) - are: - - 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 - - Note that pins 3, 27, and 28 are not marked AIN on the silkscreen - for Maple revisions through Rev 5, however, they **do work** as - analog input pins. - -Returns -------- - -Converted input voltage as an ``int``, with value 0 to 4095, inclusive. + 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 +Note that pins 3, 27, and 28 are not marked AIN on the silkscreen +for Maple revisions through Rev 5, however, they **do work** as +analog input pins. Note ---- @@ -61,7 +54,7 @@ Note If the analog input pin is not connected to anything, the value returned by analogRead() will fluctuate based on a number of factors (e.g. the values of the other analog inputs, how close your hand is to -the board, etc.). +the board, etc.) in a seemingly random way. Example @@ -70,43 +63,65 @@ Example :: - int analogPin = 3; // potentiometer wiper (middle terminal) connected to analog pin 3 - // outside leads to ground and +3.3V + int analogPin = 3; // potentiometer wiper (middle terminal) connected + // to analog pin 3. outside leads to ground and +3.3V int val = 0; // variable to store the value read void setup() { - pinMode(analogPin, INPUT_ANALOG); - SerialUSB.begin(); + pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input + SerialUSB.begin(); // set up usb virtual COM port } void loop() { val = analogRead(analogPin); // read the input pin - SerialUSB.println(val); // debug value + SerialUSB.println(val); // print the value, for debugging with + // a serial monitor } -Arduino Compatibility Note --------------------------- +Arduino Compatibility +--------------------- The Arduino board contains a 6 channel (8 channels on the Mini and -Nano, 16 on the Mega), 10-bit analog to digital converter. This means -that it will map input voltages between 0 and 5 volts into integer -values between 0 and 1023. This yields a resolution between readings -of: 5 volts / 1024 units or, .0049 volts (4.9 mV) per unit. On the -Arduino, the input range and resolution can be changed using their -implementation of `analogReference() -`_\ . - -On the Arduino, it takes about 100 microseconds (0.0001 s) to read an -analog input, so the maximum reading rate is about 10,000 times a -second. +Nano, 16 on the Mega), 10-bit analog to digital converter with an +input voltage range of 0V--5V. This means that it will map input +voltages between 0 and 5 volts (which is **larger** than Maple's range +of 0V-3.3V) into integer values between 0 and 1023 (which is +**smaller** than the Maple's range of 0--4095). + +This yields a theoretical resolution between readings of: 5 volts / +1024 units or .0049 volts (4.9 mV) per unit on Arduino boards, which +is larger, and thus less precise, than Maple's 0.0008 volts (0.8 mV). + +If your program expects Arduino-style 10-bit ADC, you can :ref:`right +shift ` the value of a Maple readout by 2, like so:: + + // right shift means that the result will be between 0 and 1023; + // be aware that you're losing a lot of precision if you do this + int adc_reading = analogRead(pin) >> 2; + +On the Arduino, the input range and resolution can be changed using +their implementation of `analogReference() +`_\ . Because of the +way its hardware (as of Rev 5) was designed, it's not possible to +implement analogReference on the Maple, so this function doesn't +exist. If your inputs lie in a different voltage range than 0V--3.3V, +you'll need to bring them into that range before using analogRead. +Some basic tools to accomplish this are `resistor dividers +`_ and `Zener diodes +`_\ +. However, opamps and other powered components can also be used if +greater precision is required. + +Finally, On the Arduino, it takes significantly longer to read analog +input: about 100 microseconds (0.0001 s), so the maximum reading rate +is 10,000 times a second. See also -------- - :ref:`ADC note ` -- :ref:`analogReference ` - `(Arduino) Tutorial: Analog Input Pins `_ diff --git a/source/arduino/analogreference.rst b/source/arduino/analogreference.rst deleted file mode 100644 index 9a25169..0000000 --- a/source/arduino/analogreference.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _arduino-analogreference: - -analogReference(type) -===================== - -Description ------------ - -Configures the reference voltage used for analog input (i.e. the -value used as the top of the input range). The options are: - - - - -- DEFAULT: the default analog reference of 5 volts (on 5V Arduino - boards) or 3.3 volts (on 3.3V Arduino boards) -- INTERNAL: an built-in reference, equal to 1.1 volts on the - ATmega168 or ATmega328 and 2.56 volts on the ATmega8. -- EXTERNAL: the voltage applied to the AREF pin is used as the - reference. - - - -Parameters ----------- - -type: which type of reference to use (DEFAULT, INTERNAL, or -EXTERNAL). - - - -Returns -------- - -None. - - - -Warning -------- - -**If you're using an external reference voltage (applied to the AREF pin), you must set the analog reference to EXTERNAL before calling analogRead().** -Otherwise, you will short together the active reference voltage -(internally generated) and the AREF pin, possibly damaging the -microcontroller on your Arduino board. - - - -Alternatively, you can connect the external reference voltage to -the AREF pin through a 5K resistor, allowing you to switch between -external and internal reference voltages. Note that the resistor -will alter the voltage that gets used as the reference because -there is an internal 32K resistor on the AREF pin. The two act as a -voltage divider, so, for example, 2.5V applied through the resistor -will yield 2.5 \* 32 / (32 + 5) = ~2.2V at the AREF pin. - - - -See also --------- - - -- `Description of the analog input pins `_ -- `analogRead `_\ () - - diff --git a/source/arduino/analogwrite.rst b/source/arduino/analogwrite.rst index 64ecd5b..d04f485 100644 --- a/source/arduino/analogwrite.rst +++ b/source/arduino/analogwrite.rst @@ -1,116 +1,161 @@ +.. highlight:: cpp + .. _arduino-analogwrite: analogWrite() ============= -TODO - -In libmaple, analogWrite is just a convenience alias for -:ref:`pwmWrite`. This is because PWM is not true analog output (i.e., -is not the output of a DAC), so the name was badly-chosen; however, -for the sake of compatibility, the alias was provided. - -.. doxygenfunction:: pwmWrite - -Description ------------ - -Writes an analog value -(`PWM wave `_) to a pin. Can be -used to light a LED at varying brightnesses or drive a motor at -various speeds. After a call to **analogWrite()**, the pin will -generate a steady square wave of the specified duty cycle until the -next call to **analogWrite()** (or a call to **digitalRead()** or -**digitalWrite()** on the same pin). The frequency of the PWM -signal is approximately 490 Hz. - - - -On most Arduino boards (those with the ATmega168 or ATmega328), -this function works on pins 3, 5, 6, 9, 10, and 11. On the Arduino -Mega, it works on pins 2 through 13. Older Arduino boards with an -ATmega8 only support analogWrite() on pins 9, 10, and 11. You do -not need to call pinMode() to set the pin as an output before -calling analogWrite(). - - - -The *analogWrite* function has nothing whatsoever to do with the -analog pins or the *analogRead* function. - - - -Syntax ------- - -analogWrite(pin, value) - - - -Parameters ----------- - -pin: the pin to write to. - - - -value: the duty cycle: between 0 (always off) and 255 (always on). - - - -Returns -------- +.. note:: + + On the Maple, calling analogWrite() is the same as calling + :ref:`wirish-pwmwrite`\ ; see that function's documentation for more + information. + + This is because PWM is not true analog output (i.e., is not the + output of a `DAC + `_\ ), so + the function is badly named. For instance, **analogWrite() has + absolutely nothing to do with** :ref:`arduino-analogread`\ , which + is potentially confusing. + + The alias of analogWrite() to pwmWrite() is provided (sigh) for the + sake of compatibility with Arduino, but we recommend using + :ref:`wirish-pwmwrite` when writing new software, for clarity. + +.. contents:: Contents + :local: + +Arduino Compatibility +--------------------- + +There are a few important differences between Arduino's `analogWrite() +`_ and Maple's +:ref:`wirish-pwmwrite` that you should keep in mind. In each case, we +have some recommendations you can use to help converting from Arduino +to Maple. + +Difference 1: Duty cycle range is different +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first and most important difference is that the largest possible +value for the duty cycle is much bigger on the Maple. Using Arduino's +analogWrite(), the duty cycle ranges between 0--255 (always off -- +always on)\ [#fbytemax]_\ . Using Maple's pwmWrite(), the duty cycle +ranges from 0--65,535 by default\ [#fuint16max]_\ . + +This is a good thing! The greater range of values on the Maple gives +you much more precise control over the duty cycle of your PWM output. + +If you're porting code from the Arduino and want a quick-and-dirty +fix, one solution is to :ref:`map ` the argument to +analogWrite into the right range:: + + // Arduino code: + analogWrite(pin, duty); + + // Becomes Maple code: + analogWrite(pin, map(duty, 0, 255, 0, 65535)); + +This will convert values in the range 0-255 to values in the range +0--65,635, which is the correct default range for all of the timers +which control PWM output. See the :ref:`timers reference ` +for more information. + +Another fix is to consult the :ref:`pin mapping mega table +` to find the timer which controls PWM on the +pin you're using, then set that Timer's overflow to 255. Subsequent +calls to analogWrite() should work as on the Arduino (with the same +loss of precision). Note, however, that that affects the overflow for +the **entire timer**, so other code relying on that timer (such as any +:ref:`interrupts ` the timer controls) will +likely need to be modified as well. + +Difference 2: You must use pinMode() to set up PWM +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The second difference is that on the Maple, you **must** set up the pin +for PWM output using :ref:`arduino-pinmode`\ , with argument ``PWM``. +This should just be one extra line of code in your +:ref:`arduino-setup` function. Example:: + + void setup() { + // set up pin 9 for PWM + pinMode(9, PWM); + } -nothing +This also means that you can't later call :ref:`arduino-digitalread` +or :ref:`arduino-digitalwrite` on that pin (unless some time in +between, you use pinMode() to reconfigure that pin for ``INPUT`` or +``OUTPUT``; see the :ref:`arduino-pinmode` page for more information). +Difference 3: No PWM on pin 10 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, +9, 11, 12, and 14, or twelve pins in total. That is at least as +*many* PWM pins as any Arduino board, but there are differences in +*which* pins support it. -Notes and Known Issues ----------------------- +* On **most Arduino boards** (those with the ATmega168 or ATmega328; + this includes the **Arduino Uno**), this function works on pins 3, + 5, 6, 9, 10, and 11, or six pins total. Note that these boards + support PWM on pin 10, while Maple does not. -The PWM outputs generated on pins 5 and 6 will have -higher-than-expected duty cycles. This is because of interactions -with the millis() and delay() functions, which share the same -internal timer used to generate those PWM outputs. This will be -noticed mostly on low duty-cycle settings (e.g 0 - 10) and may -result in a value of 0 not fully turning off the output on pins 5 -and 6. +* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins + total. Note that this board supports PWM on pins 4, 10, and 13, + while the Maple does not. Maple supports PWM on pins 0, 1, and 14, + which the Mega does not, making the total number of pins supporting + PWM equal on these boards. +* **Older Arduino boards** with an ATmega8 only support analogWrite() on + pins 9, 10, and 11. Maple does not support PWM on pin 10. +In all cases, Arduino boards support PWM on pin 10, unlike Maple. We +did our best to make PWM as pin-compatible as possible; however, +circuit layout constraints prevented us from achieving perfect +compatibility. -Example -------- +The "safest" pins to use for PWM output are pins 9 and 11. These pins +work on any Arduino board and on Maple. The "safe" pins, which work +on most recent Arduino boards, the Arduino Mega and the Maple, are +pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as +portable as possible between Maple and Arduino, we recommend using the +"safest" pins first, then the "safe" pins, as necessary. -Sets the output to the LED proportional to the value read from the -potentiometer. +Difference 4: PWM frequency +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The frequency of the PWM signal (i.e., the frequency of a complete +on/off cycle) on the Arduino is approximately 490 Hz. +On the Maple, the frequency is configurable, defaulting to about 1100 +Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of +the timer which controls PWM output on the particular pin (\ +:ref:`the PWM tutorial has the details `\ ). -:: +If your application absolutely requires Arduino's PWM frequency (it +probably doesn't), then the steps are: - - int ledPin = 9; // LED connected to digital pin 9 - int analogPin = 3; // potentiometer connected to analog pin 3 - int val = 0; // variable to store the read value - - void setup() - { - pinMode(ledPin, OUTPUT); // sets the pin as output - } - - void loop() - { - val = analogRead(analogPin); // read the input pin - analogWrite(ledPin, val / 4); // analogRead values go from 0 to 1023, analogWrite values from 0 to 255 - } +1. Figure out which timer controls PWM output on your pin (\ :ref:`this table ` is your friend here). Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4. +2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of approximately 490 Hz. +Be aware that this will change the period for the **entire timer**\ , +and will affect anything else in your program that depends on that +timer. One example is :ref:`interrupts `\ . +You've been :ref:`warned `\ . See also -------- +- :ref:`Maple PWM tutorial ` -- `analogRead `_\ () -- `Tutorial: PWM `_ +.. rubric:: Footnotes +.. [#fbytemax] This is because the value for the duty cycle on Arduino + must fit in 1 byte of memory, and an unsigned (i.e., nonnegative) + integer with size 1 byte can hold the values between 0 and 255. +.. [#fuint16max] This is because the value for the duty cycle on the + Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) + integer with size 2 bytes can hold the values between 0 and 65,535. diff --git a/source/arduino/arithmetic.rst b/source/arduino/arithmetic.rst index cbe3059..8fb9771 100644 --- a/source/arduino/arithmetic.rst +++ b/source/arduino/arithmetic.rst @@ -5,6 +5,9 @@ Addition, Subtraction, Multiplication, & Division ================================================= +.. contents:: Contents + :local: + Description ----------- @@ -17,17 +20,20 @@ This also means that the operation can overflow if the result is larger than that which can be stored in the data type (e.g. adding 1 to an :ref:`arduino-int` with the value 2147483647 gives -2147483648). If the operands are of different types, the "larger" -type is used for the calculation. - -(The specifics of these rules are beyond the scope of this -documentation; for more information, see `The C++ Programming Language -`_\ , by Bjarne -Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks -entry on C++ type conversion -`_\ -. For more information on how computers represent integers, see the -Wikipedia page on `two's complement -`_\ ). +type is used for the calculation. + +.. _arduino-arithmetic-typeconversion: + +.. note:: The specifics of these rules are beyond the scope of this + documentation; for more information, see `The C++ Programming + Language `_\ , by Bjarne + Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks + entry on C++ type conversion + `_. + +.. note:: For more information on how computers represent integers, + see the Wikipedia page on `two's complement + `_. If one of the numbers (operands) are of the type **float** or of type **double**, floating point math will be used for the @@ -55,30 +61,18 @@ Syntax result = value1 / value2; -Parameters: ------------ +Parameters +---------- **value1**: any numeric variable or constant **value2**: any numeric variable or constant +Programming Tips +---------------- -Arduino Compatibility Note --------------------------- - -Since the STM32 processor on the Maple is a 32-bit machine, the int -type overflows at a much higher value on Maple than on Arduino. In -particular, on Maple, ints do not overflow (become negative) until -they reach 2,147,483,648; on the Arduino, they overflow at 32,767. -Because of this, programs running on Maple are much less likely to run -into overflow issues. - - -Programming Tips: ------------------ - -- Know that :ref:`integer constants ` - default to :ref:`int `, so some constant calculations +- Know that :ref:`integer constants ` + default to :ref:`int `, so some constant calculations may overflow (e.g., 200000 * 5000000 will yield a negative result). - Choose variable sizes that are large enough to hold the largest @@ -93,12 +87,40 @@ Programming Tips: (the STM32 has no floating point hardware, so all floating point calculations have to be done in software). -- Use the cast operator e.g. (int)myFloat to convert one variable type +- Use cast operator, e.g. ``(int)myFloat`` to convert one variable type to another on the fly. +Arduino Compatibility +--------------------- + +Since the STM32 processor on the Maple is a 32-bit machine, the int +type overflows at a much higher value on Maple than on Arduino. In +particular, on Maple, ints do not overflow (become negative) until +they reach 2,147,483,648; on the Arduino, they overflow at 32,767. +Because of this, programs running on Maple are much less likely to run +into overflow issues. The following table summarizes the sizes and +ranges of integer datatypes on the Maple (the ranges of long long +types are approximate): + +.. _arduino-arithmetic-int-sizes: + +.. csv-table:: + :header: Datatype, Unsigned range, Signed range, Size (bytes) + :widths: 8, 12, 17, 8 + + ``char``, 0 --- 255, -128 --- 127, 1 + ``short``, "0 --- 65,535", "-32,768 --- 32,767", 2 + ``int``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 + ``long``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 + ``long long``, "0 --- 1.8*10\ :sup:`19`\ " (approx.), "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 + See Also -------- -- `libmaple_types.h `_ +- The individual sizes (in bits) of various available types are + defined in `libmaple_types.h + `_\ + . +- :ref:`sizeof `\ () diff --git a/source/arduino/arithmeticcompound.rst b/source/arduino/arithmeticcompound.rst new file mode 100644 index 0000000..a2c5b89 --- /dev/null +++ b/source/arduino/arithmeticcompound.rst @@ -0,0 +1,43 @@ +.. highlight:: cpp + +.. _arduino-arithmeticcompound: + +Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) +=============================================================== + +Description +----------- + +Perform a mathematical operation on a variable with another constant +or variable. These operators are just a convenient shorthand:: + + x += y; // equivalent to the expression x = x + y; + x -= y; // equivalent to the expression x = x - y; + x *= y; // equivalent to the expression x = x * y; + x /= y; // equivalent to the expression x = x / y; + +Here is an example:: + + int x = 2; + int y = 10; + + x += 4; // x now contains 6 + x -= 3; // x now contains 3 + x *= y; // x now contains 30 + x /= 2; // x now contains 15 + x += max(20, 6); // x now contains 35 + x -= sq(5); // x now contains 15 + +Parameters +---------- + +**x**: a numeric variable + +**y**: a numeric variable, number constant, or any other expression +that evaluates to a number (e.g. call to a function that returns a +number). + +See Also +-------- + +- :ref:`Arithmetic operators ` diff --git a/source/arduino/array.rst b/source/arduino/array.rst index f6bc141..92f3091 100644 --- a/source/arduino/array.rst +++ b/source/arduino/array.rst @@ -10,6 +10,8 @@ number. Arrays in the C++ programming language, in which the Maple is programmed, can be complicated, but using simple arrays is relatively straightforward. +.. contents:: Contents + :local: Creating (Declaring) an Array ----------------------------- @@ -69,15 +71,15 @@ access is within legal bounds of the array size that you have declared. -To assign a value to an array: ------------------------------- +To assign a value to an array +----------------------------- :: mySensVals[0] = 10; -To retrieve a value from an array: ----------------------------------- +To retrieve a value from an array +--------------------------------- :: @@ -106,6 +108,10 @@ Arduino `Knight Rider example `_\ (which will run unmodified on the Maple). +Arduino Compatibility +--------------------- + +Arrays on Maple are identical those on Arduino. See also -------- diff --git a/source/arduino/assignment.rst b/source/arduino/assignment.rst index 1c790bb..21e90e9 100644 --- a/source/arduino/assignment.rst +++ b/source/arduino/assignment.rst @@ -8,7 +8,6 @@ Stores the value to the right of the equal sign in the variable to the left of the equal sign. - The single equal sign in the C++ programming language is called the assignment operator. It has a different meaning than in algebra class, where it indicated an equation or equality. The assignment @@ -36,13 +35,17 @@ needs to be able to hold the value stored in it. If it is not large enough to hold a value, the value stored in the variable will be incorrect. - - Don't confuse the assignment operator [ = ] (single equal sign) with the comparison operator [ == ] (double equal signs), which evaluates whether two expressions are equal. +Arduino Compatibility +--------------------- + +Assignments on the Maple are identical to those on Arduino. + + See Also -------- diff --git a/source/arduino/attachinterrupt.rst b/source/arduino/attachinterrupt.rst index 189141b..cb11327 100644 --- a/source/arduino/attachinterrupt.rst +++ b/source/arduino/attachinterrupt.rst @@ -2,8 +2,18 @@ .. _arduino-attachinterrupt: -attachInterrupt(interrupt, function, mode) -========================================== +attachInterrupt() +================= + +Used to specify a function to call when an external interrupt (like an +GPIO changing from LOW to HIGH, a button getting pressed, etc.) +occurs. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- .. doxygenfunction:: attachInterrupt @@ -14,17 +24,15 @@ attachInterrupt(interrupt, function, mode) Discussion ---------- -Specifies a function to call when an external interrupt occurs. -Replaces any previous function that was attached to the interrupt. -For more information on external interrupts on the Maple +Because the function will run in interrupt context, inside of it, +:ref:`arduino-delay` won't work, and the value returned by +:ref:`arduino-millis` will not increment. Serial data received while +in the function may be lost. You should declare as ``volatile`` any +global variables that you modify within the attached function. -Note ----- - -Inside the attached function, delay() won't work, and the value -returned by millis() will not increment. Serial data received while in -the function may be lost. You should declare as volatile any variables -that you modify within the attached function. +There are a few constraints you should be aware of if you're using +more than one interrupt at a time; the :ref:`external-interrupts` page +has the details. Using Interrupts @@ -33,8 +41,7 @@ Using Interrupts Interrupts are useful for making things happen automatically in microcontroller programs, and can help solve timing problems. A good task for using an interrupt might be reading a rotary encoder, -monitoring user input. - +or monitoring user input. If you wanted to insure that a program always caught the pulses @@ -49,45 +56,44 @@ situations, using an interrupt can free the microcontroller to get some other work done while not missing the doorbell. - Example ------- :: int maple_led_pin = 13; - volatile int state = LOW; - - void setup() - { + volatile int state = LOW; // must declare volatile, since it's + // modified within the blink handler + + void setup() { pinMode(maple_led_pin, OUTPUT); attachInterrupt(0, blink, CHANGE); } - - void loop() - { + + void loop() { digitalWrite(maple_led_pin, state); } - - void blink() - { + + void blink() { state = !state; } -Arduino Compatibility Note --------------------------- +Arduino Compatibility +--------------------- Most Arduino boards have two external interrupts: numbers 0 (on digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 -(pin 18). +(pin 18). On the Maple, you don't have to remember which interrupt +number goes with which pin -- just tell ``attachInterrupt()`` the pin +you want. See also -------- -- `detachInterrupt `_ - +- :ref:`detachInterrupt ` +- :ref:`external-interrupts` diff --git a/source/arduino/bit.rst b/source/arduino/bit.rst index f8241a5..b74ad3d 100644 --- a/source/arduino/bit.rst +++ b/source/arduino/bit.rst @@ -6,37 +6,40 @@ bit() Description ----------- -Computes the value of the specified bit (bit 0 is 1, bit 1 is 2, -bit 2 is 4, etc.). - +(Macro) Computes the value of an (unsigned) integer with the specified +bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8, +16, 32, etc.). Syntax ------ -bit(n) - +``bit(n)`` Parameters ---------- -n: the bit whose value to compute +* **n** the bit to set. + +Value +----- +The value of an integer with the given bit set. -Returns -------- -the value of the bit +Arduino Compatibility +--------------------- +The Maple implementation of bit is compatible with Arduino. See also -------- -- `bitRead `_\ () -- `bitWrite `_\ () -- `bitSet `_\ () -- `bitClear `_\ () +- :ref:`arduino-bitread` +- :ref:`arduino-bitwrite` +- :ref:`arduino-bitset` +- :ref:`arduino-bitclear` diff --git a/source/arduino/bitclear.rst b/source/arduino/bitclear.rst index e86dbc5..8a46877 100644 --- a/source/arduino/bitclear.rst +++ b/source/arduino/bitclear.rst @@ -6,43 +6,39 @@ bitClear() Description ----------- -Clears (writes a 0 to) a bit of a numeric variable. - - +(Macro) Clears (writes a 0 to) a bit of a numeric variable. Syntax ------ -bitClear(x, n) - +``bitClear(x, n)`` Parameters ---------- -x: the numeric variable whose bit to clear - - - -n: which bit to clear, starting at 0 for the least-significant -(rightmost) bit +* **x** the numeric variable whose bit to clear +* **n** which bit to clear, starting at 0 for the least-significant + (rightmost) bit Returns ------- -none +None. +Arduino Compatibility +--------------------- -See also --------- - +This implementation is compatible with that of Arduino. -- `bit `_\ () -- `bitRead `_\ () -- `bitWrite `_\ () -- `bitSet `_\ () +See also +-------- +- :ref:`bit `\ () +- :ref:`bitRead `\ () +- :ref:`bitWrite `\ () +- :ref:`bitSet `\ () diff --git a/source/arduino/bitread.rst b/source/arduino/bitread.rst index 3d0b1a4..c3a79c4 100644 --- a/source/arduino/bitread.rst +++ b/source/arduino/bitread.rst @@ -6,43 +6,41 @@ bitRead() Description ----------- -Reads a bit of a number. - +(Macro) Gets the value of a bit in a number. Syntax ------ -bitRead(x, n) - +``bitRead(x, n)`` Parameters ---------- -x: the number from which to read - +* **x** the number from which to read the bit. +* **n** which bit to read, starting at 0 for the least-significant + (rightmost) bit -n: which bit to read, starting at 0 for the least-significant -(rightmost) bit +Value +----- +The value of the bit (0 or 1). -Returns -------- -the value of the bit (0 or 1). +Arduino Compatibility +--------------------- +The Maple implementation of ``bitRead`` is compatible with Arduino. See also -------- -- `bit `_\ () -- `bitWrite `_\ () -- `bitSet `_\ () -- `bitClear `_\ () - - +- :ref:`arduino-bit` +- :ref:`arduino-bitwrite` +- :ref:`arduino-bitset` +- :ref:`arduino-bitclear` diff --git a/source/arduino/bitset.rst b/source/arduino/bitset.rst index 882ec92..adf637a 100644 --- a/source/arduino/bitset.rst +++ b/source/arduino/bitset.rst @@ -6,42 +6,41 @@ bitSet() Description ----------- -Sets (writes a 1 to) a bit of a numeric variable. - +(Macro) Sets (writes a 1 to) a bit of a numeric variable. Syntax ------ -bitSet(x, n) - +``bitSet(x, n)`` Parameters ---------- -x: the numeric variable whose bit to set +* **x** the numeric variable whose bit to set +* **n** which bit to set, starting at 0 for the least-significant + (rightmost) bit -n: which bit to set, starting at 0 for the least-significant -(rightmost) bit +Value +----- +None. -Returns -------- +Arduino Compatibility +--------------------- -none +The Maple implementation of bitSet is compatible with Arduino. - -See also +See Also -------- - -- `bit `_\ () -- `bitRead `_\ () -- `bitWrite `_\ () -- `bitClear `_\ () +- :ref:`arduino-bit` +- :ref:`arduino-bitread` +- :ref:`arduino-bitwrite` +- :ref:`arduino-bitclear` diff --git a/source/arduino/bitshift.rst b/source/arduino/bitshift.rst index f59b489..d849f2a 100644 --- a/source/arduino/bitshift.rst +++ b/source/arduino/bitshift.rst @@ -1,74 +1,76 @@ +.. highlight:: cpp + .. _arduino-bitshift: -bitshift left (<<), bitshift right (>>) -======================================= +Bit shift left (``<<``), bit shift right (``>>``) +================================================= Description ----------- -From *The Bitmath Tutorial* in The Playground - +(Adapted from `The Bit Math Tutorial +`_ in `The Arduino +Playground `_\ ) There are two bit shift operators in C++: the left shift operator -<< and the right shift operator >>. These operators cause the bits -in the left operand to be shifted left or right by the number of +``<<`` and the right shift operator ``>>``. These operators cause the +bits in the left operand to be shifted left or right by the number of positions specified by the right operand. -More on bitwise math may be found -`here. `_ +More information on bitwise math can be obtained in the Wikipedia +article on `bitwise operations +`_\ , especially the +section on shifts in `C, C++, and Java +`_\ . Syntax ------ -variable << number\_of\_bits - - - -variable >> number\_of\_bits +``some_int << number_of_bits`` +``some_int >> number_of_bits`` Parameters ---------- -variable - (byte, int, long) number\_of\_bits integer <= 32 +* **some_int** An integer value or variable. + +* **number_of_bits** integer whose value is at most ``8 * + sizeof(variable)`` (so ``number_of_bits`` can be at most 32 for + ``int`` values, at most ``8`` for ``char`` values, etc.; the various + integer sizes are summarized :ref:`in this table + `\ ). Example: -------- -:: - - int a = 5; // binary: 0000000000000101 - int b = a << 3; // binary: 0000000000101000, or 40 in decimal - int c = b >> 3; // binary: 0000000000000101, or back to 5 like we started with - - - -When you shift a value x by y bits (x << y), the leftmost y bits in -x are lost, literally shifted out of existence: - +Here are some examples of bit shifting, with the binary representation of the number in comments:: + int a = 5; // binary: 101 + int b = a << 3; // binary: 101000, or 40 in decimal + int c = b >> 3; // binary: 101, or back to 5 like we started with -:: - int a = 5; // binary: 0000000000000101 - int b = a << 14; // binary: 0100000000000000 - the first 1 in 101 was discarded +When you left shift a value x by y bits (x << y), the leftmost y bits +in x are lost, literally shifted out of existence. We'll do this +example with ``char`` values (which are integers in the range 0-255, +and take up 8 bits of memory):: + char a = 5; // binary (all 8 bits): 00000101 + char b = a << 7; // binary: 10000000 - the first 1 in 101 was discarded -If you are certain that none of the ones in a value are being -shifted into oblivion, a simple way to think of the left-shift -operator is that it multiplies the left operand by 2 raised to the -right operand power. For example, to generate powers of 2, the -following expressions can be employed: - - - -:: +If you are certain that none of the ones in a value are being shifted +into oblivion, a simple way to think of the left-shift operator is +that it multiplies the left operand by 2 raised to the right operand +power (in math notation, ``x << y`` equals x * 2\ :sup:`y`\ , as long +as none of the bits of x get shifted out). For example, to generate +powers of 2, the following expressions can be employed:: 1 << 0 == 1 1 << 1 == 2 @@ -80,48 +82,64 @@ following expressions can be employed: 1 << 10 == 1024 ... +.. _arduino-bitshift-signbit-gotcha: +When you shift x right by y bits (``x >> y``), and the highest bit in +x is a 1, the behavior depends on the exact data type of x. If x is of +type ``int``, the highest bit is special, and determines whether x is +negative or not; the details are too complicated to explain here, but +they are thoroughly explained in the Wikipedia article on `two's +complement arithmetic +`_\ , which the +system most computers use to store integers. In that case, the sign +bit is copied into lower bits, for esoteric historical reasons:: -When you shift x right by y bits (x >> y), and the highest bit in x -is a 1, the behavior depends on the exact data type of x. If x is -of type int, the highest bit is the sign bit, determining whether x -is negative or not, as we have discussed above. In that case, the -sign bit is copied into lower bits, for esoteric historical -reasons: - - - -:: + int x = -16; // binary (all 32 bits): 11111111111111111111111111110000 + int y = x >> 3; // binary: 11111111111111111111111111111110 - int x = -16; // binary: 1111111111110000 - int y = x >> 3; // binary: 1111111111111110 +This behavior, called "sign extension", is often not what you +want. You probably wish zeros to be shifted in from the left. It +turns out that the right shift rules are different for ``unsigned +int`` values, so you can use a type cast to suppress ones being copied +from the left:: -This behavior, called sign extension, is often not the behavior you -want. Instead, you may wish zeros to be shifted in from the left. -It turns out that the right shift rules are different for unsigned -int expressions, so you can use a typecast to suppress ones being -copied from the left: + int x = -16; // binary: 11111111111111111111111111110000 + int y = (unsigned int)x >> 3; // binary: 00011111111111111111111111111110 -:: - - int x = -16; // binary: 1111111111110000 - int y = (unsigned int)x >> 3; // binary: 0001111111111110 +If you are careful to avoid sign extension, you can use the +right-shift operator, ``>>``, as a way to divide by powers of 2. For +example:: + int x = 1000; + int y = x >> 3; // integer division of 1000 by 8, causing y = 125. -If you are careful to avoid sign extension, you can use the -right-shift operator >> as a way to divide by powers of 2. For -example: +Arduino Compatibility +--------------------- +Since it's part of the C++ language, bit shifting on the Maple is +compatible with the Arduino; however, you should keep in mind that the +Maple has bigger integer types (as in, more bits) than the Arduino. +Since the STM32 is a 32-bit processor, the ``int`` type takes up 32 +bits instead of 16, like on Arduino's 16-bit microcontroller. This +means that you can shift left, like ``x << y``, with bigger values of +``y`` on the Maple before ones in ``x`` start to get shifted out. -:: - - int x = 1000; - int y = x >> 3; // integer division of 1000 by 8, causing y = 125. +To calculate the number of bits of an integer type on the Maple, +multiply its size in bytes (see :ref:`this table +` for these) by 8, since there are 8 +bits in 1 byte. For example, a ``short`` takes up 2 bytes of memory, +or 2 * 8 = 16 bits. +See Also +-------- +- :ref:`arduino-bit` +- :ref:`arduino-bitread` +- :ref:`arduino-bitwrite` +- :ref:`arduino-bitclear` diff --git a/source/arduino/bitwiseand.rst b/source/arduino/bitwiseand.rst deleted file mode 100644 index 8d4eb3f..0000000 --- a/source/arduino/bitwiseand.rst +++ /dev/null @@ -1,230 +0,0 @@ -.. _arduino-bitwiseand: - -Bitwise AND (&), Bitwise OR (\|), Bitwise XOR (^) -================================================= - -Bitwise AND (&) ---------------- - -The bitwise operators perform their calculations at the bit level -of variables. They help solve a wide range of common programming -problems. Much of the material below is from an excellent tutorial -on bitwise math wihch may be found -`here. `_ - - - -Description and Syntax ----------------------- - -Below are descriptions and syntax for all of the operators. Further -details may be found in the referenced tutorial. - - - -Bitwise AND (&) ---------------- - -The bitwise AND operator in C++ is a single ampersand, &, used -between two other integer expressions. Bitwise AND operates on each -bit position of the surrounding expressions independently, -according to this rule: if both input bits are 1, the resulting -output is 1, otherwise the output is 0. Another way of expressing -this is: - - - -:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 0 0 1 (operand1 & operand2) - returned result - - - -In Arduino, the type int is a 16-bit value, so using & between two -int expressions causes 16 simultaneous AND operations to occur. In -a code fragment like: - - - -:: - - int a = 92; // in binary: 0000000001011100 - int b = 101; // in binary: 0000000001100101 - int c = a & b; // result: 0000000001000100, or 68 in decimal. - - - -Each of the 16 bits in a and b are processed by using the bitwise -AND, and all 16 resulting bits are stored in c, resulting in the -value 01000100 in binary, which is 68 in decimal. - - - -One of the most common uses of bitwise AND is to select a -particular bit (or bits) from an integer value, often called -masking. See below for an example - - - -Bitwise OR (\|) ---------------- - -The bitwise OR operator in C++ is the vertical bar symbol, \|. Like -the & operator, \| operates independently each bit in its two -surrounding integer expressions, but what it does is different (of -course). The bitwise OR of two bits is 1 if either or both of the -input bits is 1, otherwise it is 0. In other words: - - - -:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) - returned result - - - -Here is an example of the bitwise OR used in a snippet of C++ -code: - - - -:: - - int a = 92; // in binary: 0000000001011100 - int b = 101; // in binary: 0000000001100101 - int c = a | b; // result: 0000000001111101, or 125 in decimal. - - - -Example Program ---------------- - -A common job for the bitwise AND and OR operators is what -programmers call Read-Modify-Write on a port. On microcontrollers, -a port is an 8 bit number that represents something about the -condition of the pins. Writing to a port controls all of the pins -at once. - - - -PORTD is a built-in constant that refers to the output states of -digital pins 0,1,2,3,4,5,6,7. If there is 1 in an bit position, -then that pin is HIGH. (The pins already need to be set to outputs -with the pinMode() command.) So if we write ``PORTD = B00110001;`` -we have made pins 2,3 & 7 HIGH. One slight hitch here is that we -*may* also have changeed the state of Pins 0 & 1, which are used by -the Arduino for serial communications so we may have interfered -with serial communication. - - - -:: - - Our algorithm for the program is: - - -- Get PORTD and clear out only the bits corresponding to the pins - we wish to control (with bitwise AND). -- Combine the modified PORTD value with the new value for the pins - under control (with biwise OR). - - - -:: - - int i; // counter variable - int j; - - void setup(){ - DDRD = DDRD | B11111100; // set direction bits for pins 2 to 7, leave 0 and 1 untouched (xx | 00 == xx) - // same as pinMode(pin, OUTPUT) for pins 2 to 7 - Serial.begin(9600); - } - - void loop(){ - for (i=0; i<64; i++){ - - PORTD = PORTD & B00000011; // clear out bits 2 - 7, leave pins 0 and 1 untouched (xx & 11 == xx) - j = (i << 2); // shift variable up to pins 2 - 7 - to avoid pins 0 and 1 - PORTD = PORTD | j; // combine the port information with the new information for LED pins - Serial.println(PORTD, BIN); // debug to show masking - delay(100); - } - } - - - -Bitwise XOR (^) ---------------- - -There is a somewhat unusual operator in C++ called bitwise -EXCLUSIVE OR, also known as bitwise XOR. (In English this is -usually pronounced "eks-or".) The bitwise XOR operator is written -using the caret symbol ^. This operator is very similar to the -bitwise OR operator \|, only it evaluates to 0 for a given bit -position when both of the input bits for that position are 1: - - - -:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 0 (operand1 ^ operand2) - returned result - - - -Another way to look at bitwise XOR is that each bit in the result -is a 1 if the input bits are different, or 0 if they are the same. - - - -Here is a simple code example: - - - -:: - - int x = 12; // binary: 1100 - int y = 10; // binary: 1010 - int z = x ^ y; // binary: 0110, or decimal 6 - - - -The ^ operator is often used to toggle (i.e. change from 0 to 1, or -1 to 0) some of the bits in an integer expression. In a bitwise OR -operation if there is a 1 in the mask bit, that bit is inverted; if -there is a 0, the bit is not inverted and stays the same. Below is -a program to blink digital pin 5. - - - -:: - - // Blink_Pin_5 - // demo for Exclusive OR - void setup(){ - DDRD = DDRD | B00100000; // set digital pin five as OUTPUT - Serial.begin(9600); - } - - void loop(){ - PORTD = PORTD ^ B00100000; // invert bit 5 (digital pin 5), leave others untouched - delay(100); - } - - - -See Also - - -- `&& `_ (Boolean AND) -- `\|\| `_ (Boolean OR) - diff --git a/source/arduino/bitwisecompound.rst b/source/arduino/bitwisecompound.rst index c3c808f..d460dc8 100644 --- a/source/arduino/bitwisecompound.rst +++ b/source/arduino/bitwisecompound.rst @@ -1,227 +1,228 @@ +.. highlight:: cpp + .. _arduino-bitwisecompound: -compound bitwise AND (&=), compound bitwise OR (\|=) -==================================================== +Compound bitwise and (&=), or (\|=), XOR (^=) +============================================= The compound bitwise operators perform their calculations at the bit level of variables. They are often used to clear and set specific bits of a variable. +See the :ref:`bitwise math tutorial ` for more +information on bitwise operators. +.. contents:: Contents + :local: -See the -`bitwise AND (&) `_ and -`bitwise OR (\|) `_ -operators for the details of their operation, and also the -`Bitmath Tutorial `_ -for more information on bitwise operators. - - - -compound bitwise AND (&=) -========================= - -Description ------------ - -The compound bitwise AND operator (&=) is often used with a -variable and a constant to force particular bits in a variable to -the LOW state (to 0). This is often referred to in programming -guides as "clearing" or "resetting" bits. - - +.. _arduino-bitwisecompound-and: -Syntax: -------- +Compound bitwise AND (&=) +------------------------- -:: +The compound bitwise AND operator ``&=`` is often used with a variable +and a constant to force particular bits in a variable to be zero. This +is often referred to in programming guides as "clearing" or +"resetting" bits. In a program, writing the line ``x &= y;`` is +equivalent to writing ``x = x & y;``. That is, the value of ``x`` +after the line will be equal to its old value bitwise ANDed with the +value of ``y``:: - x &= y; // equivalent to x = x & y; + x &= y; // equivalent to x = x & y; +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any :ref:`integer value +` (like ``3`` or ``0x20``) for ``y``. - -Parameters ----------- - -x: a char, int or long variable -y: an integer constant or char, int, or long - - - -Example: --------- - -First, a review of the Bitwise AND (&) operator - -:: +Before doing an example of ``&=``, let's first review the Bitwise AND +(``&``) operator:: 0 0 1 1 operand1 0 1 0 1 operand2 ---------- - 0 0 0 1 (operand1 & operand2) - returned result - - - -Bits that are "bitwise ANDed" with 0 are cleared to 0 so, if myByte -is a byte variable, -``myByte & B00000000 = 0;`` - - - -Bits that are "bitwise ANDed" with 1 are unchanged so, -``myByte & B11111111 = myByte;`` + 0 0 0 1 (operand1 & operand2) = result +As shown above, bits that are "bitwise ANDed" with 0 become 0, while +bits that are "bitwise ANDed" with 1 are left unchanged. So, if ``b`` +is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b & +B11111111`` equals ``b``. +.. _arduino-bitwisecompound-binconst: -Note: because we are dealing with bits in a bitwise operator - it -is convenient to use the binary formatter with -`constants. `_ The -numbers are still the same value in other representations, they are -just not as easy to understand. Also, B00000000 is shown for -clarity, but zero in any number format is zero (hmmm something -philosophical there?) +.. note:: The above uses :ref:`binary constants + `\ . The numbers are still the same + value in other representations, they just might not be as easy to + understand. + Normally, in C and C++ code, :ref:`hexadecimal + ` or :ref:`octal + ` are used when we're interested in + an integer's bits, rather than its value as a number. + While hexadecimal and octal literals might be harder to understand + at first, you should really take the time to learn them. They're + part of C, C++, and many other programming languages, while binary + constants are available only for compatibility with Arduino. -Consequently - to clear (set to zero) bits 0 & 1 of a variable, -while leaving the rest of the variable unchanged, use the compound -bitwise AND operator (&=) with the constant B11111100 + Also, ``B00000000`` is shown for clarity, but zero in any number + format is zero. -:: +So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while +leaving the rest of the variable's bits unchanged, use the compound +bitwise AND operator ``&=`` with the constant ``B11111100`` +(hexadecimal ``0xFC``\ ):: - 1 0 1 0 1 0 1 0 variable + 1 0 1 0 1 0 1 0 variable 1 1 1 1 1 1 0 0 mask ---------------------- 1 0 1 0 1 0 0 0 - - variable unchanged - bits cleared - - -Here is the same representation with the variable's bits replaced -with the symbol x - + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared -:: +Here is the same representation with the variable's bits replaced +with the symbol ``x``\ :: x x x x x x x x variable 1 1 1 1 1 1 0 0 mask ---------------------- x x x x x x 0 0 - - variable unchanged - bits cleared - - -So if: + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared -:: - myByte = 10101010; - - myByte &= B1111100 == B10101000; +So, using a byte variable ``b``\ , if we say:: + b = B10101010; // B10101010 == 0xAA + b &= B11111100; // B11111100 == 0xFC +then we will have :: -compound bitwise OR (\|=) -========================= + b == B10101000; // B10101000 == 0xA8 -Description ------------ +.. _arduino-bitwisecompound-or: -The compound bitwise OR operator (\|=) is often used with a -variable and a constant to "set" (set to 1) particular bits in a -variable. +Compound bitwise OR (\|=) +------------------------- +The compound bitwise OR operator ``|=`` is often used with a variable +and a constant to "set" (set to 1) particular bits in a variable. In +a program, writing the line ``x |= y;`` is equivalent to writing ``x = +x | y;``. That is, the value of ``x`` after the line will be equal to +its old value bitwise ORed with the value of ``y``:: + x |= y; // equivalent to x = x | y; -Syntax: -------- +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`compound bitwise AND +`\ , ``&=``). -:: +Before doing an example of ``|=``, let's first review the Bitwise OR +(``|``) operator:: - x |= y; // equivalent to x = x | y; + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) = result +Bits that are "bitwise ORed" with 0 are unchanged, while bits that are +"bitwise ORed" with 1 are set to 1. So if ``b`` is a ``byte`` +variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111`` +equals ``B11111111`` (here we've used binary constants; see the +:ref:`note ` above). +So, to set bits 0 and 1 of a one-byte variable, while leaving the rest +of the variable unchanged, use the compound bitwise OR operator +(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``):: -Parameters ----------- + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set -x: a char, int or long variable -y: an integer constant or char, int, or long +Here is the same representation with the variable's bits replaced with +the symbol ``x``:: + x x x x x x x x variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + x x x x x x 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set +So, using a byte variable ``b``, if we say:: -Example: --------- + b = B10101010; // B10101010 == 0xAA + b |= B00000011; // B00000011 == 0x3 -First, a review of the Bitwise OR (\|) operator +then we will have :: -:: + b == B10101011; // B10101011 == 0xAB - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) - returned result +.. _arduino-bitwisecompound-xor: -Bits that are "bitwise ORed" with 0 are unchanged, so if myByte is -a byte variable, -myByte \| B00000000 = myByte; +Compound bitwise XOR (\^=) +-------------------------- +The compound bitwise XOR operator ``^=`` is used with a variable and a +constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a +variable. In a program, writing the line ``x ^= y;`` is equivalent to +writing ``x = x ^ y;``. That is, the value of ``x`` after the line +will be equal to its old value bitwise XORed with the value of ``y``:: + x ^= y; // equivalent to x = x ^ y; -Bits that are "bitwise ORed" with 1 are set to 1 so: -myByte & B11111111 = B11111111; +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`&= +` and :ref:`\|= +`; in fact, these three operators all +work the same in this way). +Before doing an example of ``^=``, let's first review the Bitwise +XOR operator, ``^``:: + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) = result -Consequently - to set bits 0 & 1 of a variable, while leaving the -rest of the variable unchanged, use the compound bitwise AND -operator (&=) with the constant B00000011 +One way to look at bitwise XOR is that each bit in the result is a 1 +if the input bits are different, or 0 if they are the same. Another +way to think about it is that the result bit will be 1 when *exactly* +one (no more, no less) of the input bits is 1; otherwise, it will be +zero. This means that if you XOR a bit with 1, it will change (or +toggle) its value, while if you XOR a bit with 0, it stays the same. -:: +So, to toggle bits 0 and 1 of a one-byte variable, while leaving the +rest of the variable unchanged, use the compound bitwise XOR operator +``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see +:ref:`note ` above):: 1 0 1 0 1 0 1 0 variable 0 0 0 0 0 0 1 1 mask ---------------------- 1 0 1 0 1 0 1 1 - - variable unchanged - bits set - + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged toggled -Here is the same representation with the variables bits replaced -with the symbol x +So, using a byte variable ``b``, if we say:: + b = B10101010; // B10101010 == 0xAA + b ^= B00000011; // B00000011 == 0x3 +then we will have :: -:: - - x x x x x x x x variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - x x x x x x 1 1 - - variable unchanged - bits set - -So if: - -:: - - myByte = B10101010; - - myByte |= B00000011 == B10101011; - - + b == B10101001; // B10101001 == 0xA9 See Also +-------- - -- `& `_ (bitwise AND) -- `\| `_ (bitwise OR) -- `&& `_ (Boolean AND) -- `\|\| `_ (Boolean OR) - - +- :ref:`Boolean operations ` (``&&``, ``||``) +- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) diff --git a/source/arduino/bitwisemath.rst b/source/arduino/bitwisemath.rst new file mode 100644 index 0000000..3f102eb --- /dev/null +++ b/source/arduino/bitwisemath.rst @@ -0,0 +1,183 @@ +.. highlight:: cpp + +.. _arduino-bitwisemath: + +Bitwise AND (&), OR (\|), XOR (^), NOT (~) +========================================== + +The bitwise operators perform their calculations at the bit level of +variables. They help solve a wide range of common programming +problems. + +Much of the material here is adapted for Maple from an (Arduino) +`tutorial on bitwise math +`_\ . Another great +resource is the Wikipedia article on `bitwise operations +`_\ . + +Below are descriptions and syntax for all of the operators. + +.. contents:: Contents + :local: + +.. _arduino-bitwisemath-and: + +Bitwise AND (&) +--------------- + +The bitwise AND operator in C++ is a single ampersand, ``&``, used +between two other integer expressions. Bitwise AND operates on each +bit position of the surrounding expressions independently, according +to this rule: if both input bits are 1, the resulting output is 1, +otherwise the output is 0. Another way of expressing this is:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) = result + + +On the Maple, the type ``int`` is a 32-bit value, so using ``&`` +between two ``int`` expressions causes 32 simultaneous AND operations +to occur. In a code fragment like:: + + int a = 92; // in binary: 00000000000000000000000001011100 + int b = 101; // in binary: 00000000000000000000000001100101 + int c = a & b; // result: 00000000000000000000000001000100, + // (or 68 in decimal). + + +Each of the 32 bits in ``a`` and ``b`` are processed using bitwise +AND, and all 32 resulting bits are stored in ``c``, resulting in the +value 1000100 in binary, which is 68 in decimal. + + +.. _arduino-bitwisemath-or: + +Bitwise OR (\|) +--------------- + +The bitwise OR operator in C++ is the vertical bar symbol, ``|``. Like +the ``&`` operator, ``|`` operates independently on each bit in its +two surrounding integer expressions, but what it does is +different. The bitwise OR of two bits is 1 if either or both of the +input bits is 1, otherwise it is 0. For example:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) = result + +Here is an example of bitwise OR used in a snippet of C++ code (using +``char``, which takes up 8 bits of memory, instead of ``int``, which +uses 32):: + + char a = 92; // in binary: 01011100 + char b = 101; // in binary: 01100101 + char c = a | b; // result: 01111101, or 125 in decimal. + +.. _arduino-bitwisemath-xor: + +Bitwise XOR (^) +--------------- + +There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE +OR, also known as bitwise XOR. (In English, this is usually pronounced +"zor" or "ex-or"). The bitwise XOR operator is written using the caret +symbol, ``^``. This operator is very similar to the bitwise OR +operator ``|``, except it evaluates to 0 for a given bit position when +both of the input bits for that position are 1:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) = result + + +Another way to look at bitwise XOR is that each bit in the result +is a 1 if the input bits are different, or 0 if they are the same. + +Here is a simple example:: + + int x = 12; // binary (ignoring extra bits): 1100 + int y = 10; // binary: 1010 + int z = x ^ y; // binary: 0110, or decimal 6 + + + +The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 +to 0) some of the bits in an integer expression. In a bitwise OR +operation if there is a 1 in the mask bit, that bit is inverted; if +there is a 0, the bit is not inverted and stays the same. Below is a +program to blink digital pin 13 (the LED pin on Maple):: + + // Blink Maple LED pin + + int led_pin = 13; + int toggle = 0; + + // demo for Exclusive OR + void setup(){ + pinMode(led_pin, OUTPUT); + } + + void loop(){ + toggle = toggle ^ 1; + digitalWrite(led_pin, toggle); + delay(100); + } + +.. _arduino-bitwisemath-not: + +Bitwise NOT (~) +--------------- + +The bitwise NOT operator in C++ is the tilde character ``~``. Unlike +``&`` and ``|``, the bitwise NOT operator is applied to a single +operand to its right. Bitwise NOT changes each bit to its opposite: 0 +becomes 1, and 1 becomes 0. For example:: + + 0 1 operand1 + ---- + 1 0 ~operand1 = result + +Another example:: + + char a = 103; // binary: 01100111 + char b = ~a; // binary: 10011000 = -104 + +You might be surprised to see a negative number like -104 as the +result of this operation. This is because the highest bit in an int +variable is the so-called "sign bit". If the highest bit is 1, the +number is interpreted as negative. This encoding of positive and +negative numbers is referred to as *two's complement*. For more +information, see the Wikipedia article on `two's +complement. `_ + +As an aside, it is interesting to note that (under two's complement +arithmetic) for any integer ``x``, ``~x`` is the same as ``-x-1``. + +At times, the sign bit in a signed integer expression can cause +some unwanted surprises. + + +Uses +---- + +One of the most common uses of bitwise operations is to select or +manipulate a particular bit (or bits) from an integer value, often +called `bit masking +`_\ . See the +linked Wikipedia article for more information and examples. + +If you really want to see bit-twiddling techniques in their full +glory, you could do much worse than to get yourself a copy of +`Hacker's Delight `_\ . + + +See Also +-------- + +- :ref:`Boolean operations ` (``&&``, ``||``) +- :ref:`Compound bitwise operations ` (``&=``, + ``|=``, ``^=``). diff --git a/source/arduino/bitwisexornot.rst b/source/arduino/bitwisexornot.rst deleted file mode 100644 index 25389cb..0000000 --- a/source/arduino/bitwisexornot.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _arduino-bitwisexornot: - -Bitwise NOT (~) -=============== - -The bitwise NOT operator in C++ is the tilde character ~. Unlike & -and \|, the bitwise NOT operator is applied to a single operand to -its right. Bitwise NOT changes each bit to its opposite: 0 becomes -1, and 1 becomes 0. For example: - - - -:: - - 0 1 operand1 - - - -:: - - ---------- - 1 0 ~ operand1 - - - -:: - - int a = 103; // binary: 0000000001100111 - int b = ~a; // binary: 1111111110011000 = -104 - - - -You might be surprised to see a negative number like -104 as the -result of this operation. This is because the highest bit in an int -variable is the so-called sign bit. If the highest bit is 1, the -number is interpreted as negative. This encoding of positive and -negative numbers is referred to as two's complement. For more -information, see the Wikipedia article on -`two's complement. `_ - - - -As an aside, it is interesting to note that for any integer x, ~x -is the same as -x-1. - - - -At times, the sign bit in a signed integer expression can cause -some unwanted surprises. - - diff --git a/source/arduino/bitwrite.rst b/source/arduino/bitwrite.rst index 5d95506..b35a54f 100644 --- a/source/arduino/bitwrite.rst +++ b/source/arduino/bitwrite.rst @@ -1,52 +1,37 @@ .. _arduino-bitwrite: -bitWrite() -========== +bitWrite(x, n, b) +================= Description ----------- -Writes a bit of a numeric variable. - - - -Syntax ------- - -bitWrite(x, n, b) - - +(Macro) Writes a bit of a numeric variable. Parameters ---------- -x: the numeric variable to which to write - - - -n: which bit of the number to write, starting at 0 for the -least-significant (rightmost) bit - - - -b: the value to write to the bit (0 or 1) +**x**: the numeric variable whose bit to write. +**n**: which bit of the number to write, starting at 0 for the +least-significant (rightmost) bit. +**b**: the value to write to the bit (0 or 1). Returns ------- -none +Nothing. +Arduino Compatibility +--------------------- +Maple's version of ``bitWrite()`` is compatible with Arduino. See also -------- - -- `bit `_\ () -- `bitRead `_\ () -- `bitSet `_\ () -- `bitClear `_\ () - - +- :ref:`bit() ` +- :ref:`bitRead() ` +- :ref:`bitSet() ` +- :ref:`bitClear() ` diff --git a/source/arduino/boolean.rst b/source/arduino/boolean.rst index f109bdb..a724c20 100644 --- a/source/arduino/boolean.rst +++ b/source/arduino/boolean.rst @@ -1,94 +1,86 @@ +.. highlight:: cpp + .. _arduino-boolean: Boolean Operators ================= -These can be used inside the condition of an -`if `_ statement. +These can be used inside the condition of an :ref:`if ` +statement. +.. contents:: Contents + :local: +.. _arduino-boolean-and: && (logical and) -~~~~~~~~~~~~~~~~ - -True only if both operands are true, e.g. +---------------- -:: +True only if both operands are true. For example:: - if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches + if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches // ... - } + } + +is true only if both inputs are high. Another example:: -is true only if both inputs are high. + if (a >= 10 && a <= 20){} // true if a is between 10 and 20 +**Be careful** not to say ``10 <= a <= 20``! This won't work the way +you want. You have to separately test whether ``a`` is at least 10 +using ``a >= 10``, then test whether ``a`` is at most 20 using ``a <= +20``, then combine the results using ``&&``. -\|\| (logical or) -~~~~~~~~~~~~~~~~~ +.. _arduino-boolean-or: -True if either operand is true, e.g. +\|\| (logical or) +----------------- -:: +True if either operand is true. For example:: if (x > 0 || y > 0) { // ... - } + } -is true if either x or y is greater than 0. +is true if either ``x`` or ``y`` is greater than 0. +! (logical not) +--------------- -! (not) -~~~~~~~ +True if the operand is false. For example:: -True if the operand is false, e.g. - -:: - - if (!x) { + if (!x) { // ... - } - -is true if x is false (i.e. if x equals 0). - - - -Warning -------- + } -Make sure you don't mistake the boolean AND operator, && (double -ampersand) for the bitwise AND operator & (single ampersand). They -are entirely different beasts. +is true if ``x`` is false (i.e. if ``x`` equals zero). +Some Advice +----------- +.. warning:: -Similarly, do not confuse the boolean \|\| (double pipe) operator -with the bitwise OR operator \| (single pipe). + Make sure you don't mistake the boolean AND operator ``&&`` + (double ampersand) for the :ref:`bitwise AND operator + ` ``&`` (single ampersand). They are + entirely different beasts. + Similarly, do not confuse the boolean OR operator ``||`` (double + pipe) with the :ref:`bitwise OR operator ` + ``|`` (single pipe). + The :ref:`bitwise NOT operator ` ``~`` + (tilde) looks much different than the boolean not operator ``!`` + (exclamation point, or "bang", as some programmers say), but you + still have to be sure which one you want. -The bitwise not ~ (tilde) looks much different than the boolean not -! (exclamation point or "bang" as the programmers say) but you -still have to be sure which one you want where. - - -Examples --------- - -:: - - if (a >= 10 && a <= 20){} // true if a is between 10 and 20 - - - -See also +See Also -------- - -- `& `_ (bitwise AND) -- `\| `_ (bitwise OR) -- `~ `_ (bitwise NOT -- `if `_ - - +- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) +- :ref:`Compound bitwise operators ` (``&=``, + ``|=``, ``^=``). +- :ref:`if statement ` diff --git a/source/arduino/booleanvariables.rst b/source/arduino/booleanvariables.rst index 3bbe72a..772db0f 100644 --- a/source/arduino/booleanvariables.rst +++ b/source/arduino/booleanvariables.rst @@ -1,53 +1,52 @@ +.. highlight:: cpp + .. _arduino-booleanvariables: -boolean -======= +Booleans +======== -A **boolean** holds one of two values, -`true `_ or -`false `_. (Each boolean -variable occupies one byte of memory.) +A **boolean** holds one of two values, :ref:`true +` or :ref:`false `. +On a Maple, each boolean variable occupies one byte of memory, and has +type ``bool``. +.. warning:: + On an Arduino, the type ``boolean`` is also provided. While the + Maple also has this type for compatibility, **its use is strongly + discouraged**. The ``bool`` type is a standard part of C++, while + ``boolean`` is a non-standard extension that serves no purpose. Example ------- :: - int LEDpin = 5; // LED on pin 5 - int switchPin = 13; // momentary switch on 13, other side connected to ground - - boolean running = false; - - void setup() - { - pinMode(LEDpin, OUTPUT); + int ledPin = 13; // LED on pin 13 + int switchPin = 12; // momentary switch on 12, other side connected to ground + + // running is a boolean variable: + bool running = false; + + void setup() { + pinMode(ledPin, OUTPUT); pinMode(switchPin, INPUT); digitalWrite(switchPin, HIGH); // turn on pullup resistor } - - void loop() - { - if (digitalRead(switchPin) == LOW) - { // switch is pressed - pullup keeps pin high normally + + void loop() { + if (digitalRead(switchPin) == LOW) { + // switch is pressed - pullup keeps pin high normally delay(100); // delay to debounce switch running = !running; // toggle running variable - digitalWrite(LEDpin, running) // indicate via LED + digitalWrite(ledPin, running) // indicate via LED } } - - - - - See also -------- -- `constants `_ -- `boolean operators `_ -- `Variable Declaration `_ - - +- :ref:`Boolean constants ` +- :ref:`Boolean operators ` +- :ref:`Variables ` diff --git a/source/arduino/braces.rst b/source/arduino/braces.rst index c7bd148..1ae34e8 100644 --- a/source/arduino/braces.rst +++ b/source/arduino/braces.rst @@ -1,113 +1,94 @@ +.. highlight:: cpp + .. _arduino-braces: -{} Curly Braces -=============== +Curly Braces ({}) +================= -Curly braces (also referred to as just "braces" or as "curly -brackets") are a major part of the C programming language. They are -used in several different constructs, outlined below, and this can -sometimes be confusing for beginners. +.. contents:: Contents + :local: +Introduction +------------ +Curly braces (also referred to as just "braces" or as "curly +brackets") are a major part of the C and C++ programming +languages. They are used in several different constructs, outlined +below, and this can sometimes be confusing for beginners. -An opening curly brace "{" must always be followed by a closing -curly brace "}". This is a condition that is often referred to as -the braces being balanced. The Arduino IDE (integrated development +An opening curly brace, ``{`` must always be followed by a closing +curly brace ``}``. This is a condition that is often referred to as +the braces being *balanced*. The Maple IDE (integrated development environment) includes a convenient feature to check the balance of -curly braces. Just select a brace, or even click the insertion -point immediately following a brace, and its logical companion will -be highlighted. - - - -At present this feature is slightly buggy as the IDE will often -find (incorrectly) a brace in text that has been "commented out." - - - -Beginning programmers, and programmers coming to C from the BASIC -language often find using braces confusing or daunting. After all, -the same curly braces replace the RETURN statement in a subroutine -(function), the ENDIF statement in a conditional and the NEXT -statement in a FOR loop. - +curly braces. Just select a brace, or even click the insertion point +immediately following a brace, and its companion will be highlighted\ +[#fbug]_\ . +Beginning programmers, and programmers coming to C++ from languages +without braces, often find using them confusing or daunting. Because the use of the curly brace is so varied, it is good programming practice to type the closing brace immediately after typing the opening brace when inserting a construct which requires -curly braces. Then insert some carriage returns between your braces -and begin inserting statements. Your braces, and your attitude, -will never become unbalanced. - - +curly braces. Then insert some blank lines between your braces and +begin inserting statements. Your braces, and your attitude, will never +become unbalanced. Unbalanced braces can often lead to cryptic, impenetrable compiler errors that can sometimes be hard to track down in a large program. -Because of their varied usages, braces are also incredibly -important to the syntax of a program and moving a brace one or two -lines will often dramatically affect the meaning of a program. +Because of their varied usages, braces are also incredibly important +to the syntax of a program and moving a brace one or two lines will +usually dramatically affect the meaning of a program. +The main uses of curly braces +----------------------------- +**Functions**:: -**The main uses of curly braces** ---------------------------------- - -Functions ---------- - -:: - - void myfunction(datatype argument){ - statements(s) + // a function body needs braces around it + void myfunction(datatype argument) { + // ... function body goes in here ... } +**Loops** (see the :ref:`while `\ , :ref:`for +`\ , and :ref:`do/while ` loop reference +pages for more information):: + // you should put braces around the body of a loop: -Loops ------ - -:: - - while (boolean expression) - { - statement(s) + while (boolean expression) { + // code inside the loop goes here } - do - { - statement(s) - } while (boolean expression); - - for (initialisation; termination condition; incrementing expr) - { - statement(s) + for (initialisation; termination condition; incrementing expr) { + // code inside the loop goes here } + do { + // code inside the loop goes here + } while (boolean expression); -Conditional statements ----------------------- - - +**Conditional statements** (see the :ref:`if statement ` +reference page for more information):: -:: + // you should put braces around the body of an "if", "else if", + // or "else": - if (boolean expression) - { - statement(s) + if (boolean expression) { + // code inside the "if" } - - else if (boolean expression) - { - statement(s) + else if (boolean expression) { + // code inside the "else if" } - else - { - statement(s) + else { + // code inside the "else" } +.. rubric:: Footnotes +.. TODO remove this once IDE 0.1.0 released -`Reference Home `_ - +.. [#fbug] At present this feature is slightly buggy as the IDE will + often find (incorrectly) a brace in text that has been commented + out. diff --git a/source/arduino/break.rst b/source/arduino/break.rst index d951c52..57009c1 100644 --- a/source/arduino/break.rst +++ b/source/arduino/break.rst @@ -1,12 +1,14 @@ +.. highlight:: cpp + .. _arduino-break: break ===== -**break** is used to exit from a **do**, **for**, or **while** -loop, bypassing the normal loop condition. It is also used to exit -from a **switch** statement. - +``break`` is used to exit from a :ref:`while `\ , +:ref:`for `\ , or :ref:`do/while ` loop, +bypassing the normal loop condition. It is also used to exit from a +:ref:`switch ` statement. Example @@ -20,6 +22,8 @@ Example sens = analogRead(sensorPin); if (sens > threshold){ // bail out on sensor detect x = 0; + // this line of code means that we'll immediately exit + // from the "for" loop: break; } delay(50); diff --git a/source/arduino/byte.rst b/source/arduino/byte.rst index 5e94bd4..0b21b31 100644 --- a/source/arduino/byte.rst +++ b/source/arduino/byte.rst @@ -1,13 +1,20 @@ +.. highlight:: cpp + .. _arduino-byte: byte ==== -Description ------------ +The ``byte`` type stores a 1-byte (8-bit) unsigned integer number, +from 0 to 255. -A byte stores an 8-bit unsigned number, from 0 to 255. +.. warning:: + The ``byte`` type is provided for compatibility with Arduino. + However, it is a non-standard extension. The standard C++ type for + storing an 8-bit unsigned integer is ``unsigned char``; we + recommend using that instead. (Your code will still work on an + Arduino). Example @@ -15,15 +22,10 @@ Example :: - byte b = B10010; // "B" is the binary formatter (B10010 = 18 decimal) - - + byte b = 134; -See also +See Also -------- - -- `word `_ -- `byte `_\ () -- `Variable Declaration `_ - +- :ref:`byte() ` (casting a value to a byte) +- :ref:`Variables ` diff --git a/source/arduino/bytecast.rst b/source/arduino/bytecast.rst index 71ab4aa..bf85a35 100644 --- a/source/arduino/bytecast.rst +++ b/source/arduino/bytecast.rst @@ -1,41 +1,50 @@ +.. highlight:: cpp + .. _arduino-bytecast: -byte() -====== +byte() (cast) +============= Description ----------- -Converts a value to the -`byte `_ data type. +Converts a value to the :ref:`byte ` data type. + +.. warning:: + Casting to the byte type is provided for compatibility with + Arduino. However, ``byte`` is a non-standard type. The standard + C++ type for storing an 8-bit unsigned integer is ``unsigned + char``, and we recommend using that instead. + In order to cast a variable ``x`` to an ``unsigned char``, the + following syntax can be used:: + + (unsigned char)(x); Syntax ------ -byte(x) - +``byte(x)`` Parameters ---------- -x: a value of any type - +**x**: a value of any integer type Returns ------- -byte - +The value, converted to a ``byte``. Note, however, that if the value +is larger than the maximum value you can store in a byte (255), then +the results might be strange and unexpected. -See also +See Also -------- - -- `byte `_ +- :ref:`arduino-byte` diff --git a/source/arduino/cc-attribution.txt b/source/arduino/cc-attribution.txt new file mode 100644 index 0000000..e662eeb --- /dev/null +++ b/source/arduino/cc-attribution.txt @@ -0,0 +1,9 @@ +.. Included in all this directory's files in order to satisfy the +.. Arduino CC Attribution-ShareAlike 3.0 License + +.. admonition:: License + + This documentation page was adapted from the `Arduino Reference + Documentation `_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License `_. diff --git a/source/arduino/changes.rst b/source/arduino/changes.rst deleted file mode 100644 index 75cd65d..0000000 --- a/source/arduino/changes.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. _arduino-changes: - -Changes -======= - -This page lists major changes to the Arduino core, libraries, and -environment. For details, see the -`release notes `_. - - - -Changes in Arduino 0017 -~~~~~~~~~~~~~~~~~~~~~~~ - - -- **Environment**: The code base for the Arduino development - environment was largely re-written to bring it back into sync with - Processing (1.0.3). The main differences include support for - multiple sketch windows open simultaneously and a dedicated window - for the serial monitor. - - -- **Icons**: The icons and about images were updated. - - -- **Arduino.app**: The Mac OS X version of Arduino is now a .app - file packaged in a .dmg. - - -- **Libraries**: Support was added for third-party libraries in - the *SKETCHBOOK*/libraries directory. This allows user-installed - libraries to persist across upgrades of the Arduino software. - - -- **Servo**: The servo library was rewritten to allow support for - up to 12 servos (on any pins) and up to 48 on the Mega. - - -- **LiquidCrystal**: The begin(), cursor(), noCursor(), blink(), - noBlink(), display(), noDisplay(), scrollDisplayLeft(), - scrollDisplayRight(), autoscroll(), noAutoscroll(), leftToRight(), - rightToLeft(), and createChar() functions were added. - - - -Changes in Arduino 0016 -~~~~~~~~~~~~~~~~~~~~~~~ - - -- New functions for writing a string, write(str), or buffer, - write(buf, len), were added to the Print, Serial, and Ethernet - library Client and Server classes. - - - -Changes in Arduino 0015 -~~~~~~~~~~~~~~~~~~~~~~~ - - -- Support for the Arduino Mega. - - - -Changes in Arduino 0013 -~~~~~~~~~~~~~~~~~~~~~~~ - - -- Support for printing floats was added to the Print, Serial, and - Ethernet library Client and Server classes. - - -- The word type and word(), bitRead(), bitWrite(), bitSet(), - bitClear(), bit(), lowByte(), and highByte() functions were added. - - - -Changes in Arduino 0012 -~~~~~~~~~~~~~~~~~~~~~~~ - - -- Added the Firmata library, which provides a standard protocol - for serial communication. - - -- Added Ethernet library. - - -- Added Servo library. - - -- Added LiquidCrystal library. - - diff --git a/source/arduino/char.rst b/source/arduino/char.rst index e783ed6..53dd060 100644 --- a/source/arduino/char.rst +++ b/source/arduino/char.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-char: char @@ -6,28 +8,25 @@ char Description ----------- -A data type that takes up 1 byte of memory that stores a character -value. Character literals are written in single quotes, like this: -'A' (for multiple characters - strings - use double quotes: -"ABC"). - - +The ``char`` type stores a 1-byte character value (or integer with +value from -128 to 127). Character literals are written in single +quotes, like this: ``'A'`` (for multiple characters - strings - use +double quotes: ``"ABC"``). -Characters are stored as numbers however. You can see the specific -encoding in the -`ASCII chart `_. This -means that it is possible to do arithmetic on characters, in which -the ASCII value of the character is used (e.g. 'A' + 1 has the -value 66, since the ASCII value of the capital letter A is 65). See -`Serial.println `_ reference -for more on how characters are translated to numbers. +Just like everything else on a computer, characters are stored as +numbers. You can see the specific encoding in the `ASCII chart +`_\ +. This means that it is possible to do arithmetic on characters, in +which the ASCII value of the character is used (e.g. ``'A' + 1`` has the +decimal value 66, since the ASCII value of the capital letter A in +decimal is 65). See the :ref:`Serial.println() +` documentation for more information about how +characters are converted into numbers. - -The char datatype is a signed type, meaning that it encodes numbers -from -128 to 127. For an unsigned, one-byte (8 bit) data type, use -the *byte* data type. - +The ``char`` datatype is a signed type, meaning that it encodes +numbers from -128 to 127. For an unsigned type, which stores values +from 0 to 255, just use the type ``unsigned char`` (two words). Example @@ -35,17 +34,16 @@ Example :: - char myChar = 'A'; - char myChar = 65; // both are equivalent - + // the following two lines are equivalent: + char c = 'A'; + char c = 65; See also -------- -- `byte `_ -- `int `_ -- `array `_ -- `Serial.println `_ +- :ref:`arduino-int` +- :ref:`arduino-array` (a string is just an array of ``char``\ s) +- :ref:`Serial.println() ` diff --git a/source/arduino/charcast.rst b/source/arduino/charcast.rst index daa7c92..d8184c1 100644 --- a/source/arduino/charcast.rst +++ b/source/arduino/charcast.rst @@ -1,41 +1,36 @@ +.. highlight:: cpp + .. _arduino-charcast: -char() -====== +char() (cast) +============= Description ----------- -Converts a value to the -`char `_ data type. - - +Converts a value to the :ref:`char ` data type. Syntax ------ -char(x) - +``char(x)`` Parameters ---------- -x: a value of any type - +**x**: a value of any type Returns ------- -char +The value, converted to a ``char``. Note, however, that if the value +is outside the range of a ``char`` (-128 to 127), then the results +might be strange and unexpected. - -See also +See Also -------- - -- `char `_ - - +- :ref:`char ` diff --git a/source/arduino/comments.rst b/source/arduino/comments.rst index 189ead5..3aeb37f 100644 --- a/source/arduino/comments.rst +++ b/source/arduino/comments.rst @@ -1,45 +1,60 @@ +.. highlight:: cpp + .. _arduino-comments: Comments ======== -Comments are lines in the program that are used to inform yourself -or others about the way the program works. They are ignored by the -compiler, and not exported to the processor, so they don't take up -any space on the Atmega chip. - - +Comments are lines in the program that are used to inform yourself or +others about the way the program works. They are ignored by the +compiler, and not exported to the processor, so they don't take up any +space in RAM or Flash. -Comments only purpose are to help you understand (or remember) how -your program works or to inform others how your program works. -There are two different ways of marking a line as a comment: +One use for comments is to help you understand (or remember) how your +program works, or to inform others how your program works. There are +two different ways of making comments. +**Single line comment**: Anything following two slashes, ``//``, until +the end of the line, is a comment:: + x = 5; // the rest of this line is a comment -Example -------- - -:: - - x = 5; // This is a single line comment. Anything after the slashes is a comment - // to the end of the line +**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` +is a comment:: - /* this is multiline comment - use it to comment out whole blocks of code + /* <-- a slash-star begins a multi-line comment + + all of this in the multi-line comment - you can use it to comment + out whole blocks of code - if (gwb == 0){ // single line comment is OK inside a multiline comment - x = 3; /* but not another multiline comment - this is invalid */ + if (gwb == 0){ // single line comment is OK inside a multi-line comment + x = 3; } - // don't forget the "closing" comment - they have to be balanced! + + // don't forget the "closing" star-slash - they have to be balanced: */ +Note that it's okay to use single-line comments within a multi-line +comment, but you can't use multi-line comments within a multi-line +comment. Here's an example:: + + /* ok, i started a multi-line comment + + x = 3; /* this next star-slash ENDS the multi-line comment: */ + + x = 4; // this line is outside of the multi-line comment + + // next line is also outside of the comment, and causes a compile error: + */ +Programming Tip +--------------- -**Tip** -When experimenting with code, "commenting out" parts of your -program is a convenient way to remove lines that may be buggy. This -leaves the lines in the code, but turns them into comments, so the -compiler just ignores them. This can be especially useful when -trying to locate a problem, or when a program refuses to compile -and the compiler error is cryptic or unhelpful. +When experimenting with code, "commenting out" parts of your program +is a convenient way to remove lines that may be buggy. This leaves +the lines in the code, but turns them into comments, so the compiler +just ignores them. This can be especially useful when trying to locate +a problem, or when a program refuses to compile and the compiler error +is cryptic or unhelpful. diff --git a/source/arduino/comparison.rst b/source/arduino/comparison.rst index b87e05b..85c2118 100644 --- a/source/arduino/comparison.rst +++ b/source/arduino/comparison.rst @@ -1,54 +1,84 @@ +.. highlight:: cpp + .. _arduino-comparison: -Arduino/Processing Language Comparison -====================================== +Comparison Operators +==================== + +The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and +``>=`` are used to compare two numbers. They are :ref:`true +` when the comparison is true, and :ref:`false +` otherwise. They are based on the symbols +=, ≠, <, >, ≤, and ≥ from mathematics. + +Here are some examples, with their meaning in comments:: + + // "eq" is true when x is equal to y + bool eq = (x == y); + + // "neq" is true when x is different than y + bool neq = (x != y); + + // "lt" is true when x is less than, but NOT equal to, y + bool lt = (x < y); + + // "gt" is true when x is greater than, but NOT equal to, y + bool gt = (x > y); + + // "lte" is true when x is less than or equal to y + bool lte = (x <= y); + + // "gte" is true when x is greater than or equal to y + bool gte = (x >= y); -The Arduino language (based on Wiring) is implemented in C/C++, and -therefore has some differences from the Processing language, which -is based on Java. +The parentheses are optional; they are present only for clarity. For +example, the following two lines are the same:: + bool eq = x == y; + bool eq = (x == y); -Arrays -~~~~~~ +Uses +---- -*Arduino* -*Processing* -int bar[8]; -bar[0] = 1; -int[] bar = new int[8]; -bar[0] = 1; -int foo[] = { 0, 1, 2 }; -int foo[] = { 0, 1, 2 }; -*or* -int[] foo = { 0, 1, 2 }; +Comparison operators, along with :ref:`boolean operators +`, are useful inside the conditionals of :ref:`if +` statements. Here's one example:: + if (x < 50) { + // only execute these lines if x is less than 50 + SerialUSB.println("delaying:"); + SerialUSB.println(x); + delay(x); + } -Loops -~~~~~ +.. warning:: + Beware of accidentally using the single equal sign (``=``) when you + meant to test if two numbers are equal (``==``). This is a common + mistake inside of ``if`` statement conditionals, e.g.:: -*Arduino* -*Processing* -int i; -for (i = 0; i < 5; i++) { ... } -for (int i = 0; i < 5; i++) { ... } + // DON'T MAKE THIS MISTAKE + if (x = 10) { + // body + } + The single equal sign is the assignment operator, and sets x to 10 + (puts the value 10 into the variable x). Instead use the double equal + sign (e.g. ``if (x == 10)``), which is the comparison operator, and + tests *whether* x is equal to 10 or not. The latter statement is only + true if x equals 10, but the former statement will always be true. -Printing -~~~~~~~~ + This is because C evaluates the statement ``if (x=10)`` as follows: 10 + is assigned to x (remember that the single equal sign is the + :ref:`assignment operator `), so x now + contains 10. Then the 'if' conditional evaluates 10, which evaluates + to :ref:`true `, since any non-zero number + evaluates to ``true``. -*Arduino* -*Processing* -Serial.println("hello world"); -println("hello world"); -int i = 5; -Serial.println(i); -int i = 5; -println(i); -int i = 5; -Serial.print("i = "); -Serial.print(i); -Serial.println(); -int i = 5; -println("i = " + i); + Consequently, the conditional of an ``if`` statement like ``if (x = + 10) {...}`` will always evaluate to ``true``, and the variable x + will be set to 10, which is probably not what you meant. + (This sometimes has uses, though, so just because an assignment + appears within a conditional doesn't mean it's automatically wrong. + Be careful to know what you mean.) diff --git a/source/arduino/const.rst b/source/arduino/const.rst index 295b817..4a45387 100644 --- a/source/arduino/const.rst +++ b/source/arduino/const.rst @@ -1,37 +1,35 @@ +.. highlight:: cpp + .. _arduino-const: -const keyword +const Keyword ============= -The **const** keyword stands for constant. It is a variable +The ``const`` keyword stands for "constant". It is a variable *qualifier* that modifies the behavior of the variable, making a -variable "*read-only*". This means that the variable can be used -just as any other variable of its type, but its value cannot be -changed. You will get a compiler error if you try to assign a value -to a **const** variable. - - - -Constants defined with the *const* keyword obey the rules of -*`variable scoping `_* that -govern other variables. This, and the pitfalls of using*#define*, -makes the *const* keyword a superior method for defining constants -and is preferred over using -*`#define `_*. - +variable "*read-only*". This means that the variable can be used just +as any other variable of its type, but its value cannot be +changed. You will get a compiler error if you try to assign a value to +a ``const`` variable. +Constants defined with the ``const`` keyword obey the same rules of +:ref:`variable scoping ` that govern other +variables. This, and the pitfalls of using :ref:`#define +`, often makes using the ``const`` keyword a superior +method for defining constants than ``#define``. Example ------- :: + // this defines a variable called "pi", which cannot be changed: const float pi = 3.14; float x; // .... - x = pi * 2; // it's fine to use const's in math + x = pi * 2; // it's fine to find the value of a const variable pi = 7; // illegal - you can't write to (modify) a constant @@ -39,17 +37,13 @@ Example **#define** or **const** ------------------------ -You can use either **const** or **#define** for creating numeric or -string constants. For -`arrays `_, you will need to -use **const**. In general *const* is preferred over *#define* for -defining constants. - - - -See also: - +You can use either ``const`` or ``#define`` for creating numeric or +string constants. For :ref:`arrays `\ , you will need +to use ``const``. In general, ``const`` is preferred over ``#define`` +for defining constants. -- `#define `_ -- `volatile `_ +See Also +-------- +- :ref:`#define ` +- :ref:`volatile ` diff --git a/source/arduino/constants.rst b/source/arduino/constants.rst index 49f3933..b082774 100644 --- a/source/arduino/constants.rst +++ b/source/arduino/constants.rst @@ -7,26 +7,29 @@ Constants are predefined variables in the Arduino language. They are used to make the programs easier to read. We classify constants in groups. +.. contents:: Contents + :local: +.. _arduino-constants-bool: -Defining Logical Levels, true and false (Boolean Constants) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Boolean Constants +----------------- There are two constants used to represent truth and falsity in the Arduino language: **true**, and **false**. - +.. _arduino-constants-false: false ------ +^^^^^ false is the easier of the two to define. false is defined as 0 (zero). - +.. _arduino-constants-true: true ----- +^^^^ true is often said to be defined as 1, which is correct, but true has a wider definition. Any integer which is *non-zero* is TRUE, in @@ -34,19 +37,17 @@ a Boolean sense. So -1, 2 and -200 are all defined as true, too, in a Boolean sense. - Note that the *true* and *false* constants are typed in lowercase unlike HIGH, LOW, INPUT, & OUTPUT. - Defining Pin Levels, HIGH and LOW -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- When reading or writing to a digital pin there are only two possible values a pin can take/be-set-to: **HIGH** and **LOW**. - +.. _arduino-constants-high: **HIGH** @@ -73,7 +74,7 @@ with digitalWrite, the pin is at 5 volts. In this state it can series resistor to ground, or to another pin configured as an output, and set to LOW. - +.. _arduino-constants-low: **LOW** @@ -96,7 +97,7 @@ output, and set to HIGH. Defining Digital Pins, INPUT and OUTPUT -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------- Digital pins can be used either as **INPUT** or **OUTPUT**. Changing a pin from INPUT TO OUTPUT with pinMode() drastically @@ -105,7 +106,7 @@ changes the electrical behavior of the pin. Pins Configured as Inputs -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ Arduino (Atmega) pins configured as **INPUT** with pinMode() are said to be in a high-impedance state. One way of explaining this is @@ -117,7 +118,7 @@ reading a sensor, but not powering an LED. Pins Configured as Outputs --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ Pins configured as **OUTPUT** with pinMode() are said to be in a low-impedance state. This means that they can provide a substantial @@ -131,6 +132,158 @@ of current provided by an Atmega pin is also not enough to power most relays or motors, and some interface circuitry will be required. +.. _arduino-fpconstants: + +Floating-Point Constants +------------------------ + +Similar to integer constants, floating point constants are used to +make code more readable. Floating point constants are swapped at +compile time for the value to which the expression evaluates. + + + +Examples: + + + +``n = .005;`` + + + +Floating point constants can also be expressed in a variety of +scientific notation. 'E' and 'e' are both accepted as valid +exponent indicators. + + + +:: + + + floating-point evaluates to: also evaluates to: + constant + + 10.0 10 + 2.34E5 2.34 * 10^5 234000 + 67e-12 67.0 * 10^-12 .000000000067 + +.. _arduino-constants-integers: + +Integer Constants +----------------- + +Integer constants are numbers used directly in a sketch, like +``123``. By default, these numbers are treated as +`int `_'s but you can change +this with the U and L modifiers (see below). + + + +Normally, integer constants are treated as base 10 (decimal) +integers, but special notation (formatters) may be used to enter +numbers in other bases. + + + +:: + + Base Example Formatter Comment + + 10 (decimal) 123 none + + 2 (binary) B1111011 leading 'B' only works with 8 bit values (0 to 255) + characters 0-1 valid + + 8 (octal) 0173 leading "0" characters 0-7 valid + + 16 (hexadecimal) 0x7B leading "0x" characters 0-9, A-F, a-f valid + +.. _arduino-constants-integers-dec: + +**Decimal** is base 10. This is the common-sense math with which +you are acquainted. Constants without other prefixes are assumed to +be in decimal format. + + + +Example: +:: + + 101 // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) + +.. _arduino-constants-integers-bin: + +**Binary** is base two. Only characters 0 and 1 are valid. + + + +Example: +:: + + B101 // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) + +The binary formatter only works on bytes (8 bits) between 0 (B0) +and 255 (B11111111). If it is convenient to input an int (16 bits) +in binary form you can do it a two-step procedure such as: + + + +:: + + myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte + +.. _arduino-constants-integers-oct: + +**Octal** is base eight. Only characters 0 through 7 are valid. Octal +values are indicated by the prefix "0". + +Example: + +:: + + 0101 // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) + +Warning +It is possible to generate a hard-to-find bug by (unintentionally) +including a leading zero before a constant and having the compiler +unintentionally interpret your constant as octal. + +.. _arduino-constants-integers-hex: + +**Hexadecimal (or hex)** is base sixteen. Valid characters are 0 +through 9 and letters A through F; A has the value 10, B is 11, up +to F, which is 15. Hex values are indicated by the prefix "0x". +Note that A-F may be syted in upper or lower case (a-f). + + + +Example: + +:: + + 0x101 // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) + +.. _arduino-constants-integers-u-l: + +U & L formatters +^^^^^^^^^^^^^^^^ + +By default, an integer constant is treated as an +`int `_ with the attendant +limitations in values. To specify an integer constant with another +data type, follow it with: + + + + +- a 'u' or 'U' to force the constant into an unsigned data format. + Example: ``33u`` +- a 'l' or 'L' to force the constant into a long data format. + Example: ``100000L`` +- a 'ul' or 'UL' to force the constant into an unsigned long + constant. Example: ``32767ul`` + + See also @@ -140,5 +293,9 @@ See also - `pinMode() `_ - `Integer Constants `_ - `boolean variables `_ - - +- `#define `_ +- `byte `_ +- `int `_ +- `unsigned int `_ +- `long `_ +- `unsigned long `_ diff --git a/source/arduino/constrain.rst b/source/arduino/constrain.rst index 2769219..eb06122 100644 --- a/source/arduino/constrain.rst +++ b/source/arduino/constrain.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-constrain: constrain(x, a, b) @@ -6,55 +8,55 @@ constrain(x, a, b) Description ----------- -Constrains a number to be within a range. - +(Macro) Constrains a number to be within a range. Parameters ---------- -x: the number to constrain, all data types - - - -a: the lower end of the range, all data types - - - -b: the upper end of the range, all data types +**x**: the number to constrain +**a**: the lower end of the range +**b**: the upper end of the range Returns ------- **x**: if **x** is between **a** and **b** - - **a**: if **x** is less than **a** - - **b**: if **x** is greater than **b** - - Example ------- :: + // limits range of sensor values to between 10 and 150: sensVal = constrain(sensVal, 10, 150); - // limits range of sensor values to between 10 and 150 +Warning +------- -See also --------- +Because of the way ``constrain()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + constrain(x,a++,b); // avoid this - yields incorrect results + + constrain(x,a,b); // use this instead- + a++; // keep other math outside constrain() +Arduino Compatibility +--------------------- -- `min `_\ () -- `max `_\ () +Maple's implementation of ``constrain()`` is compatible with Arduino. +See also +-------- +- :ref:`min() ` +- :ref:`max() ` diff --git a/source/arduino/continue.rst b/source/arduino/continue.rst index 66c7e60..42d7825 100644 --- a/source/arduino/continue.rst +++ b/source/arduino/continue.rst @@ -1,13 +1,15 @@ +.. highlight:: cpp + .. _arduino-continue: continue ======== -The continue statement skips the rest of the current iteration of a -loop (**do**, **for**, or **while**). It continues by checking the -conditional expression of the loop, and proceeding with any -subsequent iterations. - +The ``continue`` keyword skips the rest of the current iteration of a +:ref:`while `\ , :ref:`for `\ , or +:ref:`do/while ` loop. It continues by checking the +conditional expression of the loop, and proceeding with any subsequent +iterations. Example @@ -19,11 +21,11 @@ Example for (x = 0; x < 255; x ++) { if (x > 40 && x < 120){ // create jump in values - continue; + continue; // skips the next two lines and goes to the + // beginning of the loop, with the next value of x } digitalWrite(PWMpin, x); delay(50); } - diff --git a/source/arduino/cos.rst b/source/arduino/cos.rst index 7fed4bb..6b1406a 100644 --- a/source/arduino/cos.rst +++ b/source/arduino/cos.rst @@ -3,31 +3,28 @@ cos(rad) ======== -Description ------------ +Calculate the cosine of an angle (in radians). -Calculates the cos of an angle (in radians). The result will be -between -1 and 1. +Library Documentation +--------------------- -Parameters ----------- +.. doxygenfunction:: cos -rad: the angle in radians (*float*) +Arduino Compatibility +--------------------- +The Maple ``cos()`` implementation is compatible with Arduino. -Returns -------- - -The cos of the angle ("double") - - +Note that the Maple implementation comes from `newlib +`_\ , while Arduino's is that of +`avr-libc `_\ . See also -------- -- `sin `_\ () -- `tan `_\ () -- `float `_ -- `double `_ +- :ref:`sin() ` +- :ref:`tan() ` +- :ref:`float ` +- :ref:`double ` diff --git a/source/arduino/define.rst b/source/arduino/define.rst index 6190cb9..e718775 100644 --- a/source/arduino/define.rst +++ b/source/arduino/define.rst @@ -1,83 +1,53 @@ -.. _arduino-define: - -Define -====== - -``#define`` is a useful C component that allows the programmer to -give a name to a constant value before the program is compiled. -Defined constants in arduino don't take up any program memory space -on the chip. The compiler will replace references to these -constants with the defined value at compile time. - - - -This can have some unwanted side effects though, if for example, a -constant name that had been #defined is included in some other -constant or variable name. In that case the text would be replaced -by the #defined number (or text). - - - -In general, the *`const `_* -keyword is preferred for defining constants and should be used -instead of #define. +.. highlight:: cpp +.. _arduino-define: +#define +======= -Arduino defines have the same syntax as C defines: +``#define`` is a useful C and C++ feature that allows the programmer +to give a name to a constant value before the program is compiled. +The compiler will replace references to these constants with the +defined value at compile time. +This can have some unwanted side effects. In general, the :ref:`const +` keyword is preferred for defining constants. Syntax ------ -``#define constantName value`` +The following line would define the name ``MY_CONSTANT`` to have value +``value``:: + + #define MY_CONSTANT value +Note that the ``#`` is necessary. It is usually good style for the +name to be capitalized, although this is not required. +There is no semicolon after the #define statement. If you include one, +the compiler will likely throw cryptic errors in unrelated places. +That is, **don't do this**:: -Note that the # is necessary. + // DON'T DO THIS! THE SEMICOLON SHOULDN'T BE THERE! + #define NAME value; +Similarly, including an equal sign after the ``#define`` line will +also generate a cryptic compiler error further down the page. That +is, **don't do this, either**:: + // DON'T DO THIS, EITHER! THE EQUALS SIGN SHOULDN'T BE THERE! + #define NAME = value Example ------- :: - #define ledPin 3 - // The compiler will replace any mention of ledPin with the value 3 at compile time. - - - -Tip ---- - -There is no semicolon after the #define statement. If you include -one, the compiler will throw cryptic errors further down the page. - - - -:: - - #define ledPin 3; // this is an error - - - -Similarly, including an equal sign after the #define statement will -also generate a cryptic compiler error further down the page. - - - -:: - - #define ledPin = 3 // this is also an error - - - -See ---- - - -- `const `_ -- `Constants `_ + #define LED_PIN 13 + // The compiler will replace any mention of LED_PIN with + // the value 3 at compile time. +See Also +-------- +- :ref:`const ` diff --git a/source/arduino/delay.rst b/source/arduino/delay.rst index 973c75b..644e8c4 100644 --- a/source/arduino/delay.rst +++ b/source/arduino/delay.rst @@ -1,35 +1,40 @@ +.. highlight:: cpp + .. _arduino-delay: delay() ======= -Description ------------ - -Pauses the program for the amount of time (in miliseconds) -specified as parameter. (There are 1000 milliseconds in a second.) - - - -Syntax ------- +Pauses the program for at least a given number of milliseconds. (There +are 1000 milliseconds in a second.) -delay(ms) +Library Documentation +--------------------- +.. doxygenfunction:: delay -Parameters +Discussion ---------- -ms: the number of milliseconds to pause (*unsigned long*) - - - -Returns -------- - -nothing - +While it is easy to create a blinking LED with the ``delay()`` +function, and many sketches use short delays for such tasks as switch +debouncing, the use of ``delay()`` in a sketch has significant +drawbacks. No other reading of sensors, mathematical calculations, or +pin manipulation can go on during the delay function, so in effect, it +brings most other activity to a halt. For alternative approaches to +controlling timing see the :ref:`millis() ` function +and the "Blink Without Delay" sketch cited :ref:`below +`\ . More knowledgeable programmers usually +avoid the use of ``delay()`` for timing of events longer than tens of +milliseconds, unless the sketch is very simple. + +Certain things *do* go on while the ``delay()`` function is +controlling the STM32 chip, however, because the delay function does +not disable interrupts. Serial communication that appears at the RX +pin is recorded, PWM (see :ref:`pwmWrite() `\ ) +values and pin states are maintained, and :ref:`interrupts +` will work as they should. Example @@ -37,58 +42,26 @@ Example :: - int ledPin = 13; // LED connected to digital pin 13 + int ledPin = 13; // LED connected to pin 13 - void setup() - { + void setup() { pinMode(ledPin, OUTPUT); // sets the digital pin as output } - void loop() - { + void loop() { digitalWrite(ledPin, HIGH); // sets the LED on delay(1000); // waits for a second digitalWrite(ledPin, LOW); // sets the LED off delay(1000); // waits for a second } - - -Caveat ------- - -While it is easy to create a blinking LED with the delay() -function, and many sketches use short delays for such tasks as -switch debouncing, the use of delay() in a sketch has significant -drawbacks. No other reading of sensors, mathematical calculations, -or pin manipulation can go on during the delay function, so in -effect, it brings most other activity to a halt. For alternative -approaches to controlling timing see the -`millis() `_ function and -the sketch sited below. More knowledgeable programmers usually -avoid the use of delay() for timing of events longer than 10's of -milliseconds unless the Arduino sketch is very simple. - - - -Certain things *do* go on while the delay() function is controlling -the Atmega chip however, because the delay function does not -disable interrupts. Serial communication that appears at the RX pin -is recorded, PWM -(`analogWrite `_) -values and pin states are maintained, and -`interrupts `_ will -work as they should. - - +.. _arduino-delay-seealso: See also -------- -- `millis `_\ () -- `micros `_\ () -- `delayMicroseconds `_\ () -- `Blink Without Delay `_ - example - +- :ref:`millis() ` +- :ref:`micros() ` +- :ref:`delayMicroseconds() ` +- (Arduino) `Blink Without Delay `_ example (works unmodified on Maple) diff --git a/source/arduino/delaymicroseconds.rst b/source/arduino/delaymicroseconds.rst index 0feaba7..2c7cde6 100644 --- a/source/arduino/delaymicroseconds.rst +++ b/source/arduino/delaymicroseconds.rst @@ -1,60 +1,34 @@ +.. highlight:: cpp + .. _arduino-delaymicroseconds: delayMicroseconds() =================== -Description ------------ - Pauses the program for the amount of time (in microseconds) specified as parameter. There are a thousand microseconds in a millisecond, and a million microseconds in a second. +Library Documentation +--------------------- - -Currently, the largest value that will produce an accurate delay is -16383. This could change in future Arduino releases. For delays -longer than a few thousand microseconds, you should use delay() -instead. - - - -Syntax ------- - -delayMicroseconds(us) - - - -Parameters ----------- - -us: the number of microseconds to pause (*unsigned int*) - - - -Returns -------- - -None - +.. doxygenfunction:: delayMicroseconds Example ------- -:: - +The following example configures pin number 8 to work as an output +pin, and sends a train of pulses with a period of roughly 100 +microseconds:: - int outPin = 8; // digital pin 8 + int outPin = 8; - void setup() - { + void setup() { pinMode(outPin, OUTPUT); // sets the digital pin as output } - void loop() - { + void loop() { digitalWrite(outPin, HIGH); // sets the pin on delayMicroseconds(50); // pauses for 50 microseconds digitalWrite(outPin, LOW); // sets the pin off @@ -62,32 +36,27 @@ Example } - -configures pin number 8 to work as an output pin. It sends a train -of pulses with 100 microseconds period. - - - Caveats and Known Issues ------------------------ -This function works very accurately in the range 3 microseconds and -up. We cannot assure that delayMicroseconds will perform precisely -for smaller delay-times. - +The longest time ``delayMicroseconds()`` can delay is bounded by its +argument type and the STM32 clock rate to be (2^32 - 1) / 12 +microseconds, or less than 6 minutes. For longer pauses, use of +:ref:`arduino-delay` is possible. +Arduino Compatibility +--------------------- -As of Arduino 0018, delayMicroseconds() no longer disables -interrupts. +While we have made every effort we could to ensure that the timing of +delayMicroseconds is as accurate as possible, we cannot guarantee it +will behave as the Arduino implementation down to the microsecond, +especially for smaller values of ``us``. - - -See also +See Also -------- - -- `millis `_\ () -- `micros `_\ () -- `delay `_\ () +- :ref:`millis ` +- :ref:`micros ` +- :ref:`delay ` diff --git a/source/arduino/detachinterrupt.rst b/source/arduino/detachinterrupt.rst index f0342df..f770de1 100644 --- a/source/arduino/detachinterrupt.rst +++ b/source/arduino/detachinterrupt.rst @@ -1,26 +1,34 @@ .. _arduino-detachinterrupt: -detachInterrupt(interrupt) -========================== +detachInterrupt() +================= -Description ------------ +Used to disable an interrupt specified with +:ref:`arduino-attachinterrupt`\ . -Turns off the given interrupt. +Library Documentation +--------------------- +.. doxygenfunction:: detachInterrupt -Parameters ----------- +Arduino Compatibility +--------------------- -interrupt: the number of interrupt to disable (0 or 1). +There is one important difference between the Maple version of +detachInterrupt and the Arduino version. On the Maple, the argument +to ``detachInterrupt()`` is the *pin* on which the interrupt is +attached, while on the Arduino, the argument is the *interrupt +number*, which is different from the pin the interrupt is enabled on. +If you're calling this function, you've already called +:ref:`arduino-attachinterrupt` to set up your interrupt handler, so +just call ``detachInterrupt()`` with the same pin argument you gave to +``attachInterrupt()``. - -See also +See Also -------- - -- `attachInterrupt `_\ () +- :ref:`attachInterrupt() ` diff --git a/source/arduino/digitalread.rst b/source/arduino/digitalread.rst index ec64fb0..86e52d8 100644 --- a/source/arduino/digitalread.rst +++ b/source/arduino/digitalread.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-digitalread: digitalRead() @@ -6,81 +8,51 @@ digitalRead() Description ----------- -Reads the value from a specified digital pin, either -`HIGH `_ or -`LOW `_. - - - -Syntax ------- - -digitalRead(pin) +Reads the value from a specified digital pin, either :ref:`HIGH +` or :ref:`LOW `. +Library Documentation +--------------------- -Parameters ----------- - -pin: the number of the digital pin you want to read (*int*) - - - -Returns -------- - -`HIGH `_ or -`LOW `_ - +.. doxygenfunction:: digitalRead Example ------- -:: +The following example turns the LED on when the button is pressed:: - - int ledPin = 13; // LED connected to digital pin 13 - int inPin = 7; // pushbutton connected to digital pin 7 - int val = 0; // variable to store the read value + int ledPin = 13; // LED connected to Maple pin 13 + int buttonPin = 38; // BUT connected to Maple pin 38 - void setup() - { - pinMode(ledPin, OUTPUT); // sets the digital pin 13 as output - pinMode(inPin, INPUT); // sets the digital pin 7 as input + void setup() { + pinMode(ledPin, OUTPUT); + pinMode(buttonPin, INPUT); } - void loop() - { - val = digitalRead(inPin); // read the input pin - digitalWrite(ledPin, val); // sets the LED to the button's value + void loop() { + int val = digitalRead(buttonPin); // reads the input pin + digitalWrite(ledPin, val); } - - -Sets pin 13 to the same value as the pin 7, which is an input. - - - Note ---- -If the pin isn't connected to anything, digitalRead() can return -either HIGH or LOW (and this can change randomly). - - +If the pin isn't connected to anything, ``digitalRead()`` can return +either HIGH or LOW (and this can change in a way that seems random). -The analog input pins can be used as digital pins, referred to as -A0, A1, etc. +Arduino Compatibility +--------------------- +The Maple version of ``digitalRead()`` is compatible with Arduino. -See also +See Also -------- +- :ref:`pinMode ` +- :ref:`digitalWrite ` -- `pinMode `_\ () -- `digitalWrite `_\ () -- `Tutorial: Digital Pins `_ diff --git a/source/arduino/double.rst b/source/arduino/double.rst index 4e7f20c..658af12 100644 --- a/source/arduino/double.rst +++ b/source/arduino/double.rst @@ -3,30 +3,44 @@ double ====== -Desciption ----------- +Description +----------- -Double precision floating point number. Occupies 4 bytes. +Double precision floating point number. Occupies 8 bytes. +Floating point numbers are not exact, and may yield strange results +when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You +should instead check that the absolute value of the difference between +the numbers is less than some small number. +Floating point math is also much slower than integer math in +performing calculations, so should be avoided if, for example, a loop +has to run at top speed for a critical timing function. Programmers +often go to some lengths to convert floating point calculations to +integer math to increase speed. -The double implementation on the Arduino is currently exactly the -same as the float, with no gain in precision. +For more information about floating point math, see the `Wikipedia +article `_\ . +Floating-point numbers represent numbers with "decimal point", unlike +integral types, which always represent whole numbers. Floating-point +numbers are often used to approximate analog and continuous values +because they have greater resolution than integers. +The double implementation on the Maple uses twice the number of bytes +as a :ref:`float `, with the corresponding gains in +precision. Tip --- Users who borrow code from other sources that includes double variables may wish to examine the code to see if the implied -precision is different from that actually achieved on the Arduino. +precision is different from that actually achieved on the Maple. +See Also +-------- -See: ----- - - -- `float `_ +- :ref:`float ` diff --git a/source/arduino/dowhile.rst b/source/arduino/dowhile.rst index 48fe75b..697e4b7 100644 --- a/source/arduino/dowhile.rst +++ b/source/arduino/dowhile.rst @@ -1,33 +1,24 @@ -.. _arduino-dowhile: - -do - while -========== +.. highlight:: cpp -The **do** loop works in the same manner as the **while** loop, -with the exception that the condition is tested at the end of the -loop, so the **do** loop will *always* run at least once. +.. _arduino-dowhile: +do/while Loop +============= +A ``do`` loop works in the same manner as a :ref:`while +` loop, with the exception that the condition is tested +at the end of the loop, so the ``do`` loop will *always* run at least +once. -:: +This is the basic syntax:: - do - { + do { // statement block } while (test condition); +Example:: - -Example -------- - -:: - - do - { + do { delay(50); // wait for sensors to stabilize x = readSensors(); // check the sensors - } while (x < 100); - - diff --git a/source/arduino/else.rst b/source/arduino/else.rst index f278a0d..e94bb25 100644 --- a/source/arduino/else.rst +++ b/source/arduino/else.rst @@ -1,73 +1,51 @@ -.. _arduino-else: - -if / else -========= - -**if/else** allows greater control over the flow of code than the -basic **if** statement, by allowing multiple tests to be grouped -together. For example, an analog input could be tested and one -action taken if the input was less than 500, and another action -taken if the input was 500 or greater. The code would look like -this: +.. highlight:: cpp +.. _arduino-else: +if/else +======= -:: +``if``/\ ``else`` allows greater control over the flow of code than +the basic :ref:`if ` statement, by allowing multiple tests +to be grouped together. For example, an :ref:`analog input +` could be tested, with one action taken if the +input was less than 500, and another action taken if the input was 500 +or greater. The code would look like this:: - if (pinFiveInput < 500) - { + if (pinFiveInput < 500) { // action A - } - else - { + } else { // action B } - - -**else** can proceed another **if** test, so that multiple, -mutually exclusive tests can be run at the same time. - - +``else`` can precede another ``if`` test, so that multiple, mutually +exclusive tests can be run at the same time. Each test will proceed to the next one until a true test is -encountered. When a true test is found, its associated block of -code is run, and the program then skips to the line following the -entire if/else construction. If no test proves to be true, the -default **else** block is executed, if one is present, and sets the -default behavior. +encountered. When a true test is found, its associated block of code +is run, and the program then skips to the line following the entire +if/else construction. If no test proves to be true, the default +``else`` block is executed, if one is present, and sets the default +behavior. +Note that an ``else if`` block may be used with or without a +terminating ``else`` block, and vice-versa. An unlimited number of +such ``else if`` branches is allowed. Here is a code example:: -Note that an **else if** block may be used with or without a -terminating **else** block and vice versa. An unlimited number of -such **else if** branches is allowed. - - - -:: - - if (pinFiveInput < 500) - { + if (pinFiveInput < 500) { // do Thing A - } - else if (pinFiveInput >= 1000) - { + } else if (pinFiveInput >= 1000) { // do Thing B - } - else - { + } else { // do Thing C } -Another way to express branching, mutually exclusive tests, is with -the `switch case `_ -statement. - - - -See also: ---------- +Another way to express branching, mutually exclusive tests, is with a +:ref:`switch/case ` statement. -`switch case `_ +See Also +-------- +- :ref:`if ` +- :ref:`switch/case ` diff --git a/source/arduino/float.rst b/source/arduino/float.rst index 2f83a67..683f32d 100644 --- a/source/arduino/float.rst +++ b/source/arduino/float.rst @@ -1,88 +1,55 @@ +.. highlight:: cpp + .. _arduino-float: float ===== +.. TODO move all the useful examples over to arduino/double.rst. We +.. want to discourage using floats, since most of the common cmath +.. functions are only declared with doubles. + Description ----------- -Datatype for floating-point numbers, a number that has a decimal -point. Floating-point numbers are often used to approximate analog -and continuous values because they have greater resolution than -integers. Floating-point numbers can be as large as 3.4028235E+38 -and as low as -3.4028235E+38. They are stored as 32 bits (4 bytes) -of information. - - - -Floats have only 6-7 decimal digits of precision. That means the -total number of digits, not the number to the right of the decimal -point. Unlike other platforms, where you can get more precision by -using a double (e.g. up to 15 digits), on the Arduino, double is -the same size as float. - - +Single-precision floating point number. ``float`` values can be as +large as 3.4028235E+38 and as low as -3.4028235E+38. They are stored +as 32 bits (4 bytes) of information. -Floating point numbers are not exact, and may yield strange results -when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You -should instead check that the absolute value of the difference -between the numbers is less than some small number. +``float``\ s have only 6-7 decimal digits of precision. That means the total +number of digits, not the number to the right of the decimal point. +You can get more precision by using a :ref:`double ` +(which has a precision of about 16 decimal digits). - - -Floating point math is also much slower than integer math in -performing calculations, so should be avoided if, for example, a -loop has to run at top speed for a critical timing function. -Programmers often go to some lengths to convert floating point -calculations to integer math to increase speed. - - - -Examples --------- - -:: +The following example declares a ``float`` value named ``myfloat``:: float myfloat; - float sensorCalbrate = 1.117; - +This example declares a ``float`` value named ``sensorCalibrate``, +with value 1.117:: -Syntax ------- + float sensorCalibrate = 1.117; -:: +The general syntax for declaring a float named ``var`` with value +``val`` is:: float var = val; - - - -- var - your float variable name -- val - the value you assign to that variable - - - -Example Code ------------- - -:: +Here is a more extended example involving a :ref:`float cast +`:: int x; int y; float z; x = 1; - y = x / 2; // y now contains 0, ints can't hold fractions - z = (float)x / 2.0; // z now contains .5 (you have to use 2.0, not 2) - - + y = x / 2; // y now contains 0, ints can't hold fractions + z = float(x) / 2; // z now contains .5 See Also -------- - -- `int `_ -- `double `_ -- `Variable Declaration `_ +- :ref:`int ` +- :ref:`double ` +- :ref:`Variables ` diff --git a/source/arduino/floatcast.rst b/source/arduino/floatcast.rst index 6b85727..773bfe9 100644 --- a/source/arduino/floatcast.rst +++ b/source/arduino/floatcast.rst @@ -1,51 +1,26 @@ +.. highlight:: cpp + .. _arduino-floatcast: -float() -======= +float() (cast) +============== Description ----------- -Converts a value to the -`float `_ data type. - - - -Syntax ------- - -float(x) - - - -Parameters ----------- - -x: a value of any type - +Converts a value to the :ref:`float ` data type. Here +is an example:: + int x = 2; + float f = float(x); // f now holds "2.0", a floating point value -Returns -------- +The value ``x`` can be of any type. However, if ``x`` is not a number +(like an ``int`` or ``long``), you will get strange results. -float +See the :ref:`float ` reference for details about the +precision and limitations of ``float`` values on the Maple. - - -Notes ------ - -See the reference for -`float `_ for details about -the precision and limitations of floating point numbers on -Arduino. - - - -See also +See Also -------- - -- `float `_ - - +- :ref:`float ` diff --git a/source/arduino/for.rst b/source/arduino/for.rst index b7e2e95..cc18722 100644 --- a/source/arduino/for.rst +++ b/source/arduino/for.rst @@ -1,117 +1,139 @@ -.. _arduino-for: - -for statements -============== - -Desciption ----------- - -The **for** statement is used to repeat a block of statements -enclosed in curly braces. An increment counter is usually used to -increment and terminate the loop. The **for** statement is useful -for any repetitive operation, and is often used in combination with -arrays to operate on collections of data/pins. - - - -There are three parts to the **for** loop header: - - - -``for (initialization; condition; increment) {`` +.. highlight:: cpp +.. _arduino-for: +for Loops +========= -``//statement(s);`` - - - -``}`` - -|image0| - +.. contents:: Contents + :local: -The **initialization** happens first and exactly once. Each time -through the loop, the **condition** is tested; if it's true, the -statement block, and the **increment** is executed, then the -**condition** is tested again. When the **condition** becomes -false, the loop ends. +Description +----------- +A ``for`` loop is used to repeat a block of statements enclosed in +curly braces. ``for`` loops are useful for performing repetitive +operations, and are often used in combination with :ref:`arrays +` to operate on collections of data or multiple +:ref:`pins `. A ``for`` loop is composed of two parts: first, a +*header*, which sets up the for loop, and then a *body*, which is made +up of lines of code enclosed in curly braces. + +There are three parts to the ``for`` loop header: an *initialization* +expression, *loop condition* expression, and a *post-loop* +expression. The general syntax looks like this:: + + for (initialization; condition; post-loop) { + // all of these lines inside the curly braces are part + // of the loop body. + statement 1; + statement 2; + ... + } +(Note that there is no semicolon after the post-loop). The +initialization happens first and exactly once, before the loop begins. +Each time through the loop, the condition is tested. The condition is +a :ref:`boolean arduino-boolean` expression. If it is true, then the +list of statements inside the curly braces are executed. Next, the +post-loop is executed. The loop then begins again by evaluating the +condition again, entering the loop body if it is true. This proceeds +until the condition becomes false. -Example -------- +Examples +-------- -:: +Here's an example:: // Dim an LED using a PWM pin - int PWMpin = 10; // LED in series with 470 ohm resistor on pin 10 - - void setup() - { - // no setup needed - } - - void loop() - { - for (int i=0; i <= 255; i++){ - analogWrite(PWMpin, i); - delay(10); - } + int pwmPin = 9; // LED in series with 470 ohm resistor on pin 9 + + void setup() { + pinMode(pwmPin, PWM); } + void loop() { + for (int i=0; i <= 65535; i++) { + pwmWrite(pwmPin, i); + delay(1); + } + } +There is a ``for`` loop In the :ref:`loop() ` function +of the above example. This loop starts by declaring an ``int`` +variable named ``i``, whose value starts out at zero. The loop +proceeds by checking if ``i`` is less than or equal to 65535. Since +``i`` is zero, this is true, and so the calls to :ref:`pwmWrite() +` and :ref:`arduino-delay` happen next. At this +point, the post-loop expression ``i++`` is evaluated, which +:ref:`increments ` ``i``, so that ``i`` becomes +one. That concludes the first time through the loop. Each "time +through the loop" is referred to as an *iteration*. + +The loop then jumps back to the beginning, checking the condition as +the beginning of its second iteration (initialization is skipped, +since this only happens once, before the first iteration). One is +less than 65535, so the loop statements are executed again. This +proceeds over and over until the iteration when ``i`` finally +reaches 65536. At that point, the condition is no longer true, so the +loop stops executing, and the ``loop()`` function returns. + +Here's another example, using a ``for`` loop to brighten and fade an +LED (see the :ref:`pwmWrite() ` reference for more +information):: + + int pwmPin = 9; // hook up the LED to pin 9 + void loop() { + int x = 1; + for (int i = 0; i >= 0; i += x) { + analogWrite(pwmPin, i); // controls the brightness of the LED + if (i == 65535) { + x = -1; // switch direction, so i starts decreasing + } + delay(1); + } + } Coding Tips ----------- -The C **for** loop is much more flexible than **for** loops found -in some other computer languages, including BASIC. Any or all of -the three header elements may be omitted, although the semicolons -are required. Also the statements for initialization, condition, -and increment can be any valid C statements with unrelated -variables, and use any C datatypes including floats. These types of -unusual **for** statements may provide solutions to some rare +The C ``for`` loop is more flexible than ``for`` loops found in some +other computer languages, including BASIC. Any or all of the three +header elements may be left blank, although the semicolons are +required. Also the statements for initialization, condition, and +post-loop can be any valid C statements, and use any C datatypes, +including :ref:`floating point numbers `. These types +of unusual ``for`` loops sometimes provide solutions to less-common programming problems. +For example, using a multiplication in the post-loop line will +generate a `geometric progression +`_:: - -For example, using a multiplication in the increment line will -generate a logarithmic progression: - -:: - - for(int x = 2; x < 100; x = x * 1.5){ - println(x); + for(int x = 1; x <= 100; x = x * 2) { + SerialUSB.println(x); } +This loop prints out the numbers 1, 2, 4, 8, ..., 64. Check +your understanding of ``for`` loops by answering the following two +questions (answers are in footnote [#fanswers]_\ ): -Generates: 2,3,4,6,9,13,19,28,42,63,94 - - - -Another example, fade an LED up and down with one **for** loop: - - - -:: - - void loop() - { - int x = 1; - for (int i = 0; i > -1; i = i + x){ - analogWrite(PWMpin, i); - if (i = 255) x = -1; // switch direction at peak - delay(10); - } - } - +1. How many iterations occur before the loop finishes? +2. Why does it stop at 64? See also -------- +- :ref:`while ` loops +- :ref:`do ` loops + +.. rubric:: Footnotes -- `while `_ +.. [#fanswers] + 1. Seven. + 2. After the seventh iteration, the post-loop causes ``x`` to + equal 128. This is larger than 100, so the loop condition is + false, and the loop stops. diff --git a/source/arduino/fpconstants.rst b/source/arduino/fpconstants.rst deleted file mode 100644 index 284342b..0000000 --- a/source/arduino/fpconstants.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _arduino-fpconstants: - -floating point constants -======================== - -Similar to integer constants, floating point constants are used to -make code more readable. Floating point constants are swapped at -compile time for the value to which the expression evaluates. - - - -Examples: - - - -``n = .005;`` - - - -Floating point constants can also be expressed in a variety of -scientific notation. 'E' and 'e' are both accepted as valid -exponent indicators. - - - -:: - - - floating-point evaluates to: also evaluates to: - constant - - 10.0 10 - 2.34E5 2.34 * 10^5 234000 - 67e-12 67.0 * 10^-12 .000000000067 - - diff --git a/source/arduino/goto.rst b/source/arduino/goto.rst index 1fcceb7..b19d424 100644 --- a/source/arduino/goto.rst +++ b/source/arduino/goto.rst @@ -1,55 +1,127 @@ -.. _arduino-goto: - -goto -==== - -Transfers program flow to a labeled point in the program - - - -Syntax ------- - -label: - - - -goto label; // sends program flow to the label - - +.. highlight:: cpp -Tip ---- - -The use of *goto* is discouraged in C programming, and some authors -of C programming books claim that the *goto* statement is never -necessary, but used judiciously, it can simplify certain programs. -The reason that many programmers frown upon the use of *goto* is -that with the unrestrained use of *goto* statements, it is easy to -create a program with undefined program flow, which can never be -debugged. - - - -With that said, there are instances where a goto statement can come -in handy, and simplify coding. One of these situations is to break -out of deeply nested *for* loops, or *if* logic blocks, on a -certain condition. +.. _arduino-goto: +Labels and goto +=============== + +A *label* gives a name to a line of code within a function. You can +label a line by writing a name for it, then a colon (``:``), before +the line starts. The ``goto`` keyword allows program flow to transfer +to a labeled line from anywhere within the same function. + +.. warning:: The use of ``goto`` is discouraged in C and C++ + programming. It is *never necessary* to use ``goto`` to write a + program. + + Unless you know what you're doing, using ``goto`` tends to + encourage code which is harder to debug and understand than + programs without ``goto`` that do the same thing. That said, + however, it's sometimes useful; :ref:`see below ` + for a concrete example. + +Using Labels and goto +--------------------- + +Labels and ``goto`` are probably best explained through example. +Let's start with an example of how to label lines. The first line +(``int x = analogRead(some_pin);``) in the :ref:`loop ` +function below has label ``readpin``. The third line (``delay(x);``) +has label ``startdelay``. The second line (``SerialUSB.println(x);``) +does not have a label:: + + void loop() { + readpin: + int x = analogRead(some_pin); + SerialUSB.println(x); // for debugging + startdelay: + delay(x); + // ... more code ... + } + +Anything which can be a :ref:`variable ` name can +be a label. + +Let's say that we wanted to print ``x`` only if it was very large, say +at least 2000. We might want to do this just so anybody watching on a +:ref:`serial monitor ` would know they were in for +a longer wait than usual. We can accomplish this through the use of a +``goto`` statement that skips the printing if ``x`` is less than +2000:: + + void loop() { + readpin: + int x = analogRead(some_pin); + if (x < 2000) { + goto startdelay; + } + SerialUSB.println(x); // for debugging + startdelay: + delay(x); + // ... more code ... + } + +In this modified program, whenever ``x`` is less than 2000, the body +of the :ref:`if ` statement in the second line is +executed. The ``goto`` statement inside the ``if`` body skips +straight to the line labeled ``startdelay``, passing over the line +doing the printing. + +A ``goto`` does not have to "move forwards"; it can go "backwards", +too. For example, the following program prints "5" forever (why?):: + + void loop() { + printfive: + SerialUSB.println(5); + goto printfive; + SerialUSB.println(6); + } +.. _goto-when-to-use: -Example -------- +When to Use goto +---------------- -:: +As mentioned above, use of ``goto`` is `generally discouraged +`_. However, +when used with care, ``goto`` can simplify certain programs. One +important use case for ``goto`` is breaking out of deeply nested +:ref:`for ` loops or :ref:`if ` logic blocks. +Here's an example:: - for(byte r = 0; r < 255; r++){ - for(byte g = 255; g > -1; g--){ - for(byte b = 0; b < 255; b++){ - if (analogRead(0) > 250){ goto bailout;} + for(int r = 0; r < 255; r++) { + for(int g = 255; g > -1; g--) { + for(int b = 0; b < 255; b++) { + if (analogRead(0) > 250) { + goto bailout; + } // more statements ... } + // innermost loop ends here } } bailout: + // more code here + +In the above example, whenever the :ref:`analog reading +` on pin 0 was greater than 250, the program would +jump to the line labeled ``bailout``, exiting all three loops at once. + +While there is already a :ref:`break ` keyword for +breaking out of a loop, it will only break out of the *innermost* +loop. So, if instead of saying "``goto bailout;``", there was a +"``break;``" instead, the program would only exit from the loop with +header "``for(int b = 0; b < 255; b++)``". The program would continue +at the line which reads "``// innermost loop ends here``", which is +clearly undesirable if you wanted to leave all three loops at once. + +More examples of when ``goto`` is a good choice are given in Donald +Knuth's paper, "Structured Programming with go to Statements"; see +below for a link. + +See Also +-------- + +- Dijkstra, Edsger W. `Go To Statement Considered Harmful `_ (PDF) +- Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) diff --git a/source/arduino/highbyte.rst b/source/arduino/highbyte.rst index dc6a1d6..0682391 100644 --- a/source/arduino/highbyte.rst +++ b/source/arduino/highbyte.rst @@ -1,42 +1,50 @@ .. _arduino-highbyte: -highByte() -========== - -Description ------------ - -Extracts the high-order (leftmost) byte of a word (or the second -lowest byte of a larger data type). - - +highByte(x) +=========== -Syntax ------- +.. warning:: This macro is provided for compatibility with Arduino + only. It returns the second-least significant byte in an integral + value. It makes sense to call this the "high" byte on a 16-bit + microcontroller like the Atmel chips on Arduinos, but it makes no + sense at all on a 32-bit microcontroller like the STM32s in the + Maple line. -highByte(x) + In short: we provide this so that existing Arduino code works as + expected, but **strongly discourage its use** in new programs. +Description +----------- +(Macro) Extracts the second lowest byte of an integral data type. Parameters ---------- -x: a value of any type +**x**: a value of any integral type. +Returns +------- +Second lowest byte in **x**. -Returns +Example ------- -byte +:: + + int x = 0xDEADBEEF; + SerialUSB.println(x, HEX); // prints "BE" +Arduino Compatibility +--------------------- +The Maple version of ``highByte()`` is compatible with Arduino. -See also +See Also -------- +- :ref:`lowByte() ` -- `lowByte `_\ () -- `word `_\ () diff --git a/source/arduino/if.rst b/source/arduino/if.rst index d75f6d3..00f1a4d 100644 --- a/source/arduino/if.rst +++ b/source/arduino/if.rst @@ -1,95 +1,78 @@ -.. _arduino-if: +.. highlight:: cpp -if (conditional) and ==, !=, <, > (comparison operators) -======================================================== +.. _arduino-if: -**``if``**, which is used in conjunction with a comparison -operator, tests whether a certain condition has been reached, such -as an input being above a certain number. The format for an if test -is: +if Statements +============= +An ``if`` statement is used to execute code when certain conditions +are met. The general syntax for an ``if`` statement is:: + if (condition) { + body + } -:: +An ``if`` statement first tests whether its *condition* is true (such +as an input being above a certain number). If the condition is true, +the ``if`` statement executes its *body*, which is made up of lines of +code inside :ref:`curly braces `. If the condition is +false, the body is not executed. Here's a more concrete example:: - if (someVariable > 50) - { + if (someVariable > 50) { // do something here } +The program tests to see if ``someVariable`` is greater than 50. If it +is, the program executes every line in the curly braces (which in the +above example does nothing, since the body is just the :ref:`comment +` line "``// do something here``"). +Put another way, if the statement in parentheses is true, the +statements inside the braces are run. If not, the program skips over +the code. -The program tests to see if someVariable is greater than 50. If it -is, the program takes a particular action. Put another way, if the -statement in parentheses is true, the statements inside the -brackets are run. If not, the program skips over the code. +An ``if`` statement's condition (which is inside the parentheses after +``if``) often uses one or more :ref:`boolean ` or +:ref:`comparison ` operators. +Writing the if Body +------------------- +The brackets may be omitted after an ``if`` statement's +conditional. If this is done, the next line (which ends in a +semicolon) becomes the only line in the body. The following three +``if`` statements all do the same thing:: -The brackets may be omitted after an *if* statement. If this is -done, the next line (defined by the semicolon) becomes the only -conditional statement. + if (x > 120) digitalWrite(ledPin, HIGH); -:: - - - if (x > 120) digitalWrite(LEDpin, HIGH); - if (x > 120) - digitalWrite(LEDpin, HIGH); - - if (x > 120){ digitalWrite(LEDpin, HIGH); } - - if (x > 120){ - digitalWrite(LEDpin1, HIGH); - digitalWrite(LEDpin2, HIGH); - } // all are correct - - - -The statements being evaluated inside the parentheses require the -use of one or more operators: - - + digitalWrite(ledPin, HIGH); -Comparison Operators: -~~~~~~~~~~~~~~~~~~~~~ + if (x > 120) { + digitalWrite(ledPin, HIGH); + } -:: +However, the following two examples are different:: - x == y (x is equal to y) - x != y (x is not equal to y) - x < y (x is less than y) - x > y (x is greater than y) - x <= y (x is less than or equal to y) - x >= y (x is greater than or equal to y) + // example 1: two lines of code in the if body + if (x > 120) { + digitalWrite(ledPin1, HIGH); + digitalWrite(ledPin2, HIGH); + } + // example 2: one line of code in the if body, and + // another line of code after the if statement + if (x > 120) + digitalWrite(ledPin1, HIGH); // this is in the if body + digitalWrite(ledPin2, HIGH); // this is NOT in the if body +In the first example, since the body is enclosed in curly braces, both +lines are included. In the second example, since the curly braces are +missing, only the first line is in the ``if`` body. -Warning: +See Also -------- -Beware of accidentally using the single equal sign -(e.g.``if (x = 10)`` ). The single equal sign is the assignment -operator, and sets x to 10 (puts the value 10 into the variable x). -Instead use the double equal sign (e.g.``if (x == 10)``), which is -the comparison operator, and tests *whether* x is equal to 10 or -not. The latter statement is only true if x equals 10, but the -former statement will always be true. - - - -This is because C evaluates the statement ``if (x=10)`` as follows: -10 is assigned to x (remember that the single equal sign is the -`assignment operator `_), -so x now contains 10. Then the 'if' conditional evaluates 10, which -always evaluates to TRUE, since any non-zero number evaluates to -TRUE. Consequently, ``if (x = 10)`` will always evaluate to TRUE, -which is not the desired result when using an 'if' statement. -Additionally, the variable x will be set to 10, which is also not a -desired action. - - - -**if** can also be part of a branching control structure using the -`if...else `_] construction. +- :ref:`boolean operators ` +- :ref:`comparison operators ` +- :ref:`else ` diff --git a/source/arduino/include.rst b/source/arduino/include.rst index 6d53801..da124e5 100644 --- a/source/arduino/include.rst +++ b/source/arduino/include.rst @@ -1,42 +1,68 @@ +.. highlight:: cpp + .. _arduino-include: #include ======== -**#include** is used to include outside libraries in your sketch. +``#include`` is used to include outside libraries in your sketch. This gives the programmer access to a large group of standard C -libraries (groups of pre-made functions), and also libraries -written especially for Arduino. - - - -The main reference page for AVR C libraries (AVR is a reference to -the Atmel chips on which the Arduino is based) is -`here. `_ - - - -Note that **#include**, similar to **#define**, has no semicolon -terminator, and the compiler will yield cryptic error messages if -you add one. - - +libraries (groups of pre-made functions and data types), and also +libraries written especially for Maple. Example ------- -This example includes a library that is used to put data into the -program space *flash* instead of *ram*. This saves the ram space -for dynamic memory needs and makes large lookup tables more -practical. - - - -:: - - #include - - prog_uint16_t myConstants[] PROGMEM = {0, 21140, 702 , 9128, 0, 25764, 8456, - 0,0,0,0,0,0,0,0,29810,8968,29762,29762,4500}; - +This example (from the `Arduino LiquidCrystal Tutorial +`_) includes a library +that is used to control :ref:`LCD displays `:: + + // include the library code: + #include + + // initialize the library with the numbers of the interface pins + LiquidCrystal lcd(12, 11, 5, 4, 3, 2); + + void setup() { + // set up the LCD's number of columns and rows: + lcd.begin(16, 2); + // Print a message to the LCD. + lcd.print("hello, world!"); + } + + void loop() { + // set the cursor to column 0, line 1 + // (note: line 1 is the second row, since counting begins with 0): + lcd.setCursor(0, 1); + // print the number of seconds since reset: + lcd.print(millis()/1000); + } + +Note that a ``#include`` line, like :ref:`#define `, +has **no semicolon**. The compiler will print strange error messages +if you add one. + +C Standard Library +------------------ + +The standard C library that comes with Maple is called `newlib +`_. Its main sources of documentation +are its `main reference `_ +page and its `math functions +`_ reference page. Here's an +example that imports the math.h library in order to take the `cube +root `_ of a number:: + + #include + + void setup() { + // no setup necessary + } + + void loop() { + // "cbrt" stands for "cube root" + double cubeRootOf3 = cbrt(3.0); + // prints a number that is approximately the cube root of 3: + SerialUSB.println(cubeRootOf3); + } diff --git a/source/arduino/increment.rst b/source/arduino/increment.rst index f9e87c9..ea9cb88 100644 --- a/source/arduino/increment.rst +++ b/source/arduino/increment.rst @@ -1,58 +1,41 @@ -.. _arduino-increment: +.. highlight:: cpp -++ (increment) / -- (decrement) -=============================== +.. _arduino-increment: -Description ------------ +Increment (``++``) and Decrement (``--``) +========================================= -Increment or decrement a variable +These operators increment (add one to) or decrement (subtract one +from) a variable. If they come before the variable, they return its +new value; otherwise, they return its old value. +Some quick examples:: + x++; // adds one to x, and returns the old value of x + ++x; // adds one to x, and returns the new value of x -Syntax ------- + x--; // decrement x by one and returns the old value of x + --x; // decrement x by one and returns the new value of x -:: +A more extended example:: - x++; // increment x by one and returns the old value of x - ++x; // increment x by one and returns the new value of x - - x-- ; // decrement x by one and returns the old value of x - --x ; // decrement x by one and returns the new value of x + x = 2; + y = ++x; // x now contains 3, y contains 3 + y = x--; // x contains 2 again, y still contains 3 +.. warning:: Be careful! You cannot put a space in between the two + ``+`` or ``-`` signs. This example is broken:: + // this line won't compile (notice the extra space): + int y = x+ +; Parameters ---------- -x: an integer or long (possibly unsigned) - - - -Returns -------- - -The original or newly incremented / decremented value of the -variable. - - - -Examples --------- - -:: - - x = 2; - y = ++x; // x now contains 3, y contains 3 - y = x--; // x contains 2 again, y still contains 3 - - +**x**: an integer value (like an ``int``, ``long``, ``unsigned int``, +etc.). See also -------- -`+= `_ -`-= `_ - - +- :ref:`Compound arithmetic operators ` diff --git a/source/arduino/incrementcompound.rst b/source/arduino/incrementcompound.rst deleted file mode 100644 index 0005fbc..0000000 --- a/source/arduino/incrementcompound.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _arduino-incrementcompound: - -+= , -= , \*= , /= -================== - -Description ------------ - -Perform a mathematical operation on a variable with another -constant or variable. The += (et al) operators are just a -convenient shorthand for the expanded syntax, listed below. - - - -Syntax ------- - -:: - - x += y; // equivalent to the expression x = x + y; - x -= y; // equivalent to the expression x = x - y; - x *= y; // equivalent to the expression x = x * y; - x /= y; // equivalent to the expression x = x / y; - - - -Parameters ----------- - -x: any variable type - - - -y: any variable type or constant - - - -Examples --------- - -:: - - x = 2; - x += 4; // x now contains 6 - x -= 3; // x now contains 3 - x *= 10; // x now contains 30 - x /= 2; // x now contains 15 - - diff --git a/source/arduino/int.rst b/source/arduino/int.rst index 2bb3bef..4bb876c 100644 --- a/source/arduino/int.rst +++ b/source/arduino/int.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-int: int @@ -6,79 +8,60 @@ int Description ----------- -Integers are your primary datatype for number storage, and store a -2 byte value. This yields a range of -32,768 to 32,767 (minimum -value of -2^15 and a maximum value of (2^15) - 1). - - - -Int's store negative numbers with a technique called -`2's complement math. `_ -The highest bit, sometimes refered to as the "sign" bit, flags the -number as a negative number. The rest of the bits are inverted and -1 is added. - - - -The Arduino takes care of dealing with negative numbers for you, so -that arithmetic operations work transparently in the expected -manner. There can be an unexpected complication in dealing with the -`bitshift right operator (>>) `_ -however. - - - -Example -------- - -:: +The ``int`` data type represents integers. Integers are your primary +data type for number storage, and store a 4 byte value. This yields a +range of -2,147,483,648 to 2,147,483,647 (minimum value of -2^31 and a +maximum value of (2^31) - 1; that's about negative 2 billion to +positive 2 billion). - int ledPin = 13; +An ``int`` stores a negative number with a technique called `two's +complement math +`_\ . +The highest bit in an ``int``, sometimes refered to as the "sign" bit, +flags the number as a negative number. (See the linked article on +two's complement for more information). +The Maple takes care of dealing with negative numbers for you, so that +arithmetic operations work mostly as you'd expect. There can be an +:ref:`unexpected complication ` in +dealing with the :ref:`bitshift right operator (>>) +`, however. +Here is an example of declaring an ``int`` variable named ``ledPin``, +then giving it value 13:: -Syntax ------- + int ledPin = 13; -:: +The general syntax for declaring an ``int`` variable named ``var``, +then giving it value ``val``, looks like:: - int var = val; + int var = val; +.. _arduino-int-overflow: +Integer Overflow +---------------- +When ``int`` variables leave the range specified above, they "roll +over" in the other direction. It's like in the game *Pac-Man* -- when +Pac-Man goes past the right edge of the screen, he reappears on the +left, and when he goes past the left side of the screen, he reappears +on the right. Here are some examples:: -- var - your int variable name -- val - the value you assign to that variable - - - -Coding Tip ----------- - -When variables are made to exceed their maximum capacity they "roll -over" back to their minimum capacitiy, note that this happens in -both directions. - - - -:: - - int x - x = -32,768; - x = x - 1; // x now contains 32,767 - rolls over in neg. direction - - x = 32,767; - x = x + 1; // x now contains -32,768 - rolls over - + int x; + x = -2,147,483,648; + x--; // x now contains 2,147,483,647; rolled over "left to right" + x = 2,147,483,647; + x++; // x now contains -2,147,483,648; rolled over "right to left" See Also -------- - -- `byte `_ -- `unsigned int `_ -- `long `_ -- `unsigned long `_ -- `Integer Constants `_ -- `Variable Declaration `_ +- :ref:`unsigned int ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`long ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` diff --git a/source/arduino/intcast.rst b/source/arduino/intcast.rst index d6bcca4..4db65d2 100644 --- a/source/arduino/intcast.rst +++ b/source/arduino/intcast.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-intcast: int() @@ -6,36 +8,22 @@ int() Description ----------- -Converts a value to the `int `_ -data type. - - - -Syntax ------- - -int(x) - - +Converts a value to the :ref:`int ` data type. Here is +an example:: -Parameters ----------- + double d = 2.5; + int i = int(d); // i holds "2", an int value -x: a value of any type +The value inside of the parentheses (``int(...)``) can be of any type. +However, if it is not a numeric type (like ``double``, ``char``, +etc.), you will get strange results. +See the :ref:`int ` reference for details about the +precision and limitations of ``int`` variables on the Maple. - -Returns -------- - -int - - - -See also +See Also -------- - -- `int `_ +- :ref:`int ` diff --git a/source/arduino/integerconstants.rst b/source/arduino/integerconstants.rst deleted file mode 100644 index d60ed24..0000000 --- a/source/arduino/integerconstants.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. _arduino-integerconstants: - -Integer Constants -================= - -Integer constants are numbers used directly in a sketch, like -``123``. By default, these numbers are treated as -`int `_'s but you can change -this with the U and L modifiers (see below). - - - -Normally, integer constants are treated as base 10 (decimal) -integers, but special notation (formatters) may be used to enter -numbers in other bases. - - - -:: - - Base Example Formatter Comment - - 10 (decimal) 123 none - - 2 (binary) B1111011 leading 'B' only works with 8 bit values (0 to 255) - characters 0-1 valid - - 8 (octal) 0173 leading "0" characters 0-7 valid - - 16 (hexadecimal) 0x7B leading "0x" characters 0-9, A-F, a-f valid - - - -**Decimal** is base 10. This is the common-sense math with which -you are acquainted. Constants without other prefixes are assumed to -be in decimal format. - - - -Example: -:: - - 101 // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) - -**Binary** is base two. Only characters 0 and 1 are valid. - - - -Example: -:: - - B101 // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) - -The binary formatter only works on bytes (8 bits) between 0 (B0) -and 255 (B11111111). If it is convenient to input an int (16 bits) -in binary form you can do it a two-step procedure such as: - - - -:: - - myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte - - - -**Octal** is base eight. Only characters 0 through 7 are valid. -Octal values are indicated by the prefix "0" - - - -Example: - -:: - - 0101 // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) - -Warning -It is possible to generate a hard-to-find bug by (unintentionally) -including a leading zero before a constant and having the compiler -unintentionally interpret your constant as octal. -**Hexadecimal (or hex)** is base sixteen. Valid characters are 0 -through 9 and letters A through F; A has the value 10, B is 11, up -to F, which is 15. Hex values are indicated by the prefix "0x". -Note that A-F may be syted in upper or lower case (a-f). - - - -Example: - -:: - - 0x101 // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) - - - -U & L formatters ----------------- - -By default, an integer constant is treated as an -`int `_ with the attendant -limitations in values. To specify an integer constant with another -data type, follow it with: - - - - -- a 'u' or 'U' to force the constant into an unsigned data format. - Example: ``33u`` -- a 'l' or 'L' to force the constant into a long data format. - Example: ``100000L`` -- a 'ul' or 'UL' to force the constant into an unsigned long - constant. Example: ``32767ul`` - - - - - -See also --------- - - -- `constants `_ -- `#define `_ -- `byte `_ -- `int `_ -- `unsigned int `_ -- `long `_ -- `unsigned long `_ - - diff --git a/source/arduino/long.rst b/source/arduino/long.rst index 3d59896..6d20111 100644 --- a/source/arduino/long.rst +++ b/source/arduino/long.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-long: long @@ -6,45 +8,45 @@ long Description ----------- -Long variables are extended size variables for number storage, and -store 32 bits (4 bytes), from -2,147,483,648 to 2,147,483,647. - - - -Example -------- - - - -:: +The ``long`` data type stores extended size integer values. You can +use a ``long`` when your values are too large to fit into an :ref:`int +`. A ``long`` occupies 8 bytes of memory. This yields a +range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion +billion, or about 92 million times the number of stars in the Milky +Way galaxy). The exact range of a ``long`` on the Maple is from +-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to +(2^63-1). - long speedOfLight = 186000L; // see Integer Constants for explanation of the 'L' +Here's an example of declaring a long (see :ref:`integer constants +` for explanation of the 'L'):: + // Speed of light in nanometers per second (approximate). + long c = 299792458000000000L; +The general syntax for declaring an ``long`` variable named ``var``, +then giving it value ``val``, looks like:: -Syntax ------- + long var = val; -:: - - long var = val; - - - - -- var - the long variable name -- val - the value assigned to the variable +This is identical to the ``int`` syntax, with ``long`` replacing +``int``. +Note that ``long`` values will still :ref:`overflow +`, just like ``int`` values, but their much +larger range makes this less likely to happen. +The downside to using a ``long`` instead of an ``int`` (besides the +extra storage) is that :ref:`arithmetic ` +operations on ``long``\ s will take longer than on ``int``\ s. See Also -------- - -- `byte `_ -- `int `_ -- `unsigned int `_ -- `unsigned long `_ -- `Integer Constants `_ -- `Variable Declaration `_ +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`int ` +- :ref:`unsigned int ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` diff --git a/source/arduino/longcast.rst b/source/arduino/longcast.rst index 9f31443..ed23821 100644 --- a/source/arduino/longcast.rst +++ b/source/arduino/longcast.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-longcast: long() @@ -6,36 +8,20 @@ long() Description ----------- -Converts a value to the -`long `_ data type. - - - -Syntax ------- - -long(x) - - - -Parameters ----------- +Converts a value to the :ref:`long ` data type. Here is +an example:: -x: a value of any type + double d = 2.5; + long i = long(d); // i holds "2L", an long value +The value inside of the parentheses (``long(...)``) can be of any type. +However, if it is not a numeric type (like ``double``, ``char``, +etc.), you will get strange results. +See the :ref:`long ` reference for details about the +precision and limitations of ``long`` variables on the Maple. -Returns -------- - -long - - - -See also +See Also -------- - -- `long `_ - - +- :ref:`long ` diff --git a/source/arduino/loop.rst b/source/arduino/loop.rst index 165b7b0..b558edf 100644 --- a/source/arduino/loop.rst +++ b/source/arduino/loop.rst @@ -1,39 +1,42 @@ +.. highlight:: cpp + .. _arduino-loop: loop() ====== -After creating a setup() function, which initializes and sets the -initial values, the loop() function does precisely what its name -suggests, and loops consecutively, allowing your program to change -and respond. Use it to actively control the Arduino board. - - +After creating a :ref:`setup() ` function, which +initializes your sketch, the ``loop()`` function gets called +repeatedly, allowing your program to change and respond. Use it to +actively control your Maple board. Example -~~~~~~~ +------- :: - - int buttonPin = 3; - + + int buttonPin = 38; + // setup initializes serial and the button pin - void setup() - { - beginSerial(9600); + void setup() { + SerialUSB.begin(); pinMode(buttonPin, INPUT); } - - // loop checks the button pin each time, - // and will send serial if it is pressed - void loop() - { - if (digitalRead(buttonPin) == HIGH) - serialWrite('H'); - else - serialWrite('L'); - + + // loop() checks the button pin each time it executes, + // and will print 'H' if it is pressed, 'L' otherwise + void loop() { + if (digitalRead(buttonPin) == HIGH) { + SerialUSB.println('H'); + } else { + SerialUSB.println('L'); + } + delay(1000); } +See Also +-------- + +- :ref:`setup() ` diff --git a/source/arduino/max.rst b/source/arduino/max.rst index 375625c..1e2c619 100644 --- a/source/arduino/max.rst +++ b/source/arduino/max.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-max: max(x, y) @@ -6,19 +8,16 @@ max(x, y) Description ----------- -Calculates the maximum of two numbers. +(Macro) Calculates the maximum of two numbers. Parameters ---------- -x: the first number, any data type - - - -y: the second number, any data type +**x**: the first number; may be any number or numeric expression. +**y**: the second number; may be any number or numeric expression. Returns @@ -26,8 +25,6 @@ Returns The larger of the two parameter values. - - Example ------- @@ -36,36 +33,28 @@ Example sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 // (effectively ensuring that it is at least 20) -Note ----- - -Perhaps counter-intuitively, max() is often used to constrain the -lower end of a variable's range, while min() is used to constrain -the upper end of the range. - - +.. note:: Perhaps counter-intuitively, max() is often used to + constrain the lower end of a variable's range, while :ref:`min() + ` is used to constrain the upper end of the range. Warning ------- -Because of the way the max() function is implemented, avoid using -other functions inside the brackets, it may lead to incorrect -results - - - -:: +Because of the way ``max()`` is implemented, avoid using other +functions inside the parentheses. It may lead to incorrect results:: max(a--, 0); // avoid this - yields incorrect results - + a--; // use this instead - - max(a, 0); // keep other math outside the function + max(a, 0); // keep other operations outside max() +Arduino Compatibility +--------------------- +The Maple version of ``max()`` is compatible with Arduino. -See also +See Also -------- - -- `min `_\ () -- `constrain `_\ () +- :ref:`min() ` +- :ref:`constrain() ` diff --git a/source/arduino/min.rst b/source/arduino/min.rst index fdd7a5f..0ac018c 100644 --- a/source/arduino/min.rst +++ b/source/arduino/min.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-min: min(x, y) @@ -6,19 +8,16 @@ min(x, y) Description ----------- -Calculates the minimum of two numbers. +(Macro) Calculates the minimum of two numbers. Parameters ---------- -x: the first number, any data type - - - -y: the second number, any data type +**x**: the first number; may be any number or numeric expression. +**y**: the second number; may be any number or numeric expression. Returns @@ -27,45 +26,38 @@ Returns The smaller of the two numbers. - -Examples --------- +Example +------- :: sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 // ensuring that it never gets above 100. -Note ----- - -Perhaps counter-intuitively, max() is often used to constrain the -lower end of a variable's range, while min() is used to constrain -the upper end of the range. +.. note:: Perhaps counter-intuitively, max() is often used to + constrain the lower end of a variable's range, while min() is used + to constrain the upper end of the range. Warning ------- -Because of the way the min() function is implemented, avoid using -other functions inside the brackets, it may lead to incorrect -results - - - -:: +Because of the way ``min()`` is implemented, avoid using other +functions inside the parentheses. It may lead to incorrect results:: min(a++, 100); // avoid this - yields incorrect results - - a++; - min(a, 100); // use this instead - keep other math outside the function + a++; // use this instead - + min(a, 100); // keep other operations outside min() +Arduino Compatibility +--------------------- -See also --------- +The Maple version of ``min()`` is compatible with Arduino. +See Also +-------- -- `max `_\ () -- `constrain `_\ () +- :ref:`max() ` +- :ref:`constrain() ` diff --git a/source/arduino/modulo.rst b/source/arduino/modulo.rst index 195d15b..64a546d 100644 --- a/source/arduino/modulo.rst +++ b/source/arduino/modulo.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-modulo: % (modulo) @@ -6,79 +8,67 @@ Description ----------- -Calculates the remainder when one integer is divided by another. It -is useful for keeping a variable within a particular range (e.g. -the size of an array). - - +Calculates the `remainder `_ +when one integer is divided by another. It is useful for keeping a +variable within a particular range (e.g. the size of an array). Syntax ------ -result = dividend % divisor +:: + + result = dividend % divisor Parameters ---------- -dividend: the number to be divided - - - -divisor: the number to divide by - +**dividend**: the number to be divided +**divisor**: the number to divide by Returns ------- -the remainder - - +The remainder of **dividend**\ /\ **divisor**\ . Examples -------- :: + int x; x = 7 % 5; // x now contains 2 x = 9 % 5; // x now contains 4 x = 5 % 5; // x now contains 0 x = 4 % 5; // x now contains 4 - - -Example Code ------------- - :: /* update one value in an array each time through a loop */ - + int values[10]; int i = 0; - - void setup() {} - - void loop() - { - values[i] = analogRead(0); - i = (i + 1) % 10; // modulo operator rolls over variable - } + void setup() { + // no setup necessary + } + void loop() { + values[i] = analogRead(0); + i = (i + 1) % 10; // modulo operator makes sure i stays between 0 and 9 + } Tip --- -The modulo operator does not work on floats. - +The modulo operator does not work on floats. For that, you can use +the C standard library function `fmod() +`_. -See also +See Also -------- - -- `division `_ - +- :ref:`Arithmetic ` diff --git a/source/arduino/pinmode.rst b/source/arduino/pinmode.rst index 34c7998..b34bb31 100644 --- a/source/arduino/pinmode.rst +++ b/source/arduino/pinmode.rst @@ -5,6 +5,12 @@ pinMode() ========= +.. contents:: Contents + :local: + +Library Documentation +--------------------- + .. doxygenfunction:: pinMode .. doxygenenum:: WiringPinMode @@ -13,7 +19,7 @@ Discussion ---------- pinMode() is usually called within :ref:`arduino-setup` in order to -configure a pin for a certain usage (although it may be called from +configure a pin for a certain usage (although it may be called anywhere). @@ -40,8 +46,8 @@ Example -Arduino Compatibility Note --------------------------- +Arduino Compatibility +--------------------- The libmaple implementation of pinMode() supports OUTPUT and INPUT modes with a meaning identical to that of the Arduino function. @@ -64,4 +70,4 @@ See also - :ref:`arduino-digitalwrite` - :ref:`arduino-digitalread` - Maple :ref:`GPIO ` reference page -- Arduino `pinMode() `_ reference + diff --git a/source/arduino/pointer.rst b/source/arduino/pointer.rst index 4e4b9e5..b9bbc48 100644 --- a/source/arduino/pointer.rst +++ b/source/arduino/pointer.rst @@ -1,10 +1,8 @@ .. _arduino-pointer: -The pointer operators -===================== +The pointer operators: & (reference) and \* (dereference) +========================================================= -& (reference) and \* (dereference) -================================== Pointers are one of the more complicated subjects for beginners in learning C, and it is possible to write the vast majority of @@ -13,4 +11,15 @@ manipulating certain data structures, the use of pointers can simplify the code, and and knowledge of manipulating pointers is handy to have in one's toolkit. +Introducing pointers is somewhat outside the scope of this +documentation. However, a good `pointer tutorial +`_ is available. +Also see the `Wikipedia article on pointers +`_, especially +the section on `pointers in C +`_. +See Also +======== + +- http://xkcd.com/138/ diff --git a/source/arduino/pow.rst b/source/arduino/pow.rst index 3a09481..66e67d7 100644 --- a/source/arduino/pow.rst +++ b/source/arduino/pow.rst @@ -3,45 +3,24 @@ pow(base, exponent) =================== -Description ------------ - -Calculates the value of a number raised to a power. Pow() can be -used to raise a number to a fractional power. This is useful for -generating exponential mapping of values or curves. - - - -Parameters ----------- - -base: the number (*float*) - - - -exponent: the power to which the base is raised (*float*) - - - -Returns -------- - -The result of the exponentiation (*double*) +Calculates the value of a number raised to a power. +Library Documentation +--------------------- +.. doxygenfunction:: pow Example ------- -See the `fscale `_ -function in the code library. - +``pow()`` can be used to raise a number to a fractional power. This +is useful for e.g. generating exponential mapping of values or +curves. See the `fscale `_ +function in the Arduino playground for more on this. - -See also +See Also -------- - -- `sqrt `_\ () -- `float `_ -- `double `_ +- :ref:`sqrt() ` +- :ref:`float ` +- :ref:`double ` diff --git a/source/arduino/return.rst b/source/arduino/return.rst index ae3b37d..9774320 100644 --- a/source/arduino/return.rst +++ b/source/arduino/return.rst @@ -1,69 +1,58 @@ +.. highlight:: cpp + .. _arduino-return: return ====== -Terminate a function and return a value from a function to the -calling function, if desired. - - +(Keyword) Terminates a function and return a value from a function to +the calling function, if the function has non-``void`` return type. Syntax: ------- -return; - - - -return value; // both forms are valid - - - -Parameters ----------- +:: -value: any variable or constant type + // from within a "void" function: + return; + // from within a non-"void" function: + return value; +In the second case, ``value`` should have a type which is the same as +the return type of the function, or be convertible to it (like an +``int`` to a ``long``, etc.; see :ref:`this note +` for some references). Examples: --------- -A function to compare a sensor input to a threshold - -:: +A function to compare a sensor input to a threshold:: - int checkSensor(){ + // converts analog readings between 0 and 400 to 0, and 400 up to 1. + int checkSensor() { if (analogRead(0) > 400) { return 1; - else{ + else { return 0; } } +An early ``return`` is also useful when testing a section of code +without having to "comment out" large sections of possibly buggy code, +like so:: + void loop() { -The return keyword is handy to test a section of code without -having to "comment out" large sections of possibly buggy code. - - + // brilliant code idea to test here -:: + return; - void loop(){ - - // brilliant code idea to test here - - return; - - // the rest of a dysfunctional sketch here - // this code will never be executed + // the rest of a dysfunctional sketch here + // this code will never be executed } - - -See also +See Also -------- -`comments `_ - +- :ref:`comments ` diff --git a/source/arduino/scope.rst b/source/arduino/scope.rst index bb56246..0e793ec 100644 --- a/source/arduino/scope.rst +++ b/source/arduino/scope.rst @@ -1,56 +1,59 @@ +.. highlight:: cpp + .. _arduino-scope: Variable Scope ============== -Variables in the C programming language, which Arduino uses, have a -property called *scope*. This is in contrast to languages such as -BASIC where every variable is a *global* variable. - - - -A global variable is one that can be *seen* by every function in a -program. Local variables are only visible to the function in which -they are declared. In the Arduino environment, any variable -declared outside of a function (e.g. setup(), loop(), etc. ), is a -global variable. - +Variables in the C++ programming language, which Maple uses (all of +your sketches are C++ programs in disguise), have a property called +*scope*. This is in contrast to languages such as BASIC where every +variable is a *global* variable. +A global variable is one that can be "seen" by every function in a +program. Local variables are only usable within the function in which +they are declared. In the :ref:`Maple IDE `, any variable +declared outside of a function (like :ref:`setup() `, +:ref:`loop() `, etc.), is a global variable. When programs start to get larger and more complex, local variables -are a useful way to insure that only one function has access to its -own variables. This prevents programming errors when one function +are a useful way to ensure that a function has exclusive access to its +own variables. This prevents programming errors when one function inadvertently modifies variables used by another function. +It is also sometimes useful to declare and initialize a variable +inside a :ref:`for ` loop. This creates a variable that +can only be accessed from inside the loop body. - -It is also sometimes handy to declare and initialize a variable -inside a *for* loop. This creates a variable that can only be -accessed from inside the for-loop brackets. - - +Scope in C++ is actually a fairly complex topic. More information is +available in the `C++ programming Wikibook +`_. Example: -------- :: - int gPWMval; // any function will see this variable - - void setup() - { + int globalVar; // any function will see this variable + + void setup() { // ... } - - void loop() - { + + void loop() { int i; // "i" is only "visible" inside of "loop" float f; // "f" is only "visible" inside of "loop" // ... - + for (int j = 0; j <100; j++){ - // variable j can only be accessed inside the for-loop brackets + // variable j can only be accessed inside the for-loop brackets + i = j * j; } - + i = globalVar; // globalVar can be accessed from anywhere, including loop() } +See Also +-------- + +- `C++ programming Wikibook `_. +- Wikipedia article on `scope `_ diff --git a/source/arduino/semicolon.rst b/source/arduino/semicolon.rst index b3cc8c4..3230819 100644 --- a/source/arduino/semicolon.rst +++ b/source/arduino/semicolon.rst @@ -1,16 +1,11 @@ -.. _arduino-semicolon: - -; semicolon -=========== - -Used to end a statement. - +.. highlight:: cpp +.. _arduino-semicolon: -Example -~~~~~~~ +Semicolon (;) +============= -:: +Used to end a line of code. Example:: int a = 13; diff --git a/source/arduino/serial.rst b/source/arduino/serial.rst index 31ce06c..abba049 100644 --- a/source/arduino/serial.rst +++ b/source/arduino/serial.rst @@ -43,6 +43,9 @@ Functions - `read `_\ () - `flush `_\ () - `print `_\ () + +.. _arduino-serial-println: + - `println `_\ () - `write `_\ () diff --git a/source/arduino/sin.rst b/source/arduino/sin.rst index 3a06a8f..4eb2e1f 100644 --- a/source/arduino/sin.rst +++ b/source/arduino/sin.rst @@ -1,35 +1,25 @@ .. _arduino-sin: -sin(rad) -======== +sin() +===== -Description ------------ +Calculates the `sine `_ of an angle +(in radians). -Calculates the sine of an angle (in radians). The result will be -between -1 and 1. +Library Documentation +--------------------- +.. doxygenfunction:: sin +Arduino Compatibility +--------------------- -Parameters ----------- +The Maple versino of ``sin()`` is compatible with Arduino. -rad: the angle in radians (*float*) - - - -Returns -------- - -the sine of the angle (*double*) - - - -See also +See Also -------- - -- `cos `_\ () -- `tan `_\ () -- `float `_ -- `double `_ +- :ref:`cos ` +- :ref:`tan ` +- :ref:`float ` +- :ref:`double ` diff --git a/source/arduino/sizeof.rst b/source/arduino/sizeof.rst index a95dfbf..104c183 100644 --- a/source/arduino/sizeof.rst +++ b/source/arduino/sizeof.rst @@ -1,71 +1,62 @@ -.. _arduino-sizeof: - -sizeof -====== - -Description ------------ - -The sizeof operator returns the number of bytes in a variable type, -or the number of bytes occupied by an array. +.. highlight:: cpp +.. _arduino-sizeof: +sizeof() +======== Syntax ------ -sizeof(variable) - - +:: -Parameters ----------- + sizeof(type) + sizeof(var) -variable: any variable type or array (e.g. int, float, byte) +Description +----------- -Example code ------------- +The ``sizeof`` operator returns the number of bytes needed to store a +value of a given type. This can be an ordinary numeric type, like +``int``. It can be something more complicated, like a ``struct`` or +``union``. If the argument to ``sizeof`` is an array, it returns the +total number of bytes occupied by the array. -The sizeof operator is useful for dealing with arrays (such as -strings) where it is convenient to be able to change the size of -the array without breaking other parts of the program. +Examplec +-------- +The ``sizeof`` operator is useful for dealing with arrays (such as +strings) where it is convenient to be able to change the size of the +array without breaking other parts of the program. This program prints out a text string one character at a time. Try -changing the text phrase. - - - -:: +changing the text phrase:: char myStr[] = "this is a test"; int i; - - void setup(){ + + void setup() { Serial.begin(9600); } - - void loop() { - for (i = 0; i < sizeof(myStr) - 1; i++){ + + void loop() { + for (i = 0; i < sizeof(myStr) - 1; i++) { Serial.print(i, DEC); Serial.print(" = "); Serial.println(myStr[i], BYTE); } } - - -Note that sizeof returns the total number of bytes. So for larger -variable types such as ints, the for loop would look something like -this. - -:: +Note that ``sizeof`` returns the total number of bytes; this is equal +to the number of ``char``\ s only because the C++ standard guarantees +that ``sizeof(char) == 1``. So for larger variable types such as +``int``, the :ref:`for loop ` would look something like +this:: for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { // do something with myInts[i] } - diff --git a/source/arduino/sq.rst b/source/arduino/sq.rst new file mode 100644 index 0000000..2b6b1fe --- /dev/null +++ b/source/arduino/sq.rst @@ -0,0 +1,39 @@ +.. highlight:: cpp + +.. _arduino-sq: + +sq(a) +===== + +Description +----------- + +(Macro) computes the square of a number. + +Parameters +---------- + +**a**: the number. + +Returns +------- + +**a** squared (**a** × **a**). + +Warning +------- + +Because of the way ``sq()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + b = sq(a++); // avoid this - yields incorrect results + + b = sq(a); // use this instead - + a++; // keep other operations outside sq() + + +Arduino Compatibility +--------------------- + +Maple's implementation of ``sq()`` is compatible with Arduino. diff --git a/source/arduino/sqrt.rst b/source/arduino/sqrt.rst index 5b8a73e..4263345 100644 --- a/source/arduino/sqrt.rst +++ b/source/arduino/sqrt.rst @@ -1,33 +1,22 @@ .. _arduino-sqrt: -sqrt(x) -======= - -Description ------------ +sqrt() +====== Calculates the square root of a number. +Library Documentation +--------------------- +.. doxygenfunction:: sqrt -Parameters ----------- - -x: the number, any data type - - - -Returns -------- +Arduino Compatibility +--------------------- -double, the number's square root. +The Maple versino of ``sqrt()`` is compatible with Arduino. - - -See also +See Also -------- - -- `pow `_\ () -- `sq `_\ () - +- :ref:`pow ` +- :ref:`sq ` diff --git a/source/arduino/static.rst b/source/arduino/static.rst index 1c0340e..b292891 100644 --- a/source/arduino/static.rst +++ b/source/arduino/static.rst @@ -1,71 +1,54 @@ +.. highlight:: cpp + .. _arduino-static: Static ====== -The static keyword is used to create variables that are visible to -only one function. However unlike local variables that get created -and destroyed every time a function is called, static variables -persist beyond the function call, preserving their data between -function calls. - - +The ``static`` keyword can be used to create variables that are +visible to only one function. However, unlike local variables that get +created and destroyed every time a function is called, ``static`` +variables persist beyond the function call, preserving their data +between function calls. -Variables declared as static will only be created and initialized +Variables declared as ``static`` will only be created and initialized the first time a function is called. - +.. note:: This is only one use of the ``static`` keyword in C++. It + has some other important uses that are outside the scope of this + documentation; consult a reliable C++ reference for details. Example ------- -:: +One use case for ``static`` variables is implementing counters that +last longer than the functions which need them, but shouldn't be +shared to other functions. Here's an example:: - - - /* RandomWalk - * Paul Badger 2007 - * RandomWalk wanders up and down randomly between two - * endpoints. The maximum move in one loop is governed by - * the parameter "stepsize". - * A static variable is moved up and down a random amount. - * This technique is also known as "pink noise" and "drunken walk". - */ - - #define randomWalkLowRange -20 - #define randomWalkHighRange 20 - int stepsize; - - int thisTime; - int total; - - void setup() - { - Serial.begin(9600); + void setup() { + SerialUSB.begin(); } - - void loop() - { // tetst randomWalk function - stepsize = 5; - thisTime = randomWalk(stepsize); - Serial.println(thisTime); - delay(10); + + void loop() { + int reading; + if (timeToReadSensors()) { + reading = readSensors(); + } + // do something with reading } - - int randomWalk(int moveSize){ - static int place; // variable to store value in random walk - declared static so that it stores - // values in between function calls, but no other functions can change its value - - place = place + (random(-moveSize, moveSize + 1)); - - if (place < randomWalkLowRange){ // check lower and upper limits - place = place + (randomWalkLowRange - place); // reflect number back in positive direction - } - else if(place > randomWalkHighRange){ - place = place - (place - randomWalkHighRange); // reflect number back in negative direction - } - - return place; + + int readSensors() { + static int numSensorReadings = 0; + numSensorReadings++; + if (numSensorReadings % 100 == 0) { + SerialUSB.print("just got to another 100 sensor readings"); + } + return analogRead(...); } - +In this example, the static variable ``numSensorReadings`` is +initialized to zero the first time ``readSensors()`` is called, and +then incremented, so it starts out at one. Subsequent calls to +``readSensors()`` won't reset ``numSensorReadings`` to zero, because +it was declared ``static``. Thus, ``numSensorReadings`` is a count of +the number of times that ``readSensors()`` has been called. diff --git a/source/arduino/string.rst b/source/arduino/string.rst index b841728..8db400a 100644 --- a/source/arduino/string.rst +++ b/source/arduino/string.rst @@ -1,158 +1,128 @@ +.. highlight:: cpp + .. _arduino-string: -string -====== +Strings +======= Description ----------- -Text strings can be represented in two ways. you can use the String -data type, which is part of the core as of version 0019, or you can -make a string out of an array of type char and null-terminate it. -This page described the latter method. For more details on the -String object, which gives you more functionality at the cost of -more memory, see the -`String object `_ -page. +Text strings can be represented in two ways. You can + +1. Use the :ref:`String ` data type, which is +part of the core as of version 0.0.9, or +2. You can make a string out of an array of type :ref:`char +` and null-terminate it. +This page describes the second method. Examples -------- -All of the following are valid declarations for strings. - -:: - - char Str1[15]; - char Str2[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o'}; - char Str3[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o', '\0'}; - char Str4[ ] = "arduino"; - char Str5[8] = "arduino"; - char Str6[15] = "arduino"; - - - -**Possibilities for declaring strings** - - +All of the following are valid declarations for strings:: + char str1[15]; + char str2[6] = {'m', 'a', 'p', 'l', 'e'}; + char str3[6] = {'m', 'a', 'p', 'l', 'e', '\0'}; + char str4[ ] = "maple"; + char str5[6] = "maple"; + char str6[15] = "maple"; -- Declare an array of chars without initializing it as in Str1 -- Declare an array of chars (with one extra char) and the compiler - will add the required null character, as in Str2 -- Explicitly add the null character, Str3 -- Initialize with a string constant in quotation marks; the - compiler will size the array to fit the string constant and a - terminating null character, Str4 -- Initialize the array with an explicit size and string constant, - Str5 -- Initialize the array, leaving extra space for a larger string, - Str6 +As you can see, there are several methods available for declaring and +initializing strings: +- Declare an array of ``char`` without initializing it, as with ``str1``. +- Declare an array of ``char`` (with one extra ``char``) and the + compiler will add the required null character, as with ``str2``. -**Null termination** +- Explicitly add the null character (``'\0'``), as with ``str3``. +- Initialize with a string constant in quotation marks (``"..."``); + the compiler will size the array to fit the string constant and a + terminating null character (``str4``). +- Initialize the array with an explicit size and string constant, + (``str5``). -Generally, strings are terminated with a null character (ASCII code -0). This allows functions (like Serial.print()) to tell where the -end of a string is. Otherwise, they would continue reading -subsequent bytes of memory that aren't actually part of the -string. +- Initialize the array, leaving extra space for a larger string + (``str6``). +Null Termination +---------------- +Generally, strings are terminated with a null character (`ASCII +`_ code 0). This allows functions +(like ``SerialUSB.print()``) to tell where the end of a string is. +Otherwise, they would continue reading subsequent bytes of memory that +aren't actually part of the string. -This means that your string needs to have space for one more -character than the text you want it to contain. That is why Str2 -and Str5 need to be eight characters, even though "arduino" is only -seven - the last position is automatically filled with a null -character. Str4 will be automatically sized to eight characters, -one for the extra null. In Str3, we've explicitly included the null -character (written '\\0') ourselves. - - +This means that your string needs to have space for one more character +than the text you want it to contain. That is why ``str2`` and +``str5`` need to be six characters, even though "maple" is only five +-- the last position is automatically filled with a NULL +character. ``str4`` will be automatically sized to six characters, one +for the extra null. In the case of ``str3``, we've explicitly included +the null character (written ``'\0'``) ourselves. Note that it's possible to have a string without a final null -character (e.g. if you had specified the length of Str2 as seven -instead of eight). This will break most functions that use strings, -so you shouldn't do it intentionally. If you notice something -behaving strangely (operating on characters not in the string), -however, this could be the problem. - - - -**Single quotes or double quotes?** - - - -Strings are always defined inside double quotes ("Abc") and -characters are always defined inside single quotes('A'). +character (e.g. if you had specified the length of ``str2`` as five +instead of six). This will break most functions that use strings, so +you shouldn't do it intentionally. If you notice something behaving +strangely (operating on characters not in the string), however, this +could be the problem. +Single quotes or double quotes? +------------------------------- +Strings are always defined inside double quotes (``"Abc"``) and +characters are always defined inside single quotes (``'A'``). -**Wrapping long strings** +Wrapping long strings +--------------------- - - -You can wrap long strings like this: - -:: +You can wrap long strings like this:: char myString[] = "This is the first line" - " this is the second line" - " etcetera"; - - - -**Arrays of strings** - + " this is the second line" + " etcetera"; +Arrays of Strings +----------------- It is often convenient, when working with large amounts of text, such as a project with an LCD display, to setup an array of strings. Because strings themselves are arrays, this is in actually an example of a two-dimensional array. - - -In the code below, the asterisk after the datatype char "char\*" +In the code below, the asterisk after the datatype char ``char *`` indicates that this is an array of "pointers". All array names are actually pointers, so this is required to make an array of arrays. Pointers are one of the more esoteric parts of C for beginners to -understand, but it isn't necessary to understand pointers in detail -to use them effectively here. - - - -Example -------- +understand, but it isn't necessary to understand pointers in detail to +use them effectively here:: -:: + char* myStrings[] = {"This is string 1", "This is string 2", + "This is string 3", "This is string 4", + "This is string 5", "This is string 6"}; - - char* myStrings[]={"This is string 1", "This is string 2", "This is string 3", - "This is string 4", "This is string 5","This is string 6"}; - - void setup(){ - Serial.begin(9600); - } - - void loop(){ - for (int i = 0; i < 6; i++){ - Serial.println(myStrings[i]); - delay(500); - } + void setup() { + SerialUSB.begin(); } + void loop() { + for (int i = 0; i < 6; i++) { + SerialUSB.println(myStrings[i]); + delay(500); + } + } See Also -------- - -- `array `_ -- `PROGMEM `_ -- `Variable Declaration `_ - +- :ref:`array ` +- :ref:`__attribute__ ` +- :ref:`Variables ` diff --git a/source/arduino/stringclass.rst b/source/arduino/stringclass.rst new file mode 100644 index 0000000..0c9c61d --- /dev/null +++ b/source/arduino/stringclass.rst @@ -0,0 +1,6 @@ +.. _arduino-stringclass: + +String Class +============ + +Stub. diff --git a/source/arduino/switchcase.rst b/source/arduino/switchcase.rst index 28791eb..1634de1 100644 --- a/source/arduino/switchcase.rst +++ b/source/arduino/switchcase.rst @@ -3,71 +3,72 @@ switch / case statements ======================== -Like **if** statements, **switch...case** controls the flow of -programs by allowing programmers to specify different code that -should be executed in various conditions. In particular, a switch -statement compares the value of a variable to the values specified -in case statements. When a case statement is found whose value -matches that of the variable, the code in that case statement is -run. - - - -The **break** keyword exits the switch statement, and is typically -used at the end of each case. Without a break statement, the switch -statement will continue executing the following expressions -("falling-through") until a break, or the end of the switch -statement is reached. - - - -Example -~~~~~~~ - -:: - - switch (var) { - case 1: - //do something when var equals 1 - break; - case 2: - //do something when var equals 2 - break; - default: - // if nothing else matches, do the default - // default is optional - } - - +Like :ref:`if/else ` blocks, A ``switch`` statement +controls program flow by allowing you to specify different code that +should be executed under various cases. Syntax -~~~~~~ +------ :: switch (var) { - case label: + case val1: // statements break; - case label: + case val2: // statements break; - default: + ... + default: // statements } +Where ``var`` is a variable whose value to investigate, and the +``val1``, ``val2`` after each ``case`` are constant values that +``var`` might be. +Description +----------- -Parameters -~~~~~~~~~~ +A ``switch`` statement compares the value of a variable to the values +specified in ``case`` statements. When a ``case`` statement is found +whose value matches that of the variable, the code in that case +statement is run. -var: the variable whose value to compare to the various cases +The ``break`` keyword exits the switch statement, and is typically +used at the end of each ``case``. Without a ``break``, the ``switch`` +statement will continue executing the following ``case`` expressions +("falling-through") until a ``break`` (or the end of the switch +statement) is reached. +Writing ``default:`` instead of a ``case`` statement allows you to +specify what to do if none of the ``case`` statements matches. Having +a ``default:`` is optional (you can leave it out), but if you have +one, it must appear after all of the ``case`` statements, as shown +above. +``switch`` statements are often used with an ``enum`` value as the +variable to compare. In this case, you can write down all of the +values the ``enum`` takes as ``case`` statements, and be sure you've +covered all the possibilities. -label: a value to compare the variable to +Example +------- +:: + switch (var) { + case 1: + //do something when var equals 1 + break; + case 2: + //do something when var equals 2 + break; + default: + // if nothing else matches, do the default + // default is optional + } See also: --------- diff --git a/source/arduino/variables.rst b/source/arduino/variables.rst new file mode 100644 index 0000000..d79f28b --- /dev/null +++ b/source/arduino/variables.rst @@ -0,0 +1,188 @@ +.. highlight:: cpp + +.. _arduino-variables: + +Variables +--------- + +A variable is a way of naming and storing a value for later use by +the program, such as data from a sensor or an intermediate value +used in a calculation. + + + +Declaring Variables +^^^^^^^^^^^^^^^^^^^ + +Before they are used, all variables have to be declared. Declaring +a variable means defining its type, and optionally, setting an +initial value (initializing the variable). Variables do not have to +be initialized (assigned a value) when they are declared, but it is +often useful. + + + +:: + + int inputVariable1; + int inputVariable2 = 0; // both are correct + + + +Programmers should consider the size of the numbers they wish to +store in choosing variable types. Variables will +`roll over <#VariableRollover>`_ when the value stored exceeds the +space assigned to store it. See below for an example. + + + +Variable Scope +^^^^^^^^^^^^^^ + +Another important choice that programmers face is where to declare +variables. The specific place that variables are declared +influences how various functions in a program will *see* the +variable. This is called variable +`scope `_. + + + +Initializing Variables +^^^^^^^^^^^^^^^^^^^^^^ + +Variables may be *initialized* (assigned a starting value) when +they are declared or not. It is always good programming practice +however to double check that a variable has valid data in it, +before it is accessed for some other purpose. + + + +Example: + +:: + + int calibrationVal = 17; // declare calibrationVal and set initial value + + + +Variable Rollover +^^^^^^^^^^^^^^^^^ + +When variables are made to exceed their maximum capacity they "roll +over" back to their minimum capacity, note that this happens in +both directions. + + + +:: + + int x + x = -32,768; + x = x - 1; // x now contains 32,767 - rolls over in neg. direction + + + +:: + + x = 32,767; + x = x + 1; // x now contains -32,768 - rolls over + + + +Using Variables +^^^^^^^^^^^^^^^ + +Once variables have been declared, they are used by setting the +variable equal to the value one wishes to store with the +`assignment operator `_ +(single equal sign). The assignment operator tells the program to +put whatever is on the right side of the equal sign into the +variable on the left side. + + + +:: + + inputVariable1 = 7; // sets the variable named inputVariable1 to 7 + inputVariable2 = analogRead(2); // sets the variable named inputVariable2 to the + // (digitized) input voltage read from analog pin #2 + + + +Examples +^^^^^^^^ + +:: + + int lightSensVal; + char currentLetter; + unsigned long speedOfLight = 186000UL; + char errorMessage = {"choose another option"}; // see string + + + +Once a variable has been set (assigned a value), you can test its +value to see if it meets certain conditions, or you can use its +value directly. For instance, the following code tests whether the +inputVariable2 is less than 100, then sets a delay based on +inputVariable2 which is a minimum of 100: + + + +:: + + if (inputVariable2 < 100) + { + inputVariable2 = 100; + } + + delay(inputVariable2); + + + +This example shows all three useful operations with variables. It +tests the variable ( ``if (inputVariable2 < 100)`` ), it sets the +variable if it passes the test ( ``inputVariable2 = 100`` ), and it +uses the value of the variable as an input parameter to the delay() +function (``delay(inputVariable2)`` ) + + + +**Style Note:** You should give your variables descriptive names, +so as to make your code more readable. Variable names like +**tiltSensor** or **pushButton** help you (and anyone else reading +your code) understand what the variable represents. Variable names +like **var** or **value**, on the other hand, do little to make +your code readable. + + + +You can name a variable any word that is not already one of the +`keywords `_`? `_ +in Arduino. Avoid beginning variable names with numeral +characters. + + + +Some variable types +^^^^^^^^^^^^^^^^^^^ + + +- `char `_ +- `byte `_ +- `int `_ +- `unsigned int `_ +- `long `_ +- `unsigned long `_ +- `float `_ +- `double `_ + + + +Variable Scope +^^^^^^^^^^^^^^ + + +- `Variable Scope `_ + + diff --git a/source/arduino/while.rst b/source/arduino/while.rst index 5155f09..9ec9f78 100644 --- a/source/arduino/while.rst +++ b/source/arduino/while.rst @@ -1,6 +1,6 @@ .. _arduino-while: -while loops +while Loops =========== Description diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 21379db..8435a1f 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -1,13 +1,34 @@ .. _arm-gcc: -.. _arm-gcc-attribute-flash: ============ GCC on ARM ============ +This document provides an introduction to using +:command:`arm-none-eabi-gcc`\ , the `CodeSourcery +`_ version of the GNU `GCC +`_ compilers used to compile programs for the +Maple. + Stub. -Include special things, differences with AVR-GCC, using -``__attribute__`` to stick things in flash, etc. + +.. _arm-gcc-avr-gcc-diff: + + +Differences with AVR-GCC +------------------------ + +people coming from arduino and other Atmel AVR powered microcontroller +platforms are likely to be used to AVR-GCC. our compiler is +different. explain why (stub). + + +.. _arm-gcc-attribute-flash: + +Tips and Tricks +--------------- + +* you can use ``__attribute__`` to stick things in flash (stub) diff --git a/source/bootloader.rst b/source/bootloader.rst index fea1f35..032b20b 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -4,6 +4,8 @@ Maple Bootloader ================== +.. TODO: [Stub] add a section on flashing your own bootloader + The firmware which allows the Maple to be reprogrammed via a USB connection. Every Maple board comes programmed with this by default, and it is not overwritten by regular programs (it lives lower in the @@ -21,10 +23,10 @@ Flash memory and only runs when the chip is reset). Bootloader Schemes Explained! ----------------------------- -Maple Rev 3 (the version currently shipping) represents a drastic -remake of the core library as well as the upload process. Some of -these changes are aesthetic, refactoring and reorganization. Some are -performance minded. The changes to the bootloader, however, were +Maple Rev 3 and Rev 5 (the version currently shipping) represents a +drastic remake of the core library as well as the upload process. Some +of these changes are aesthetic, refactoring and reorganization. Some +are performance minded. The changes to the bootloader, however, were implemented to solve some really gritty cross platform issues. Before delving in to how the Rev 1 bootloader worked and how the Rev 3 bootloader works now, lets look at the features common to both of them diff --git a/source/compatibility.rst b/source/compatibility.rst index 8872a1b..cf4c2b3 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -75,7 +75,7 @@ The incompatible hardware differences are: Software Language/Library Changes --------------------------------- -With :ref:`one notable exception `, the entire +With :ref:`a few exceptions `, the entire Arduino language is supported. However, there are some subtle differences, most of which are improvements: diff --git a/source/conf.py b/source/conf.py index e1aa3a4..288efad 100644 --- a/source/conf.py +++ b/source/conf.py @@ -59,7 +59,7 @@ copyright = u'2010, LeafLabs, LLC' # The short X.Y version. version = '0.0' # The full version, including alpha/beta/rc tags. -release = '0.0.7' +release = '0.0.9' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/source/foo.rst b/source/foo.rst index 769e666..5631922 100644 --- a/source/foo.rst +++ b/source/foo.rst @@ -6,8 +6,10 @@ This is the index of the imported Arduino docs. +Finished: + .. toctree:: - :maxdepth: 2 + :maxdepth: 1 abs() analogRead() @@ -16,99 +18,104 @@ This is the index of the imported Arduino docs. Arrays Assignment attachInterrupt() - bit + bit() + bitClear() + bitRead() + bitSet() + arduino/bitshift + arduino/analogwrite + arduino/bitwisemath + arduino/bitwisecompound + bitWrite() + arduino/boolean + arduino/booleanvariables + arduino/braces + arduino/break + arduino/byte + arduino/bytecast + arduino/char + arduino/charcast + arduino/comments + arduino/const + constrain() + arduino/continue + cos() + #define + arduino/delay + arduino/delaymicroseconds + arduino/detachinterrupt + arduino/digitalread + arduino/double + arduino/dowhile + arduino/else + arduino/float + arduino/floatcast + arduino/for + arduino/goto + arduino/highbyte + arduino/if + arduino/comparison + arduino/include + arduino/increment + arduino/arithmeticcompound + arduino/int + arduino/intcast + arduino/long + arduino/longcast + arduino/loop + arduino/max + arduino/min + arduino/modulo + arduino/pointer + arduino/pow + arduino/return + arduino/scope + arduino/semicolon + arduino/sin + arduino/sizeof + arduino/sqrt + arduino/sq + arduino/static + arduino/string + +Unfinished; straightforward to convert: + +.. toctree:: + :maxdepth: 1 -.. bitclear -.. bitread -.. bitset -.. bitshift -.. bitwiseand -.. bitwisecompound -.. bitwisexornot -.. bitwrite -.. boolean -.. booleanvariables -.. braces -.. break -.. byte -.. bytecast -.. changes -.. char -.. charcast -.. comments -.. comparison -.. const -.. constants -.. constrain -.. continue -.. cos -.. define -.. delay -.. delaymicroseconds -.. detachinterrupt -.. digitalread -.. digitalwrite -.. double -.. dowhile -.. else -.. float -.. floatcast -.. for -.. fpconstants -.. goto -.. highbyte -.. homepage -.. if -.. include -.. increment -.. incrementcompound -.. int -.. intcast -.. integerconstants -.. interrupts -.. libraries -.. long -.. longcast -.. loop -.. lowbyte -.. map -.. max -.. micros -.. millis -.. min -.. modulo -.. nointerrupts -.. notone -.. pointer -.. pow -.. pulsein -.. random -.. randomseed -.. return -.. scope -.. semicolon -.. serial -.. setup -.. shiftout -.. sin -.. sizeof -.. sqrt -.. static -.. string -.. stringobject -.. switchcase -.. tan -.. tone -.. unsignedchar -.. unsignedint -.. unsignedlong -.. void -.. volatile -.. while -.. word -.. wordcast + arduino/switchcase + arduino/tan + arduino/unsignedchar + arduino/unsignedint + arduino/unsignedlong + arduino/variables + arduino/void + arduino/volatile + arduino/while -.. TODO later +Unfinished, requires libmaple/Arduino knowledge: + +.. toctree:: + :maxdepth: 1 -.. analogreference() -.. analogWrite() + arduino/word + arduino/wordcast + arduino/constants + arduino/digitalwrite + arduino/notone + arduino/serial + arduino/interrupts + analogWrite() + arduino/nointerrupts + arduino/pulsein + arduino/stringobject + arduino/tone + arduino/random + arduino/randomseed + arduino/setup + arduino/map + arduino/shiftout + arduino/micros + arduino/millis + arduino/lowbyte + arduino/stringclass diff --git a/source/gpio.rst b/source/gpio.rst index 7a9031a..ee2b6eb 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -1,8 +1,7 @@ .. _gpio: -====== - GPIO -====== +GPIO +==== The Maple features 38 ready-to-use general purpose input/output (GPIO) pins for digital input/output, numbered D0 through D37. These numbers @@ -80,7 +79,7 @@ above). GPIO Modes ---------- -.. doxygenenum:: WiringMode +.. doxygenenum:: WiringPinMode Function Reference ------------------ diff --git a/source/ide.rst b/source/ide.rst new file mode 100644 index 0000000..c8dbd74 --- /dev/null +++ b/source/ide.rst @@ -0,0 +1,11 @@ +.. _ide: + +Maple IDE Documentation +======================= + +Stub. + +.. _ide-serial-monitor: + +Serial Monitor +-------------- diff --git a/source/index.rst b/source/index.rst index ac92d4b..fdaf801 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,8 +1,3 @@ -.. libmaple documentation master file, created by - sphinx-quickstart on Thu Oct 7 06:42:30 2010. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - .. _index: Maple Documentation Index @@ -24,6 +19,7 @@ Table of contents: Maple Quickstart Guide Maple IDE Installation Guide + Maple IDE Documentation Maple/Arduino Compatibility Reference Maple Language Reference Maple Library Reference @@ -34,6 +30,7 @@ Table of contents: Maple bootloader Known Problems [Temporary] Arduino docs TOC + [Temporary] Wirish-only docs TOC Indices and tables ================== diff --git a/source/language.rst b/source/language.rst index 5a2efad..b2ef017 100644 --- a/source/language.rst +++ b/source/language.rst @@ -193,7 +193,9 @@ Arduino Documentation Links | | | | +------------------------------------+------------------------------------+-----------------------------------------+ -.. _language-no-word: +.. _language-missing-features: + +Stub TODO: fill in other missing features, like analogReference() .. note:: @@ -212,7 +214,7 @@ Arduino Documentation Links can put the following at the top of the file you're porting:: typedef uint16 word; - + .. _if: http://arduino.cc/en/Reference/If .. _if...else: http://arduino.cc/en/Reference/Else .. _for: http://arduino.cc/en/Reference/For @@ -394,7 +396,7 @@ method, which behaves roughly like:: while (true) loop(); } -(The truth is a little bit more complicated, but not by much). +(The truth is a little bit more complicated, but not by much). As an example, consider a sketch with two files. The first file contains ``setup()`` and ``loop()``:: diff --git a/source/libmaple.rst b/source/libmaple.rst index a018cd7..b161afb 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -37,3 +37,4 @@ wrappers and code to imitate the Arduino programming library. Unix Toolchain Quickstart libmaple API reference + Guide to using GCC's ARM target diff --git a/source/pwm.rst b/source/pwm.rst index 178d103..42dc1a5 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -114,7 +114,7 @@ Function Reference .. _pwm-overflow: -``Timer1.setOverflow(overflow)`` +``Timer[1,2,3,4].setOverflow(overflow)`` This function sets the period ("reload" or "overflow") value for an entire PWM timer bank. The value is 16bit (0 to 65535) and @@ -147,6 +147,30 @@ Function Reference This function is normally called once from, `setup()`_, but the timer can be reconfigured with a new prescaler at any time. + * Configure the prescaler and overflow values to generate a timer + * reload with a period as close to the given number of + * microseconds as possible. + * + * The return value is the overflow, which may be used to set + * channel compare values. However, if a clock that fires an + * interrupt every given number of microseconds is all that is + * desired, and the relative "phases" are unimportant, channel + * compare values may all be set to 1. + +``Timer[1,2,3,4].setPeriod(period_in_microseconds)`` + + Configure the prescaler and overflow values to generate a timer + reload with a period as close to the given number of microseconds + as possible. + + The return value is the overflow, which may be used to set channel + compare values. However, if a clock that fires an interrupt every + given number of microseconds is all that is desired, and the + relative "phases" are unimportant, channel compare values may all + be set to 1. + + + Recommended Reading ------------------- diff --git a/source/timers.rst b/source/timers.rst index e0e57cb..fe6ea4a 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -32,6 +32,8 @@ counter to reset to zero more frequently. Caveats ------- +.. _timers-pwm-conflicts: + **PWM Conflicts:** Because PWM functionality on a given pin depends on the configuration of the timer and channel, you must chose your channels carefully if you want to use both timer interrupts and PWM in @@ -196,6 +198,9 @@ from 1 to 4. Note that function call overhead means that the smallest increment rate is a couple microseconds. +.. _timers-attachinterrupt: +.. _timers-detachinterrupt: + ``Timer1.attachCompare1Interrupt(function)``/\ ``Timer1.detachCompare1Interrupt()`` This is how to attach or disable an interrupt handlers to timer diff --git a/source/wirish.rst b/source/wirish.rst new file mode 100644 index 0000000..2773e24 --- /dev/null +++ b/source/wirish.rst @@ -0,0 +1,9 @@ + +[temporary] Wirish Functions +============================ + +.. toctree:: + :maxdepth: 2 + + wirish/pwmwrite + wirish/types diff --git a/source/wirish/pwmwrite.rst b/source/wirish/pwmwrite.rst new file mode 100644 index 0000000..b1f0515 --- /dev/null +++ b/source/wirish/pwmwrite.rst @@ -0,0 +1,52 @@ +.. highlight:: cpp + +.. _wirish-pwmwrite: + +pwmWrite() +========== + +Writes a :ref:`PWM wave ` to a pin. You can use this to make an +LED get brighter or dimmer, control a servomotor, etc. After a call to +pwmWrite(), the pin will output a steady square wave with the given +duty cycle. You can change the duty cycle later by calling pwmWrite() +again with the same pin and a different duty. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: pwmWrite + +Example +------- + +Sets the output to the LED proportional to the value read from the +potentiometer (adapted for Maple from the Arduino `analogWrite() +reference `_\ ):: + + + int ledPin = 13; // LED connected to pin 13 (Maple-specific) + int analogPin = 3; // potentiometer connected to analog pin 3 + int val = 0; // variable to store the read value + + void setup() { + pinMode(ledPin, OUTPUT); // sets the LED pin as output + + pinMode(analogPin, PWM); // sets the potentiometer pin as PWM + // output (Maple-specific) + } + + void loop() { + val = analogRead(analogPin); // read the input pin + + analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, + // analogWrite values from 0 to 65535 + // (Maple-specific) + } + +See Also +-------- + +- :ref:`Maple PWM tutorial ` diff --git a/source/wirish/types.rst b/source/wirish/types.rst new file mode 100644 index 0000000..0b78d01 --- /dev/null +++ b/source/wirish/types.rst @@ -0,0 +1,6 @@ +.. _wirish-types: + +Standard types +============== + +Stub. (uint8, uint64, etc.) -- cgit v1.2.3 From 72a96c4d5f1df99673d8ae31111e313fc576547b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 17 Nov 2010 12:43:21 -0500 Subject: arduino docs nearing completion; CC-BY-SA 3.0 notice appended to all of them --- source/arduino/abs.rst | 3 +++ source/arduino/analogread.rst | 3 +++ source/arduino/analogwrite.rst | 3 +++ source/arduino/arithmetic.rst | 3 +++ source/arduino/arithmeticcompound.rst | 3 +++ source/arduino/array.rst | 3 +++ source/arduino/assignment.rst | 3 +++ source/arduino/attachinterrupt.rst | 3 +++ source/arduino/bit.rst | 3 +++ source/arduino/bitclear.rst | 3 +++ source/arduino/bitread.rst | 3 +++ source/arduino/bitset.rst | 3 +++ source/arduino/bitshift.rst | 3 +++ source/arduino/bitwisecompound.rst | 3 +++ source/arduino/bitwisemath.rst | 3 +++ source/arduino/bitwrite.rst | 3 +++ source/arduino/boolean.rst | 3 +++ source/arduino/booleanvariables.rst | 3 +++ source/arduino/braces.rst | 3 +++ source/arduino/break.rst | 3 +++ source/arduino/byte.rst | 3 +++ source/arduino/bytecast.rst | 3 +++ source/arduino/cc-attribution.txt | 2 +- source/arduino/char.rst | 3 +++ source/arduino/charcast.rst | 3 +++ source/arduino/comments.rst | 3 +++ source/arduino/comparison.rst | 3 +++ source/arduino/const.rst | 3 +++ source/arduino/constants.rst | 3 +++ source/arduino/constrain.rst | 3 +++ source/arduino/continue.rst | 3 +++ source/arduino/cos.rst | 3 +++ source/arduino/define.rst | 3 +++ source/arduino/delay.rst | 3 +++ source/arduino/delaymicroseconds.rst | 3 +++ source/arduino/detachinterrupt.rst | 3 +++ source/arduino/digitalread.rst | 3 +++ source/arduino/digitalwrite.rst | 3 +++ source/arduino/double.rst | 3 +++ source/arduino/dowhile.rst | 3 +++ source/arduino/else.rst | 3 +++ source/arduino/float.rst | 3 +++ source/arduino/floatcast.rst | 3 +++ source/arduino/for.rst | 3 +++ source/arduino/goto.rst | 3 +++ source/arduino/highbyte.rst | 3 +++ source/arduino/if.rst | 3 +++ source/arduino/include.rst | 3 +++ source/arduino/increment.rst | 3 +++ source/arduino/int.rst | 3 +++ source/arduino/intcast.rst | 3 +++ source/arduino/interrupts.rst | 3 +++ source/arduino/long.rst | 3 +++ source/arduino/longcast.rst | 3 +++ source/arduino/loop.rst | 3 +++ source/arduino/lowbyte.rst | 3 +++ source/arduino/map.rst | 3 +++ source/arduino/max.rst | 3 +++ source/arduino/micros.rst | 3 +++ source/arduino/millis.rst | 3 +++ source/arduino/min.rst | 3 +++ source/arduino/modulo.rst | 3 +++ source/arduino/nointerrupts.rst | 3 +++ source/arduino/notone.rst | 3 +++ source/arduino/pinmode.rst | 3 +++ source/arduino/pointer.rst | 3 +++ source/arduino/pow.rst | 3 +++ source/arduino/pulsein.rst | 3 +++ source/arduino/random.rst | 3 +++ source/arduino/randomseed.rst | 3 +++ source/arduino/return.rst | 3 +++ source/arduino/scope.rst | 3 +++ source/arduino/semicolon.rst | 3 +++ source/arduino/serial.rst | 3 +++ source/arduino/setup.rst | 3 +++ source/arduino/shiftout.rst | 3 +++ source/arduino/sin.rst | 3 +++ source/arduino/sizeof.rst | 3 +++ source/arduino/sq.rst | 3 +++ source/arduino/sqrt.rst | 3 +++ source/arduino/static.rst | 3 +++ source/arduino/string.rst | 3 +++ source/arduino/stringclass.rst | 3 +++ source/arduino/stringobject.rst | 3 +++ source/arduino/switchcase.rst | 3 +++ source/arduino/tan.rst | 3 +++ source/arduino/tone.rst | 3 +++ source/arduino/unsignedchar.rst | 3 +++ source/arduino/unsignedint.rst | 3 +++ source/arduino/unsignedlong.rst | 3 +++ source/arduino/variables.rst | 3 +++ source/arduino/void.rst | 3 +++ source/arduino/volatile.rst | 3 +++ source/arduino/while.rst | 3 +++ source/arduino/word.rst | 3 +++ source/arduino/wordcast.rst | 3 +++ 96 files changed, 286 insertions(+), 1 deletion(-) diff --git a/source/arduino/abs.rst b/source/arduino/abs.rst index ed7296a..0ec6b47 100644 --- a/source/arduino/abs.rst +++ b/source/arduino/abs.rst @@ -37,3 +37,6 @@ Arduino Compatibility --------------------- Maple's implementation of ``abs()`` is compatible with Arduino. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/analogread.rst b/source/arduino/analogread.rst index 9577c62..cd18567 100644 --- a/source/arduino/analogread.rst +++ b/source/arduino/analogread.rst @@ -147,3 +147,6 @@ See also should first read ST's application notes on `ADC modes `_ and `ADC oversampling `_. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/analogwrite.rst b/source/arduino/analogwrite.rst index d04f485..a1057ab 100644 --- a/source/arduino/analogwrite.rst +++ b/source/arduino/analogwrite.rst @@ -159,3 +159,6 @@ See also .. [#fuint16max] This is because the value for the duty cycle on the Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) integer with size 2 bytes can hold the values between 0 and 65,535. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/arithmetic.rst b/source/arduino/arithmetic.rst index 8fb9771..412a0be 100644 --- a/source/arduino/arithmetic.rst +++ b/source/arduino/arithmetic.rst @@ -124,3 +124,6 @@ See Also . - :ref:`sizeof `\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/arithmeticcompound.rst b/source/arduino/arithmeticcompound.rst index a2c5b89..734ef9d 100644 --- a/source/arduino/arithmeticcompound.rst +++ b/source/arduino/arithmeticcompound.rst @@ -41,3 +41,6 @@ See Also -------- - :ref:`Arithmetic operators ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/array.rst b/source/arduino/array.rst index 92f3091..e49cc18 100644 --- a/source/arduino/array.rst +++ b/source/arduino/array.rst @@ -118,3 +118,6 @@ See also - :ref:`Storing arrays in FLASH memory ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/assignment.rst b/source/arduino/assignment.rst index 21e90e9..4907473 100644 --- a/source/arduino/assignment.rst +++ b/source/arduino/assignment.rst @@ -65,3 +65,6 @@ See Also `The Anatomy of the Assignment Operator `_ for more information. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/attachinterrupt.rst b/source/arduino/attachinterrupt.rst index cb11327..3714709 100644 --- a/source/arduino/attachinterrupt.rst +++ b/source/arduino/attachinterrupt.rst @@ -97,3 +97,6 @@ See also - :ref:`detachInterrupt ` - :ref:`external-interrupts` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bit.rst b/source/arduino/bit.rst index b74ad3d..f25236c 100644 --- a/source/arduino/bit.rst +++ b/source/arduino/bit.rst @@ -43,3 +43,6 @@ See also - :ref:`arduino-bitwrite` - :ref:`arduino-bitset` - :ref:`arduino-bitclear` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitclear.rst b/source/arduino/bitclear.rst index 8a46877..14261a6 100644 --- a/source/arduino/bitclear.rst +++ b/source/arduino/bitclear.rst @@ -42,3 +42,6 @@ See also - :ref:`bitRead `\ () - :ref:`bitWrite `\ () - :ref:`bitSet `\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitread.rst b/source/arduino/bitread.rst index c3a79c4..f2cb037 100644 --- a/source/arduino/bitread.rst +++ b/source/arduino/bitread.rst @@ -44,3 +44,6 @@ See also - :ref:`arduino-bitwrite` - :ref:`arduino-bitset` - :ref:`arduino-bitclear` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitset.rst b/source/arduino/bitset.rst index adf637a..b6964a0 100644 --- a/source/arduino/bitset.rst +++ b/source/arduino/bitset.rst @@ -44,3 +44,6 @@ See Also - :ref:`arduino-bitwrite` - :ref:`arduino-bitclear` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitshift.rst b/source/arduino/bitshift.rst index d849f2a..00c466f 100644 --- a/source/arduino/bitshift.rst +++ b/source/arduino/bitshift.rst @@ -143,3 +143,6 @@ See Also - :ref:`arduino-bitread` - :ref:`arduino-bitwrite` - :ref:`arduino-bitclear` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitwisecompound.rst b/source/arduino/bitwisecompound.rst index d460dc8..92f3fdd 100644 --- a/source/arduino/bitwisecompound.rst +++ b/source/arduino/bitwisecompound.rst @@ -226,3 +226,6 @@ See Also - :ref:`Boolean operations ` (``&&``, ``||``) - :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitwisemath.rst b/source/arduino/bitwisemath.rst index 3f102eb..196cc2c 100644 --- a/source/arduino/bitwisemath.rst +++ b/source/arduino/bitwisemath.rst @@ -181,3 +181,6 @@ See Also - :ref:`Boolean operations ` (``&&``, ``||``) - :ref:`Compound bitwise operations ` (``&=``, ``|=``, ``^=``). + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitwrite.rst b/source/arduino/bitwrite.rst index b35a54f..0e57cc4 100644 --- a/source/arduino/bitwrite.rst +++ b/source/arduino/bitwrite.rst @@ -35,3 +35,6 @@ See also - :ref:`bitRead() ` - :ref:`bitSet() ` - :ref:`bitClear() ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/boolean.rst b/source/arduino/boolean.rst index a724c20..8106520 100644 --- a/source/arduino/boolean.rst +++ b/source/arduino/boolean.rst @@ -84,3 +84,6 @@ See Also - :ref:`Compound bitwise operators ` (``&=``, ``|=``, ``^=``). - :ref:`if statement ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/booleanvariables.rst b/source/arduino/booleanvariables.rst index 772db0f..a5f2c51 100644 --- a/source/arduino/booleanvariables.rst +++ b/source/arduino/booleanvariables.rst @@ -50,3 +50,6 @@ See also - :ref:`Boolean constants ` - :ref:`Boolean operators ` - :ref:`Variables ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/braces.rst b/source/arduino/braces.rst index 1ae34e8..38018fe 100644 --- a/source/arduino/braces.rst +++ b/source/arduino/braces.rst @@ -92,3 +92,6 @@ reference page for more information):: .. [#fbug] At present this feature is slightly buggy as the IDE will often find (incorrectly) a brace in text that has been commented out. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/break.rst b/source/arduino/break.rst index 57009c1..8c0478a 100644 --- a/source/arduino/break.rst +++ b/source/arduino/break.rst @@ -30,3 +30,6 @@ Example } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/byte.rst b/source/arduino/byte.rst index 0b21b31..8478d0b 100644 --- a/source/arduino/byte.rst +++ b/source/arduino/byte.rst @@ -29,3 +29,6 @@ See Also - :ref:`byte() ` (casting a value to a byte) - :ref:`Variables ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bytecast.rst b/source/arduino/bytecast.rst index bf85a35..38aec36 100644 --- a/source/arduino/bytecast.rst +++ b/source/arduino/bytecast.rst @@ -48,3 +48,6 @@ See Also - :ref:`arduino-byte` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/cc-attribution.txt b/source/arduino/cc-attribution.txt index e662eeb..e100140 100644 --- a/source/arduino/cc-attribution.txt +++ b/source/arduino/cc-attribution.txt @@ -1,7 +1,7 @@ .. Included in all this directory's files in order to satisfy the .. Arduino CC Attribution-ShareAlike 3.0 License -.. admonition:: License +.. admonition:: License and Attribution This documentation page was adapted from the `Arduino Reference Documentation `_\ , which diff --git a/source/arduino/char.rst b/source/arduino/char.rst index 53dd060..72d5ef2 100644 --- a/source/arduino/char.rst +++ b/source/arduino/char.rst @@ -47,3 +47,6 @@ See also - :ref:`arduino-array` (a string is just an array of ``char``\ s) - :ref:`Serial.println() ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/charcast.rst b/source/arduino/charcast.rst index d8184c1..91a0f8f 100644 --- a/source/arduino/charcast.rst +++ b/source/arduino/charcast.rst @@ -34,3 +34,6 @@ See Also -------- - :ref:`char ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/comments.rst b/source/arduino/comments.rst index 3aeb37f..e46fc48 100644 --- a/source/arduino/comments.rst +++ b/source/arduino/comments.rst @@ -58,3 +58,6 @@ a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/comparison.rst b/source/arduino/comparison.rst index 85c2118..e5e92d7 100644 --- a/source/arduino/comparison.rst +++ b/source/arduino/comparison.rst @@ -82,3 +82,6 @@ Comparison operators, along with :ref:`boolean operators (This sometimes has uses, though, so just because an assignment appears within a conditional doesn't mean it's automatically wrong. Be careful to know what you mean.) + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/const.rst b/source/arduino/const.rst index 4a45387..eb2b07b 100644 --- a/source/arduino/const.rst +++ b/source/arduino/const.rst @@ -47,3 +47,6 @@ See Also - :ref:`#define ` - :ref:`volatile ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/constants.rst b/source/arduino/constants.rst index b082774..3a819b3 100644 --- a/source/arduino/constants.rst +++ b/source/arduino/constants.rst @@ -299,3 +299,6 @@ See also - `unsigned int `_ - `long `_ - `unsigned long `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/constrain.rst b/source/arduino/constrain.rst index eb06122..a43b8f8 100644 --- a/source/arduino/constrain.rst +++ b/source/arduino/constrain.rst @@ -60,3 +60,6 @@ See also - :ref:`min() ` - :ref:`max() ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/continue.rst b/source/arduino/continue.rst index 42d7825..31af3a5 100644 --- a/source/arduino/continue.rst +++ b/source/arduino/continue.rst @@ -29,3 +29,6 @@ Example delay(50); } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/cos.rst b/source/arduino/cos.rst index 6b1406a..e1188d0 100644 --- a/source/arduino/cos.rst +++ b/source/arduino/cos.rst @@ -28,3 +28,6 @@ See also - :ref:`tan() ` - :ref:`float ` - :ref:`double ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/define.rst b/source/arduino/define.rst index e718775..6a403d4 100644 --- a/source/arduino/define.rst +++ b/source/arduino/define.rst @@ -51,3 +51,6 @@ Example See Also -------- - :ref:`const ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/delay.rst b/source/arduino/delay.rst index 644e8c4..64d78aa 100644 --- a/source/arduino/delay.rst +++ b/source/arduino/delay.rst @@ -65,3 +65,6 @@ See also - :ref:`micros() ` - :ref:`delayMicroseconds() ` - (Arduino) `Blink Without Delay `_ example (works unmodified on Maple) + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/delaymicroseconds.rst b/source/arduino/delaymicroseconds.rst index 2c7cde6..10f3a1b 100644 --- a/source/arduino/delaymicroseconds.rst +++ b/source/arduino/delaymicroseconds.rst @@ -60,3 +60,6 @@ See Also - :ref:`delay ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/detachinterrupt.rst b/source/arduino/detachinterrupt.rst index f770de1..6e037e6 100644 --- a/source/arduino/detachinterrupt.rst +++ b/source/arduino/detachinterrupt.rst @@ -32,3 +32,6 @@ See Also - :ref:`attachInterrupt() ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/digitalread.rst b/source/arduino/digitalread.rst index 86e52d8..daf04f8 100644 --- a/source/arduino/digitalread.rst +++ b/source/arduino/digitalread.rst @@ -56,3 +56,6 @@ See Also + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/digitalwrite.rst b/source/arduino/digitalwrite.rst index 82e1813..b80d5c6 100644 --- a/source/arduino/digitalwrite.rst +++ b/source/arduino/digitalwrite.rst @@ -111,3 +111,6 @@ See also - `Tutorial: Digital Pins `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/double.rst b/source/arduino/double.rst index 658af12..d1c1076 100644 --- a/source/arduino/double.rst +++ b/source/arduino/double.rst @@ -44,3 +44,6 @@ See Also - :ref:`float ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/dowhile.rst b/source/arduino/dowhile.rst index 697e4b7..7dffe50 100644 --- a/source/arduino/dowhile.rst +++ b/source/arduino/dowhile.rst @@ -22,3 +22,6 @@ Example:: delay(50); // wait for sensors to stabilize x = readSensors(); // check the sensors } while (x < 100); + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/else.rst b/source/arduino/else.rst index e94bb25..9345e8a 100644 --- a/source/arduino/else.rst +++ b/source/arduino/else.rst @@ -49,3 +49,6 @@ See Also - :ref:`if ` - :ref:`switch/case ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/float.rst b/source/arduino/float.rst index 683f32d..aa3bd99 100644 --- a/source/arduino/float.rst +++ b/source/arduino/float.rst @@ -53,3 +53,6 @@ See Also - :ref:`double ` - :ref:`Variables ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/floatcast.rst b/source/arduino/floatcast.rst index 773bfe9..6a2e799 100644 --- a/source/arduino/floatcast.rst +++ b/source/arduino/floatcast.rst @@ -24,3 +24,6 @@ See Also -------- - :ref:`float ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/for.rst b/source/arduino/for.rst index cc18722..43b82fa 100644 --- a/source/arduino/for.rst +++ b/source/arduino/for.rst @@ -137,3 +137,6 @@ See also 2. After the seventh iteration, the post-loop causes ``x`` to equal 128. This is larger than 100, so the loop condition is false, and the loop stops. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/goto.rst b/source/arduino/goto.rst index b19d424..e683c98 100644 --- a/source/arduino/goto.rst +++ b/source/arduino/goto.rst @@ -125,3 +125,6 @@ See Also - Dijkstra, Edsger W. `Go To Statement Considered Harmful `_ (PDF) - Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/highbyte.rst b/source/arduino/highbyte.rst index 0682391..74717c1 100644 --- a/source/arduino/highbyte.rst +++ b/source/arduino/highbyte.rst @@ -48,3 +48,6 @@ See Also + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/if.rst b/source/arduino/if.rst index 00f1a4d..89af166 100644 --- a/source/arduino/if.rst +++ b/source/arduino/if.rst @@ -76,3 +76,6 @@ See Also - :ref:`boolean operators ` - :ref:`comparison operators ` - :ref:`else ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/include.rst b/source/arduino/include.rst index da124e5..37553f4 100644 --- a/source/arduino/include.rst +++ b/source/arduino/include.rst @@ -66,3 +66,6 @@ root `_ of a number:: SerialUSB.println(cubeRootOf3); } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/increment.rst b/source/arduino/increment.rst index ea9cb88..38dee6c 100644 --- a/source/arduino/increment.rst +++ b/source/arduino/increment.rst @@ -39,3 +39,6 @@ See also -------- - :ref:`Compound arithmetic operators ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/int.rst b/source/arduino/int.rst index 4bb876c..690deb8 100644 --- a/source/arduino/int.rst +++ b/source/arduino/int.rst @@ -65,3 +65,6 @@ See Also - :ref:`unsigned long ` - :ref:`Integer Constants ` - :ref:`Variables ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/intcast.rst b/source/arduino/intcast.rst index 4db65d2..0b34a39 100644 --- a/source/arduino/intcast.rst +++ b/source/arduino/intcast.rst @@ -27,3 +27,6 @@ See Also - :ref:`int ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/interrupts.rst b/source/arduino/interrupts.rst index 282362b..b9c95b1 100644 --- a/source/arduino/interrupts.rst +++ b/source/arduino/interrupts.rst @@ -57,3 +57,6 @@ See Also - `detachInterrupt `_\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/long.rst b/source/arduino/long.rst index 6d20111..cae659a 100644 --- a/source/arduino/long.rst +++ b/source/arduino/long.rst @@ -50,3 +50,6 @@ See Also - :ref:`Integer Constants ` - :ref:`Variables ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/longcast.rst b/source/arduino/longcast.rst index ed23821..f247dae 100644 --- a/source/arduino/longcast.rst +++ b/source/arduino/longcast.rst @@ -25,3 +25,6 @@ See Also -------- - :ref:`long ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/loop.rst b/source/arduino/loop.rst index b558edf..4383ab6 100644 --- a/source/arduino/loop.rst +++ b/source/arduino/loop.rst @@ -40,3 +40,6 @@ See Also -------- - :ref:`setup() ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/lowbyte.rst b/source/arduino/lowbyte.rst index d69f66a..9331181 100644 --- a/source/arduino/lowbyte.rst +++ b/source/arduino/lowbyte.rst @@ -40,3 +40,6 @@ See also - `word `_\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/map.rst b/source/arduino/map.rst index 65647fa..61aa626 100644 --- a/source/arduino/map.rst +++ b/source/arduino/map.rst @@ -117,3 +117,6 @@ See Also - `constrain `_\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/max.rst b/source/arduino/max.rst index 1e2c619..a80c421 100644 --- a/source/arduino/max.rst +++ b/source/arduino/max.rst @@ -58,3 +58,6 @@ See Also - :ref:`min() ` - :ref:`constrain() ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/micros.rst b/source/arduino/micros.rst index cdee497..bd8b926 100644 --- a/source/arduino/micros.rst +++ b/source/arduino/micros.rst @@ -64,3 +64,6 @@ See also - `delay `_\ () - `delayMicroseconds `_\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/millis.rst b/source/arduino/millis.rst index 009517d..12f5d8d 100644 --- a/source/arduino/millis.rst +++ b/source/arduino/millis.rst @@ -65,3 +65,6 @@ See also - `delayMicroseconds `_\ () - `Tutorial: Blink Without Delay `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/min.rst b/source/arduino/min.rst index 0ac018c..efe78ca 100644 --- a/source/arduino/min.rst +++ b/source/arduino/min.rst @@ -61,3 +61,6 @@ See Also - :ref:`max() ` - :ref:`constrain() ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/modulo.rst b/source/arduino/modulo.rst index 64a546d..bb65600 100644 --- a/source/arduino/modulo.rst +++ b/source/arduino/modulo.rst @@ -72,3 +72,6 @@ See Also -------- - :ref:`Arithmetic ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/nointerrupts.rst b/source/arduino/nointerrupts.rst index 10d504d..8711ebb 100644 --- a/source/arduino/nointerrupts.rst +++ b/source/arduino/nointerrupts.rst @@ -54,3 +54,6 @@ See Also - `interrupts `_\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/notone.rst b/source/arduino/notone.rst index 4390b52..9e59065 100644 --- a/source/arduino/notone.rst +++ b/source/arduino/notone.rst @@ -45,3 +45,6 @@ See also - `tone `_ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pinmode.rst b/source/arduino/pinmode.rst index b34bb31..e84e1e6 100644 --- a/source/arduino/pinmode.rst +++ b/source/arduino/pinmode.rst @@ -71,3 +71,6 @@ See also - :ref:`arduino-digitalread` - Maple :ref:`GPIO ` reference page + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pointer.rst b/source/arduino/pointer.rst index b9bbc48..efc81ca 100644 --- a/source/arduino/pointer.rst +++ b/source/arduino/pointer.rst @@ -23,3 +23,6 @@ See Also ======== - http://xkcd.com/138/ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pow.rst b/source/arduino/pow.rst index 66e67d7..0a7355c 100644 --- a/source/arduino/pow.rst +++ b/source/arduino/pow.rst @@ -24,3 +24,6 @@ See Also - :ref:`sqrt() ` - :ref:`float ` - :ref:`double ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pulsein.rst b/source/arduino/pulsein.rst index 568d992..f26f754 100644 --- a/source/arduino/pulsein.rst +++ b/source/arduino/pulsein.rst @@ -77,3 +77,6 @@ Example } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/random.rst b/source/arduino/random.rst index 44f122a..8da92b0 100644 --- a/source/arduino/random.rst +++ b/source/arduino/random.rst @@ -90,3 +90,6 @@ See also - `randomSeed `_\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/randomseed.rst b/source/arduino/randomseed.rst index b0b5d71..983c66d 100644 --- a/source/arduino/randomseed.rst +++ b/source/arduino/randomseed.rst @@ -68,3 +68,6 @@ See also - `random `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/return.rst b/source/arduino/return.rst index 9774320..fd1493d 100644 --- a/source/arduino/return.rst +++ b/source/arduino/return.rst @@ -56,3 +56,6 @@ See Also -------- - :ref:`comments ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/scope.rst b/source/arduino/scope.rst index 0e793ec..5974825 100644 --- a/source/arduino/scope.rst +++ b/source/arduino/scope.rst @@ -57,3 +57,6 @@ See Also - `C++ programming Wikibook `_. - Wikipedia article on `scope `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/semicolon.rst b/source/arduino/semicolon.rst index 3230819..b90d925 100644 --- a/source/arduino/semicolon.rst +++ b/source/arduino/semicolon.rst @@ -20,3 +20,6 @@ missing semicolon, in the immediate vicinity, preceding the line at which the compiler complained. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/serial.rst b/source/arduino/serial.rst index abba049..1bcd28d 100644 --- a/source/arduino/serial.rst +++ b/source/arduino/serial.rst @@ -63,3 +63,6 @@ Examples - `Serial Call Response `_ - `Serial Call Response ASCII `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/setup.rst b/source/arduino/setup.rst index 05911ed..79c9527 100644 --- a/source/arduino/setup.rst +++ b/source/arduino/setup.rst @@ -29,3 +29,6 @@ Example // ... } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/shiftout.rst b/source/arduino/shiftout.rst index 2277cf1..3815dc5 100644 --- a/source/arduino/shiftout.rst +++ b/source/arduino/shiftout.rst @@ -131,3 +131,6 @@ Example } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/sin.rst b/source/arduino/sin.rst index 4eb2e1f..b117f5f 100644 --- a/source/arduino/sin.rst +++ b/source/arduino/sin.rst @@ -23,3 +23,6 @@ See Also - :ref:`tan ` - :ref:`float ` - :ref:`double ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/sizeof.rst b/source/arduino/sizeof.rst index 104c183..8513e9d 100644 --- a/source/arduino/sizeof.rst +++ b/source/arduino/sizeof.rst @@ -60,3 +60,6 @@ this:: for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { // do something with myInts[i] } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/sq.rst b/source/arduino/sq.rst index 2b6b1fe..c918d50 100644 --- a/source/arduino/sq.rst +++ b/source/arduino/sq.rst @@ -37,3 +37,6 @@ Arduino Compatibility --------------------- Maple's implementation of ``sq()`` is compatible with Arduino. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/sqrt.rst b/source/arduino/sqrt.rst index 4263345..f93908e 100644 --- a/source/arduino/sqrt.rst +++ b/source/arduino/sqrt.rst @@ -20,3 +20,6 @@ See Also - :ref:`pow ` - :ref:`sq ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/static.rst b/source/arduino/static.rst index b292891..76bf949 100644 --- a/source/arduino/static.rst +++ b/source/arduino/static.rst @@ -52,3 +52,6 @@ then incremented, so it starts out at one. Subsequent calls to ``readSensors()`` won't reset ``numSensorReadings`` to zero, because it was declared ``static``. Thus, ``numSensorReadings`` is a count of the number of times that ``readSensors()`` has been called. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/string.rst b/source/arduino/string.rst index 8db400a..528e7de 100644 --- a/source/arduino/string.rst +++ b/source/arduino/string.rst @@ -126,3 +126,6 @@ See Also - :ref:`array ` - :ref:`__attribute__ ` - :ref:`Variables ` + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/stringclass.rst b/source/arduino/stringclass.rst index 0c9c61d..ce508e7 100644 --- a/source/arduino/stringclass.rst +++ b/source/arduino/stringclass.rst @@ -4,3 +4,6 @@ String Class ============ Stub. + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/stringobject.rst b/source/arduino/stringobject.rst index ffee295..1844266 100644 --- a/source/arduino/stringobject.rst +++ b/source/arduino/stringobject.rst @@ -86,3 +86,6 @@ See Also - `Variable Declaration `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/switchcase.rst b/source/arduino/switchcase.rst index 1634de1..2ca2793 100644 --- a/source/arduino/switchcase.rst +++ b/source/arduino/switchcase.rst @@ -76,3 +76,6 @@ See also: `if...else `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/tan.rst b/source/arduino/tan.rst index f31b357..f17ffcc 100644 --- a/source/arduino/tan.rst +++ b/source/arduino/tan.rst @@ -33,3 +33,6 @@ See also - `cos `_\ () - `float `_ - `double `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/tone.rst b/source/arduino/tone.rst index c7b1e44..8252804 100644 --- a/source/arduino/tone.rst +++ b/source/arduino/tone.rst @@ -76,3 +76,6 @@ See also - `Tutorial: PWM `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/unsignedchar.rst b/source/arduino/unsignedchar.rst index f846105..1fd7a1c 100644 --- a/source/arduino/unsignedchar.rst +++ b/source/arduino/unsignedchar.rst @@ -39,3 +39,6 @@ See also - `Serial.println `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/unsignedint.rst b/source/arduino/unsignedint.rst index 10835fe..11412b1 100644 --- a/source/arduino/unsignedint.rst +++ b/source/arduino/unsignedint.rst @@ -75,3 +75,6 @@ See Also - `Variable Declaration `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/unsignedlong.rst b/source/arduino/unsignedlong.rst index 1bdb434..c493c40 100644 --- a/source/arduino/unsignedlong.rst +++ b/source/arduino/unsignedlong.rst @@ -61,3 +61,6 @@ See Also - `Variable Declaration `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/variables.rst b/source/arduino/variables.rst index d79f28b..bedb86b 100644 --- a/source/arduino/variables.rst +++ b/source/arduino/variables.rst @@ -186,3 +186,6 @@ Variable Scope - `Variable Scope `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/void.rst b/source/arduino/void.rst index 00166b6..1d3bf8e 100644 --- a/source/arduino/void.rst +++ b/source/arduino/void.rst @@ -35,3 +35,6 @@ See also `function declaration `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/volatile.rst b/source/arduino/volatile.rst index 4212ac5..9516db0 100644 --- a/source/arduino/volatile.rst +++ b/source/arduino/volatile.rst @@ -68,3 +68,6 @@ See also - `AttachInterrupt `_ + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/while.rst b/source/arduino/while.rst index 9ec9f78..e8167bd 100644 --- a/source/arduino/while.rst +++ b/source/arduino/while.rst @@ -44,3 +44,6 @@ Example var++; } + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/word.rst b/source/arduino/word.rst index 39b3a0d..32506b8 100644 --- a/source/arduino/word.rst +++ b/source/arduino/word.rst @@ -27,3 +27,6 @@ See also - `byte `_ - `word `_\ () + + +.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/wordcast.rst b/source/arduino/wordcast.rst index 5ef821c..1e854ba 100644 --- a/source/arduino/wordcast.rst +++ b/source/arduino/wordcast.rst @@ -49,3 +49,6 @@ See also - `word `_ + + +.. include:: cc-attribution.txt \ No newline at end of file -- cgit v1.2.3 From 4b60b1cad5fe16895179d0bd8a5dc1e6e4c7564c Mon Sep 17 00:00:00 2001 From: AJM Date: Wed, 17 Nov 2010 16:14:50 -0500 Subject: modified the bootloader docs, added description of the rev6 bootloader gameplan and description of the first rev of the serial protocol --- source/bootloader.rst | 334 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 329 insertions(+), 5 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index 032b20b..2cacb5a 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -1,8 +1,8 @@ .. highlight:: sh -================== - Maple Bootloader -================== +===================== + Maple Bootloader(s) +===================== .. TODO: [Stub] add a section on flashing your own bootloader @@ -92,8 +92,8 @@ platforms to make everything work this way. .. _bootloader-rev3: -Maple Rev3 ----------- +Maple Rev3/Rev5 +--------------- Maple Rev 3 takes a completely different tack, more along the lines of Arduino. In Rev 3, the device resets into bootloader mode, which @@ -134,3 +134,327 @@ alternate setting 0 or 1, respectively) and resets the board again. This time, however, no DFU transaction is initiated, and the bootloader gives way to user code, closing down the DFU pipe and bringing up the USB serial. + +.. _bootloader-rev6: + +Maple Rev6 - The Serial Bootloader (Tentative) +---------------------------------------------- + +The bootloader in Rev3/Rev5 works quite well in linux, it works OK in +Mac, but in windows we had a few major issues. First off, unlike the +other operating systems, Windows needed to be manually pointed to both +the driver to use for programming (DFU, via libusb) and the driver to +use for serial communication (usbser.sys, built in to windows). Maple +operates in only one of these modes at a time, installation has been +quite tricky, involving getting Maple into the right mode and then +installing the driver/inf file during the windows prompt. Furthermore, +because libusb is not bundled with Windows, and its driver is not +signed, users of Windows 7 have been forced to laboriously disable +driver signing checks. Finally, the constant switching of the device +between Serial and DFU modes (during programming) really confuses +windows, often reprompting users to install drivers that are alrady +installed or generally not working well. We have therefore decided to +simplify things greatly, by simply abandoning DFU. In this new +bootloader scheme, Maple is, simply, a serial device. Windows comes +bundled with usbser.sys, so no driver signing is required. The +installation process will be greatly simplified, there will be no more +siwtching back and forth between "modes" and we get the chance to +build in a lot of new functionality that were outside the DFU spec. + +The first incarnation of this serial-only bootloader leaves libmaple +and user code untouched. However, during programming, instead of +calling dfu-util to upload code we will now call a newly written +utility script similar to avr-dude used by arduino. The high level +operation of the bootloader will remain the same - come on at startup, +wait for an upload operation or timeout and jump to user code. The +second version of this bootloader will eliminate this dependence on +resetting and timing out by having the bootloader run in the +background all the time, and owning the serial port. In this scheme, +sending data over the COM port while DTR is pulled low results in that +packet being captured by the bootloader and interpreted as a +bootloader command. When the user uploads a new program, the +bootloader will overwrite the old one, reset the various peripheral +registers, and jump to user code. All of this will occur without every +resetting the chip and thus causing Maple to connect and disconnect +from your computer (which seems to cause many problems). The finaly +version of this new bootloader scheme will actually involve a separate +microcontroller, whose responsibilities are to drive the USB port, +program the main processor, and offer some amount of debugging +capability. This will allow user sketches to run on the "bare metal" +of the main processor, without any bootloader hiding underneath your +programs. This approach is similar to the approaches taken by mBed and +the new Arduino UNO. + +Regardless of which generation of the new serial bootloader you are +working with, the command interface is the same. The low level +communication protocol is inspired by STK-500, the protocol used to +program Arduino's and many other AVR based development boards. The +protocol is a packetized query-response scheme. The host PC initiates +every transaction, and for every query sent to the bootloader, a +single response will be returned (or the system times out). Data is +transmitted over 115.2kbps, 8 data bits, 1 stop bit, no parity +bit. Every query or response follows the same packet format that looks +like this: + +.. _bootloader-packet-structure: + +The Packet +^^^^^^^^^^ +.. csv-table:: + :header: Field, length (Bytes), value, description + + START, 2, 0x7EAF, A magic constant that indicates this is a + bootloader packet + + SEQUENCE_NUM, 1, 0-255, Every response must have the same sequence + number as its query + + MESSAGE_SIZE, 2, 0-65535, Size of the message body\, currently + messages must be <= 512 Bytes + + MESSAGE_BODY, 0-65535, DATA, Self explanatory + + CHECKSUM, 4, VAL, The XOR of all bytes in the packet except the + checksum byte + +.. _bootloader-commands: + +Commands +^^^^^^^^ + +The packet structure is really just overhead. The actual queries and +responses are transacted inside of the message body. Again following +in the footsteps of STK-500, each query or response begins with the +single byte CMD field. For each query, the resultant response must +begin with the same CMD byte. For each type of CMD, the structure of +queries and responses are well formed and of fixed size. Like STK-500, +fields longer than 1 byte are transmitted MSB first (big +endian). However, READ and WRITE commands operate bytewise (not word +wise), it is up to the host PC to ensure that alignment and ordering +issues are taken care of when appropriate (Maple uses a little endian +processor, LSB first). + +.. list-table:: GET_INFO Query + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - GET_INFO + - 1 + - +\ + +.. list-table:: GET_INFO Response + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - GET_INFO + - 1 + - + + * - Available Ram + - 4 + - + + * - Available Flash + - 4 + - + + * - Flash Page Size + - 2 + - + + * - Starting Address (FLASH) + - 4 + - Usually 0x08005000 + + * - Starting Address (RAM) + - 4 + - Usually 0x200000C0 + + * - Bootloader Version + - 4 + - Current version 0x00060000 (MAJ,MIN) + +\ +\ + +.. list-table:: ERASE_PAGE Query + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - ERASE_PAGE + - 1 + - \ + + * - ADDRESS + - 4 + - Will erase whichever page contains ADDRESS + +\ + +.. list-table:: ERASE_PAGE Response + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - ERASE_PAGE + - 1 + - + + * - SUCCESS? + - 1 + - Either 0 or 1, (FAILED and OK) + +\ +\ + +.. list-table:: ERASE_PAGE Response + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - WRITE_BYTES + - 1 + - + + * - Starting Address + - 4 + - Can only write to RAM or addresses on cleared FLASH pages! + + * - DATA + - Message Size - 5 + - + +\ + +.. list-table:: WRITE_BYTES Response + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - WRITE_BYTES + - 1 + - + + * - SUCCESS? + - 1 + - Either 0 or 1 (FAILED, OK). Will fail if writes were made to uncleared pages, does not clean up failed writes (memory in unknown state) + +\ +\ + +.. list-table:: READ_BYTES Query + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - READ_BYTES + - 1 + - + + * - ADDRESS + - 4 + - Start of block to read, must be a multiple of 4 (4 byte alignment) + + * - LENGTH + - 2 + - Number of Bytes to Read (currently 512 byte max, must be a multiple of 4) + +\ + +.. list-table:: READ_BYTES Response + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - READ_BYTES + - 1 + - + + * - DATA + - Message Size - 1 + - Returns data, if this section is of length 0, this should be interpreted as a read failure + +\ +\ + +.. list-table:: JUMP_TO_USER Query + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - JUMP_TO_USER + - 1 + - + +\ + +.. list-table:: JUMP_TO_USER Response + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - JUMP_TO_USER + - 1 + - + + * - SUCCESS + - 1 + - Either 0 or 1 (FAILED,OK). Will end this bootloader session and jump to user + +\ +\ + +.. list-table:: SOFT_RESET Query + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - SOFT_RESET + - 1 + - Will engage a full software reset + +\ + +.. list-table:: SOFT_RESET Response + :header-rows: 1 + + * - Field + - Bytes + - Comments + + * - SOFT_RESET + - 1 + - Will engage a full software + + * - SUCCESS + - 1 + - Either 0 or 1 (FAILED,OK). Will end this bootloader session and reset the processor + +\ +\ -- cgit v1.2.3 From c770a7f14404822c1164a2399079411a37808cfd Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 21 Nov 2010 01:40:37 -0500 Subject: updated serial bootloader spec; other improvements --- source/arduino/arithmetic.rst | 4 +- source/arduino/bitwisemath.rst | 4 +- source/arduino/boolean.rst | 8 +- source/arduino/braces.rst | 8 +- source/arduino/break.rst | 8 +- source/arduino/bytecast.rst | 14 +- source/arduino/comments.rst | 10 +- source/arduino/const.rst | 10 +- source/arduino/constants.rst | 24 +- source/arduino/continue.rst | 18 +- source/arduino/delaymicroseconds.rst | 12 +- source/arduino/floatcast.rst | 12 +- source/arduino/goto.rst | 4 +- source/arduino/highbyte.rst | 8 +- source/arduino/millis.rst | 4 +- source/arduino/setup.rst | 8 +- source/arduino/sizeof.rst | 45 ++-- source/arduino/static.rst | 6 +- source/arduino/switchcase.rst | 96 ++++--- source/arduino/unsignedchar.rst | 2 +- source/arduino/variables.rst | 16 +- source/arduino/void.rst | 8 +- source/arduino/volatile.rst | 10 +- source/bootloader.rst | 400 +++++++++++++++++------------ source/external-interrupts.rst | 2 +- source/foo.rst | 3 +- source/index.rst | 20 +- source/language.rst | 469 +++++++++++++++-------------------- source/unix-toolchain.rst | 42 ++-- source/wirish.rst | 1 + source/wirish/pwmwrite.rst | 13 +- 31 files changed, 675 insertions(+), 614 deletions(-) diff --git a/source/arduino/arithmetic.rst b/source/arduino/arithmetic.rst index 412a0be..69cf166 100644 --- a/source/arduino/arithmetic.rst +++ b/source/arduino/arithmetic.rst @@ -14,7 +14,7 @@ Description These operators return the sum, difference, product, or quotient (respectively) of the two operands. The operation is conducted using the data type of the operands, so, for example, ``9 / 4`` gives ``2`` -since 9 and 4 are ints. +since 9 and 4 are :ref:`int variables `. This also means that the operation can overflow if the result is larger than that which can be stored in the data type (e.g. adding 1 @@ -126,4 +126,4 @@ See Also - :ref:`sizeof `\ () -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/bitwisemath.rst b/source/arduino/bitwisemath.rst index 196cc2c..40c3d7a 100644 --- a/source/arduino/bitwisemath.rst +++ b/source/arduino/bitwisemath.rst @@ -120,7 +120,7 @@ program to blink digital pin 13 (the LED pin on Maple):: void setup(){ pinMode(led_pin, OUTPUT); } - + void loop(){ toggle = toggle ^ 1; digitalWrite(led_pin, toggle); @@ -183,4 +183,4 @@ See Also ``|=``, ``^=``). -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/boolean.rst b/source/arduino/boolean.rst index 8106520..1d834d3 100644 --- a/source/arduino/boolean.rst +++ b/source/arduino/boolean.rst @@ -6,7 +6,8 @@ Boolean Operators ================= These can be used inside the condition of an :ref:`if ` -statement. +statement. Evaluate to :ref:`true ` or +:ref:`false `. .. contents:: Contents :local: @@ -45,6 +46,7 @@ True if either operand is true. For example:: is true if either ``x`` or ``y`` is greater than 0. +.. _arduino-boolean-not: ! (logical not) --------------- @@ -55,7 +57,7 @@ True if the operand is false. For example:: // ... } -is true if ``x`` is false (i.e. if ``x`` equals zero). +is true if ``x`` is false (i.e. if ``x`` is zero). Some Advice ----------- @@ -86,4 +88,4 @@ See Also - :ref:`if statement ` -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/braces.rst b/source/arduino/braces.rst index 38018fe..04518b3 100644 --- a/source/arduino/braces.rst +++ b/source/arduino/braces.rst @@ -59,10 +59,10 @@ pages for more information):: while (boolean expression) { // code inside the loop goes here } - + for (initialisation; termination condition; incrementing expr) { // code inside the loop goes here - } + } do { // code inside the loop goes here @@ -80,7 +80,7 @@ reference page for more information):: } else if (boolean expression) { // code inside the "else if" - } + } else { // code inside the "else" } @@ -94,4 +94,4 @@ reference page for more information):: out. -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/break.rst b/source/arduino/break.rst index 8c0478a..3e1e9ee 100644 --- a/source/arduino/break.rst +++ b/source/arduino/break.rst @@ -19,17 +19,17 @@ Example for (x = 0; x < 255; x ++) { digitalWrite(PWMpin, x); - sens = analogRead(sensorPin); + sens = analogRead(sensorPin); if (sens > threshold){ // bail out on sensor detect x = 0; // this line of code means that we'll immediately exit // from the "for" loop: break; - } + } delay(50); } - -.. include:: cc-attribution.txt \ No newline at end of file + +.. include:: cc-attribution.txt diff --git a/source/arduino/bytecast.rst b/source/arduino/bytecast.rst index 38aec36..348c9fb 100644 --- a/source/arduino/bytecast.rst +++ b/source/arduino/bytecast.rst @@ -10,17 +10,17 @@ Description Converts a value to the :ref:`byte ` data type. -.. warning:: +.. note:: Casting to the byte type is provided for compatibility with - Arduino. However, ``byte`` is a non-standard type. The standard - C++ type for storing an 8-bit unsigned integer is ``unsigned - char``, and we recommend using that instead. + Arduino. However, the recommended Maple type for storing an 8-bit + unsigned integer is ``uint8``. (C and C++ programmers: ``stdint.h`` + is also available). - In order to cast a variable ``x`` to an ``unsigned char``, the + In order to cast a variable ``x`` to a ``uint8``, the following syntax can be used:: - (unsigned char)(x); + uint8(x); Syntax ------ @@ -50,4 +50,4 @@ See Also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/comments.rst b/source/arduino/comments.rst index e46fc48..b50aa0f 100644 --- a/source/arduino/comments.rst +++ b/source/arduino/comments.rst @@ -14,19 +14,23 @@ One use for comments is to help you understand (or remember) how your program works, or to inform others how your program works. There are two different ways of making comments. +.. _arduino-comments-singleline: + **Single line comment**: Anything following two slashes, ``//``, until the end of the line, is a comment:: x = 5; // the rest of this line is a comment +.. _arduino-comments-multiline: + **Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` is a comment:: - + /* <-- a slash-star begins a multi-line comment all of this in the multi-line comment - you can use it to comment out whole blocks of code - + if (gwb == 0){ // single line comment is OK inside a multi-line comment x = 3; } @@ -60,4 +64,4 @@ is cryptic or unhelpful. -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/const.rst b/source/arduino/const.rst index eb2b07b..b008144 100644 --- a/source/arduino/const.rst +++ b/source/arduino/const.rst @@ -26,13 +26,13 @@ Example // this defines a variable called "pi", which cannot be changed: const float pi = 3.14; float x; - + // .... - + x = pi * 2; // it's fine to find the value of a const variable - + pi = 7; // illegal - you can't write to (modify) a constant - + **#define** or **const** ------------------------ @@ -49,4 +49,4 @@ See Also - :ref:`volatile ` -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/constants.rst b/source/arduino/constants.rst index 3a819b3..e841c9b 100644 --- a/source/arduino/constants.rst +++ b/source/arduino/constants.rst @@ -103,7 +103,7 @@ Digital pins can be used either as **INPUT** or **OUTPUT**. Changing a pin from INPUT TO OUTPUT with pinMode() drastically changes the electrical behavior of the pin. - +.. _arduino-constants-input: Pins Configured as Inputs ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -115,7 +115,7 @@ circuit that they are sampling, say equivalent to a series resistor of 100 Megohms in front of the pin. This makes them useful for reading a sensor, but not powering an LED. - +.. _arduino-constants-output: Pins Configured as Outputs ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -132,7 +132,7 @@ of current provided by an Atmega pin is also not enough to power most relays or motors, and some interface circuitry will be required. -.. _arduino-fpconstants: +.. _arduino-constants-fp: Floating-Point Constants ------------------------ @@ -141,28 +141,26 @@ Similar to integer constants, floating point constants are used to make code more readable. Floating point constants are swapped at compile time for the value to which the expression evaluates. +.. TODO explain that floating point literals are doubles +.. _arduino-constants-fp-f: -Examples: - +.. TODO f modifiers +Examples: ``n = .005;`` - - Floating point constants can also be expressed in a variety of scientific notation. 'E' and 'e' are both accepted as valid exponent indicators. - - :: - + floating-point evaluates to: also evaluates to: - constant - + constant + 10.0 10 2.34E5 2.34 * 10^5 234000 67e-12 67.0 * 10^-12 .000000000067 @@ -301,4 +299,4 @@ See also - `unsigned long `_ -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/continue.rst b/source/arduino/continue.rst index 31af3a5..bda1c95 100644 --- a/source/arduino/continue.rst +++ b/source/arduino/continue.rst @@ -2,8 +2,9 @@ .. _arduino-continue: -continue -======== +========== + continue +========== The ``continue`` keyword skips the rest of the current iteration of a :ref:`while `\ , :ref:`for `\ , or @@ -13,22 +14,21 @@ iterations. Example -------- +======= :: - - for (x = 0; x < 255; x ++) - { - if (x > 40 && x < 120){ // create jump in values + + for (x = 0; x < 255; x ++) { + if (x > 40 && x < 120) { // create jump in values continue; // skips the next two lines and goes to the // beginning of the loop, with the next value of x } - + digitalWrite(PWMpin, x); delay(50); } -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/delaymicroseconds.rst b/source/arduino/delaymicroseconds.rst index 10f3a1b..d1016f1 100644 --- a/source/arduino/delaymicroseconds.rst +++ b/source/arduino/delaymicroseconds.rst @@ -21,18 +21,18 @@ Example The following example configures pin number 8 to work as an output pin, and sends a train of pulses with a period of roughly 100 microseconds:: - + int outPin = 8; - + void setup() { pinMode(outPin, OUTPUT); // sets the digital pin as output } - + void loop() { digitalWrite(outPin, HIGH); // sets the pin on - delayMicroseconds(50); // pauses for 50 microseconds + delayMicroseconds(50); // pauses for 50 microseconds digitalWrite(outPin, LOW); // sets the pin off - delayMicroseconds(50); // pauses for 50 microseconds + delayMicroseconds(50); // pauses for 50 microseconds } @@ -62,4 +62,4 @@ See Also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/floatcast.rst b/source/arduino/floatcast.rst index 6a2e799..a8d1113 100644 --- a/source/arduino/floatcast.rst +++ b/source/arduino/floatcast.rst @@ -9,13 +9,14 @@ Description ----------- Converts a value to the :ref:`float ` data type. Here -is an example:: +is an example (see the :ref:`constants reference +` for an explanation of the "2.0f"):: int x = 2; - float f = float(x); // f now holds "2.0", a floating point value + float f = float(x); // f now holds 2.0f, a float value The value ``x`` can be of any type. However, if ``x`` is not a number -(like an ``int`` or ``long``), you will get strange results. +(like an ``int``), you will get strange results. See the :ref:`float ` reference for details about the precision and limitations of ``float`` values on the Maple. @@ -24,6 +25,7 @@ See Also -------- - :ref:`float ` +- :ref:`double ` +- :ref:`double() ` - -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/goto.rst b/source/arduino/goto.rst index e683c98..2901913 100644 --- a/source/arduino/goto.rst +++ b/source/arduino/goto.rst @@ -95,7 +95,7 @@ Here's an example:: if (analogRead(0) > 250) { goto bailout; } - // more statements ... + // more statements ... } // innermost loop ends here } @@ -127,4 +127,4 @@ See Also - Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/highbyte.rst b/source/arduino/highbyte.rst index 74717c1..5b1c24e 100644 --- a/source/arduino/highbyte.rst +++ b/source/arduino/highbyte.rst @@ -6,9 +6,9 @@ highByte(x) .. warning:: This macro is provided for compatibility with Arduino only. It returns the second-least significant byte in an integral value. It makes sense to call this the "high" byte on a 16-bit - microcontroller like the Atmel chips on Arduinos, but it makes no - sense at all on a 32-bit microcontroller like the STM32s in the - Maple line. + ``int`` microcontroller like the Atmel chips on Arduinos, but it + makes no sense at all on a 32-bit microcontroller like the STM32s + in the Maple line. In short: we provide this so that existing Arduino code works as expected, but **strongly discourage its use** in new programs. @@ -50,4 +50,4 @@ See Also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/millis.rst b/source/arduino/millis.rst index 12f5d8d..f52d396 100644 --- a/source/arduino/millis.rst +++ b/source/arduino/millis.rst @@ -32,7 +32,7 @@ Example :: unsigned long time; - + void setup(){ Serial.begin(9600); } @@ -67,4 +67,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/setup.rst b/source/arduino/setup.rst index 79c9527..9cc96d4 100644 --- a/source/arduino/setup.rst +++ b/source/arduino/setup.rst @@ -15,15 +15,15 @@ Example :: - + int buttonPin = 3; - + void setup() { Serial.begin(9600); pinMode(buttonPin, INPUT); } - + void loop() { // ... @@ -31,4 +31,4 @@ Example -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/sizeof.rst b/source/arduino/sizeof.rst index 8513e9d..7c31809 100644 --- a/source/arduino/sizeof.rst +++ b/source/arduino/sizeof.rst @@ -5,28 +5,20 @@ sizeof() ======== -Syntax ------- +The ``sizeof`` operator on the Maple returns the number of bytes +needed to store a value of a given type\ [#fcharsize]_. This can be +an ordinary numeric type, like ``int``. It can be something more +complicated, like a ``struct`` or ``union``. If the argument to +``sizeof`` is an array, it returns the total number of bytes occupied +by the array. -:: +The general syntax looks like this:: sizeof(type) sizeof(var) - - -Description ------------ - -The ``sizeof`` operator returns the number of bytes needed to store a -value of a given type. This can be an ordinary numeric type, like -``int``. It can be something more complicated, like a ``struct`` or -``union``. If the argument to ``sizeof`` is an array, it returns the -total number of bytes occupied by the array. - - -Examplec --------- +Example +------- The ``sizeof`` operator is useful for dealing with arrays (such as strings) where it is convenient to be able to change the size of the @@ -51,15 +43,22 @@ changing the text phrase:: } -Note that ``sizeof`` returns the total number of bytes; this is equal -to the number of ``char``\ s only because the C++ standard guarantees -that ``sizeof(char) == 1``. So for larger variable types such as -``int``, the :ref:`for loop ` would look something like -this:: +Note that ``sizeof`` returns the total number of bytes. So for larger +variable types such as ``int``, the :ref:`for loop ` +would look something like this:: for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { // do something with myInts[i] } +.. rubric:: Footnotes + +.. [#fcharsize] Technically (and pedantically) speaking, ``sizeof`` + returns a multiple of the number of bits a ``char`` occupies in + memory. However, on the Maple (this goes for most C++ + implementations), a ``char`` occupies 8 bits = 1 byte. All the C++ + standard guarantees, however, is that a ``char`` occupies at + *least* 8 bits. + +.. include:: cc-attribution.txt -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/static.rst b/source/arduino/static.rst index 76bf949..01f3dbf 100644 --- a/source/arduino/static.rst +++ b/source/arduino/static.rst @@ -15,8 +15,8 @@ Variables declared as ``static`` will only be created and initialized the first time a function is called. .. note:: This is only one use of the ``static`` keyword in C++. It - has some other important uses that are outside the scope of this - documentation; consult a reliable C++ reference for details. + has some other important uses that are not documented here; consult + a reliable C++ reference for details. Example ------- @@ -54,4 +54,4 @@ it was declared ``static``. Thus, ``numSensorReadings`` is a count of the number of times that ``readSensors()`` has been called. -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/switchcase.rst b/source/arduino/switchcase.rst index 2ca2793..9f66d0a 100644 --- a/source/arduino/switchcase.rst +++ b/source/arduino/switchcase.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _arduino-switchcase: switch / case statements @@ -7,10 +9,7 @@ Like :ref:`if/else ` blocks, A ``switch`` statement controls program flow by allowing you to specify different code that should be executed under various cases. -Syntax ------- - -:: +The general syntax looks like this:: switch (var) { case val1: @@ -28,6 +27,7 @@ Where ``var`` is a variable whose value to investigate, and the ``val1``, ``val2`` after each ``case`` are constant values that ``var`` might be. + Description ----------- @@ -36,46 +36,82 @@ specified in ``case`` statements. When a ``case`` statement is found whose value matches that of the variable, the code in that case statement is run. -The ``break`` keyword exits the switch statement, and is typically -used at the end of each ``case``. Without a ``break``, the ``switch`` -statement will continue executing the following ``case`` expressions -("falling-through") until a ``break`` (or the end of the switch -statement) is reached. +Here's a more concrete example:: -Writing ``default:`` instead of a ``case`` statement allows you to -specify what to do if none of the ``case`` statements matches. Having -a ``default:`` is optional (you can leave it out), but if you have -one, it must appear after all of the ``case`` statements, as shown -above. + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + afterTheSwitch(); -``switch`` statements are often used with an ``enum`` value as the -variable to compare. In this case, you can write down all of the -values the ``enum`` takes as ``case`` statements, and be sure you've -covered all the possibilities. +In the above example, if ``var == 1``, then the code beginning on the +line after ``case 1:`` gets executed. That is, if ``var`` is one, +``doThing1()`` gets called first, and then the ``break`` statement +gets executed. + +The ``break`` keyword exits the ``switch`` statement, and is typically +used at the end of each ``case``. Since there is a ``break`` at the +end of ``case 1:``, the ``switch`` statement gets exited, and the next +line to be run is the one which calls ``afterTheSwitch()``. + +Without a ``break``, the ``switch`` statement will continue executing +the following ``case`` expressions ("falling-through") until a +``break`` (or the end of the switch statement) is reached. Let's +pretend the ``switch`` looked like this instead:: -Example -------- + switch (var) { + case 1: + doThing1(); + // no break statement anymore + case 2: + doThing2(); + break; + } + afterTheSwitch(); + +Now, if ``var`` is one, ``doThing1()`` gets executed like before. +However, without a ``break``, the code would continue to be executed +line-by-line, so ``doThing2()`` would be called next. At this point, +a ``break`` has been reached, so the program continues by calling +``afterTheSwitch()``. This is usually not what you want, which is why +each ``case`` usually has a ``break`` at the end. -:: +Writing "``default:``" instead of a ``case`` statement allows you to +specify what to do if none of the ``case`` statements matches. Having +a ``default`` is optional (you can leave it out), but if you have one, +it must appear after all of the ``case`` statements. Let's add a +``default`` to the ``switch`` we've been discussing:: switch (var) { case 1: - //do something when var equals 1 + doThing1(); break; case 2: - //do something when var equals 2 + doThing2(); break; default: - // if nothing else matches, do the default - // default is optional + doSomethingElse(); } + afterTheSwitch(); -See also: ---------- - -`if...else `_ +If ``var`` is one, then ``doThing1()`` gets called. If ``var`` is +two, ``doThing2()`` gets called. If ``var`` is anything else, +``doSomethingElse()`` gets called. As stated above, a ``default`` is +optional. If you're missing one and none of the ``case`` statements +match, the ``switch`` does nothing at all, as if it wasn't there. +``switch`` statements are often used with an ``enum`` value as the +variable to compare. In this case, you can write down all of the +values the ``enum`` takes as ``case`` statements, and be sure you've +covered all the possibilities. +See also: +--------- +- :ref:`if...else ` -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/unsignedchar.rst b/source/arduino/unsignedchar.rst index 1fd7a1c..5c26d17 100644 --- a/source/arduino/unsignedchar.rst +++ b/source/arduino/unsignedchar.rst @@ -41,4 +41,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/variables.rst b/source/arduino/variables.rst index bedb86b..0720041 100644 --- a/source/arduino/variables.rst +++ b/source/arduino/variables.rst @@ -9,7 +9,7 @@ A variable is a way of naming and storing a value for later use by the program, such as data from a sensor or an intermediate value used in a calculation. - +.. _arduino-variables-declaring: Declaring Variables ^^^^^^^^^^^^^^^^^^^ @@ -34,7 +34,7 @@ store in choosing variable types. Variables will `roll over <#VariableRollover>`_ when the value stored exceeds the space assigned to store it. See below for an example. - +.. _arduino-variables-scope: Variable Scope ^^^^^^^^^^^^^^ @@ -45,7 +45,7 @@ influences how various functions in a program will *see* the variable. This is called variable `scope `_. - +.. _arduino-variables-initializing: Initializing Variables ^^^^^^^^^^^^^^^^^^^^^^ @@ -63,7 +63,7 @@ Example: int calibrationVal = 17; // declare calibrationVal and set initial value - +.. _arduino-variables-rollover: Variable Rollover ^^^^^^^^^^^^^^^^^ @@ -104,7 +104,7 @@ variable on the left side. :: inputVariable1 = 7; // sets the variable named inputVariable1 to 7 - inputVariable2 = analogRead(2); // sets the variable named inputVariable2 to the + inputVariable2 = analogRead(2); // sets the variable named inputVariable2 to the // (digitized) input voltage read from analog pin #2 @@ -117,7 +117,7 @@ Examples int lightSensVal; char currentLetter; unsigned long speedOfLight = 186000UL; - char errorMessage = {"choose another option"}; // see string + char errorMessage = {"choose another option"}; // see string @@ -135,7 +135,7 @@ inputVariable2 which is a minimum of 100: { inputVariable2 = 100; } - + delay(inputVariable2); @@ -188,4 +188,4 @@ Variable Scope -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/void.rst b/source/arduino/void.rst index 1d3bf8e..82f9606 100644 --- a/source/arduino/void.rst +++ b/source/arduino/void.rst @@ -16,17 +16,17 @@ Example: // actions are performed in the functions "setup" and "loop" // but no information is reported to the larger program - + void setup() { // ... } - + void loop() { // ... } - + @@ -37,4 +37,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/arduino/volatile.rst b/source/arduino/volatile.rst index 9516db0..fc02081 100644 --- a/source/arduino/volatile.rst +++ b/source/arduino/volatile.rst @@ -39,21 +39,21 @@ Example :: // toggles LED when interrupt pin changes state - + int pin = 13; volatile int state = LOW; - + void setup() { pinMode(pin, OUTPUT); attachInterrupt(0, blink, CHANGE); } - + void loop() { digitalWrite(pin, state); } - + void blink() { state = !state; @@ -70,4 +70,4 @@ See also -.. include:: cc-attribution.txt \ No newline at end of file +.. include:: cc-attribution.txt diff --git a/source/bootloader.rst b/source/bootloader.rst index 2cacb5a..4be8e93 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -4,7 +4,7 @@ Maple Bootloader(s) ===================== -.. TODO: [Stub] add a section on flashing your own bootloader +.. TODO: add a section on flashing your own bootloader The firmware which allows the Maple to be reprogrammed via a USB connection. Every Maple board comes programmed with this by default, @@ -20,43 +20,46 @@ Flash memory and only runs when the chip is reset). .. contents:: Contents :local: -Bootloader Schemes Explained! ------------------------------ - -Maple Rev 3 and Rev 5 (the version currently shipping) represents a -drastic remake of the core library as well as the upload process. Some -of these changes are aesthetic, refactoring and reorganization. Some -are performance minded. The changes to the bootloader, however, were -implemented to solve some really gritty cross platform issues. Before -delving in to how the Rev 1 bootloader worked and how the Rev 3 -bootloader works now, lets look at the features common to both of them -and touch a bit on the Arduino setup. This is a fairly involved -explanation, with a lot of details that are likely only interesting to -a few. If you just want to get the rough idea, skim this article. If -you want to start hacking on the bootloader, get in touch with us to -get even more info on how this all works. Of course, you can always -`check out the code at github `_! +Bootloader Schemes Explained +---------------------------- + +Maple Rev 3 and Rev 5 (Rev 5 is the version currently shipping) +represents a drastic remake of the core library as well as the upload +process. Thes changes to the bootloader, were implemented to resolve +platform-specific issues on Windows. Before delving into how the Rev +1 bootloader worked and how the Rev 5 bootloader works now, we'll +discuss the features common to each and touch a bit on the Arduino +setup. + +This is a fairly involved explanation, with a lot of details that are +likely only interesting to a few. If you just want to get the rough +idea, skim this article. If you want to start hacking on the +bootloader, get in touch with us to get even more info on how this all +works. And finally, you can always `check out the code at github +`_! Arduino ------- -Arduino is based off of AVR series micro controllers, most of which +Arduino is based off of AVR series microcontrollers, most of which lack USB support. Thus, boards like the Duemilanove add USB capability -via an FTDI USB to Serial converter chip. This chip interfaces with -the AVR over…serial. When you plug an Arduino into a computer, only an -FTDI driver is needed. Since the FTDI chip is separate from the AVR, -you can reset the Arduino without closing this USB connection with the -FTDI chip. To program an Arduino, the host machine sends a command -over the USB pipe (reset DTR) which in turn resets the AVR. The AVR -will boot into a bootloader, which waits for a second for any upload -commands over serial. The host machine can either send those commands, -or do nothing. In which case the AVR will quickly jump to user code +via an FTDI USB-to-Serial converter chip. This chip interfaces with +the AVR over an RS-232 serial interface. When you plug an Arduino into +a computer, only an FTDI driver is needed. Since the FTDI chip is +separate from the AVR, you can reset the Arduino without closing this +USB connection with the FTDI chip. + +To program an Arduino, the host machine sends a command over the USB +pipe (reset DTR) which in turn resets the AVR. The AVR will boot into +a bootloader, which waits for a second for any upload commands over +serial. The host machine can either send those commands, or do +nothing. If it does nothing, the AVR will quickly jump to user code and off you go. The whole process is quick, the bootloader doesn’t live for very long, and will exit almost immediately if no upload commands are received. -Maple Rev 1: The Horror... ---------------------------- +Maple Rev 1 +----------- Maple is based off the STM32 (ARM cortex M3) series chips, which do have embedded USB support. Thus, Maple doesn’t need the extra FTDI @@ -140,101 +143,132 @@ bringing up the USB serial. Maple Rev6 - The Serial Bootloader (Tentative) ---------------------------------------------- -The bootloader in Rev3/Rev5 works quite well in linux, it works OK in -Mac, but in windows we had a few major issues. First off, unlike the -other operating systems, Windows needed to be manually pointed to both -the driver to use for programming (DFU, via libusb) and the driver to -use for serial communication (usbser.sys, built in to windows). Maple -operates in only one of these modes at a time, installation has been -quite tricky, involving getting Maple into the right mode and then -installing the driver/inf file during the windows prompt. Furthermore, -because libusb is not bundled with Windows, and its driver is not -signed, users of Windows 7 have been forced to laboriously disable -driver signing checks. Finally, the constant switching of the device -between Serial and DFU modes (during programming) really confuses -windows, often reprompting users to install drivers that are alrady -installed or generally not working well. We have therefore decided to -simplify things greatly, by simply abandoning DFU. In this new -bootloader scheme, Maple is, simply, a serial device. Windows comes -bundled with usbser.sys, so no driver signing is required. The -installation process will be greatly simplified, there will be no more -siwtching back and forth between "modes" and we get the chance to -build in a lot of new functionality that were outside the DFU spec. +The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac, +but was unsatisfactory on Windows. Unlike the other operating systems, +Windows needed to be manually pointed to both the driver to use for +programming (DFU, via `libusb `_) and the +driver to use for serial communication (usbser.sys, built in to +Windows). Since Maple operates in only one of these modes at a time, +driver installation was unnecessarily complicated. It was necessary to +bring Maple into the correct mode before installing each of the +drivers. Furthermore, because libusb is not bundled with Windows, and +its driver is not signed, Windows 7 users have been forced to +laboriously disable driver signing checks. Finally, Windows hates the +constant switching of the device between Serial and DFU modes (during +programming), and often prompts users to install drivers that are +already installed. We have therefore decided to abandon DFU. + +In our new bootloader scheme, Maple is simply a serial device. +Windows comes bundled with usbser.sys, so no driver signing is +required. The IDE installation process is greatly simplified, there +is no more switching back and forth between "modes", and we can build +in new functionality outside the DFU spec. The first incarnation of this serial-only bootloader leaves libmaple and user code untouched. However, during programming, instead of -calling dfu-util to upload code we will now call a newly written -utility script similar to avr-dude used by arduino. The high level +calling :command:`dfu-util` to upload code we will now call a newly +written utility script similar to `avr-dude +`_. The high level operation of the bootloader will remain the same - come on at startup, -wait for an upload operation or timeout and jump to user code. The -second version of this bootloader will eliminate this dependence on -resetting and timing out by having the bootloader run in the -background all the time, and owning the serial port. In this scheme, +wait for an upload operation or timeout, and jump to user code. + +The second version of this bootloader will eliminate this dependence +on resetting and timing out by having the bootloader run in the +background. It will additionally own the serial port. In this scheme, sending data over the COM port while DTR is pulled low results in that packet being captured by the bootloader and interpreted as a bootloader command. When the user uploads a new program, the bootloader will overwrite the old one, reset the various peripheral -registers, and jump to user code. All of this will occur without every +registers, and jump to user code. All of this will occur without resetting the chip and thus causing Maple to connect and disconnect -from your computer (which seems to cause many problems). The finaly -version of this new bootloader scheme will actually involve a separate +from your computer (which seems to cause many problems). + +The final version of this bootloader scheme will involve a separate microcontroller, whose responsibilities are to drive the USB port, program the main processor, and offer some amount of debugging -capability. This will allow user sketches to run on the "bare metal" -of the main processor, without any bootloader hiding underneath your -programs. This approach is similar to the approaches taken by mBed and -the new Arduino UNO. +capability. This will allow user sketches to run on the bare metal of +the main processor, without any bootloader hiding underneath. This +approach is similar to the approaches taken by mbed and the Arduino +Uno. Regardless of which generation of the new serial bootloader you are working with, the command interface is the same. The low level communication protocol is inspired by STK-500, the protocol used to -program Arduino's and many other AVR based development boards. The -protocol is a packetized query-response scheme. The host PC initiates -every transaction, and for every query sent to the bootloader, a -single response will be returned (or the system times out). Data is +program many AVR-based development boards. The protocol is a +packetized query-response scheme. The host PC initiates every +transaction, and for every query sent to the bootloader, a single +response will be returned (or the system times out). Data is transmitted over 115.2kbps, 8 data bits, 1 stop bit, no parity bit. Every query or response follows the same packet format that looks like this: .. _bootloader-packet-structure: -The Packet -^^^^^^^^^^ -.. csv-table:: - :header: Field, length (Bytes), value, description +Packet Structure +^^^^^^^^^^^^^^^^ + +A bootloader packet is composed of a sequence of fields, as follows. + +.. list-table:: + :header-rows: 1 + + * - Field + - Length (bytes) + - Value + - Description - START, 2, 0x7EAF, A magic constant that indicates this is a - bootloader packet + * - START + - 2 + - 0x7EAF + - Magic constant, indicates bootloader packet - SEQUENCE_NUM, 1, 0-255, Every response must have the same sequence - number as its query + * - SEQUENCE_NUM + - 1 + - 0--255 + - Queries and responses must have the same sequence number; rolls + over to 0 after 255. - MESSAGE_SIZE, 2, 0-65535, Size of the message body\, currently - messages must be <= 512 Bytes + * - MESSAGE_SIZE + - 2 + - 0--65,535 + - Size of message body, currently limited to a 512B maximum - MESSAGE_BODY, 0-65535, DATA, Self explanatory + * - MESSAGE_BODY + - Variable, determined by MESSAGE_SIZE field + - Command query or response + - See next section - CHECKSUM, 4, VAL, The XOR of all bytes in the packet except the - checksum byte + * - CHECKSUM + - 4 + - XOR of all other bytes in packet + - .. _bootloader-commands: Commands ^^^^^^^^ -The packet structure is really just overhead. The actual queries and -responses are transacted inside of the message body. Again following -in the footsteps of STK-500, each query or response begins with the -single byte CMD field. For each query, the resultant response must -begin with the same CMD byte. For each type of CMD, the structure of -queries and responses are well formed and of fixed size. Like STK-500, -fields longer than 1 byte are transmitted MSB first (big -endian). However, READ and WRITE commands operate bytewise (not word -wise), it is up to the host PC to ensure that alignment and ordering -issues are taken care of when appropriate (Maple uses a little endian -processor, LSB first). - -.. list-table:: GET_INFO Query +The packet structure overhead is for reliability. The actual queries +and responses are transacted inside of the message body. Following in +the footsteps of the STK-500 protocol, each query or response begins +with the single byte CMD field. For each query, the resultant response +must begin with the same CMD byte. For each type of CMD, the structure +of queries and responses are of fixed size. As in STK-500, fields +longer than 1 byte are transmitted MSB first (big endian). However, +READ and WRITE commands operate byte-wise (not word-wise); it is up to +the host PC to ensure that alignment and ordering issues are handled +appropriately. + +.. _bootloader-get-info: + +GET_INFO +"""""""" + +Used to query device characteristics. + +GET_INFO Query: + +.. list-table:: :header-rows: 1 * - Field @@ -243,11 +277,13 @@ processor, LSB first). * - GET_INFO - 1 - - -\ + - Value 0 + +GET_INFO Response: -.. list-table:: GET_INFO Response +.. list-table:: :header-rows: 1 + :widths: 4 2 10 * - Field - Bytes @@ -255,19 +291,25 @@ processor, LSB first). * - GET_INFO - 1 - - + - Value 0 + + * - Endianness + - 1 + - 0 indicates little-endian, 1 indicates big-endian. + (Currently returns 0; this field allows for future + expansion). * - Available Ram - 4 - - + - In bytes * - Available Flash - 4 - - + - In bytes * - Flash Page Size - 2 - - + - In bytes * - Starting Address (FLASH) - 4 @@ -281,11 +323,18 @@ processor, LSB first). - 4 - Current version 0x00060000 (MAJ,MIN) -\ -\ +.. _bootloader-erase-page: -.. list-table:: ERASE_PAGE Query +ERASE_PAGE +"""""""""" + +Used to erase flash pages. + +ERASE_PAGE query: + +.. list-table:: :header-rows: 1 + :widths: 4 2 10 * - Field - Bytes @@ -293,16 +342,17 @@ processor, LSB first). * - ERASE_PAGE - 1 - - \ + - Value 1 * - ADDRESS - 4 - Will erase whichever page contains ADDRESS -\ +ERASE_PAGE response: -.. list-table:: ERASE_PAGE Response +.. list-table:: :header-rows: 1 + :widths: 3 2 10 * - Field - Bytes @@ -310,17 +360,22 @@ processor, LSB first). * - ERASE_PAGE - 1 - - - - * - SUCCESS? + - Value 1 + + * - SUCCESS - 1 - - Either 0 or 1, (FAILED and OK) + - Either 0 (failure) or 1 (success) + +WRITE_BYTES +""""""""""" -\ -\ +Used to write to RAM or flash. -.. list-table:: ERASE_PAGE Response +WRITE_BYTES query: + +.. list-table:: :header-rows: 1 + :widths: 4 4 10 * - Field - Bytes @@ -328,20 +383,22 @@ processor, LSB first). * - WRITE_BYTES - 1 - - + - Value 2 * - Starting Address - 4 - - Can only write to RAM or addresses on cleared FLASH pages! + - Can address arbitrary RAM, or :ref:`cleared + ` flash pages. * - DATA - - Message Size - 5 - - + - MESSAGE_SIZE - 5 + - See :ref:`Packet Structure ` -\ +WRITE_BYTES response: -.. list-table:: WRITE_BYTES Response +.. list-table:: :header-rows: 1 + :widths: 2 2 10 * - Field - Bytes @@ -349,38 +406,47 @@ processor, LSB first). * - WRITE_BYTES - 1 - - - - * - SUCCESS? + - Value 2 + + * - SUCCESS - 1 - - Either 0 or 1 (FAILED, OK). Will fail if writes were made to uncleared pages, does not clean up failed writes (memory in unknown state) + - Either 0 (failure) or 1 (success). Will fail if writes were + made to uncleared pages. Does not clean up failed writes + (memory will be left in an undefined state). -\ -\ +READ_BYTES +"""""""""" -.. list-table:: READ_BYTES Query +Used to read from RAM or flash. + +READ_BYTES query: + +.. list-table:: :header-rows: 1 + :widths: 2 2 10 * - Field - Bytes - Comments - + * - READ_BYTES - 1 - - - + - Value 3 + * - ADDRESS - 4 - - Start of block to read, must be a multiple of 4 (4 byte alignment) + - Start of block to read. Must be a multiple of 4. * - LENGTH - 2 - - Number of Bytes to Read (currently 512 byte max, must be a multiple of 4) + - Maximum number of bytes to read (currently, this may be at most + 512). Must be a multiple of 4. -\ +READ_BYTES response: -.. list-table:: READ_BYTES Response +.. list-table:: :header-rows: 1 + :widths: 2 2 10 * - Field - Bytes @@ -388,17 +454,26 @@ processor, LSB first). * - READ_BYTES - 1 - - + - Value 3 * - DATA - - Message Size - 1 - - Returns data, if this section is of length 0, this should be interpreted as a read failure + - MESSAGE_SIZE - 1 + - Contains read bytes. The actual number of bytes read may be + less than the LENGTH field of the corresponding READ_BYTES + query. If this section is of length 0, this should be + interpreted as a read failure. See + :ref:`bootloader-packet-structure`. + +JUMP_TO_USER +"""""""""""" + +Causes the bootloader to jump to user code's starting address. -\ -\ +JUMP_TO_USER query: -.. list-table:: JUMP_TO_USER Query +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -406,12 +481,19 @@ processor, LSB first). * - JUMP_TO_USER - 1 - - + - Value 4 + + * - Location + - 1 + - 0 means jump to flash starting address, 1 means jump to RAM + starting address. See the :ref:`bootloader-get-info` command + for more information. -\ +JUMP_TO_USER response: -.. list-table:: JUMP_TO_USER Response +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -419,17 +501,26 @@ processor, LSB first). * - JUMP_TO_USER - 1 - - + - Value 4 * - SUCCESS - 1 - - Either 0 or 1 (FAILED,OK). Will end this bootloader session and jump to user + - Either 0 (failure) or 1 (success). If successful, after the + response is sent, the bootloader ends this session and jumps to + the user code in flash or RAM as specified in the query's + Location field. + + +SOFT_RESET +"""""""""" -\ -\ - -.. list-table:: SOFT_RESET Query +Engages a full software reset. + +SOFT_RESET query: + +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -437,12 +528,13 @@ processor, LSB first). * - SOFT_RESET - 1 - - Will engage a full software reset + - Value 5 -\ +SOFT_RESET response: -.. list-table:: SOFT_RESET Response +.. list-table:: :header-rows: 1 + :widths: 2 1 10 * - Field - Bytes @@ -450,11 +542,9 @@ processor, LSB first). * - SOFT_RESET - 1 - - Will engage a full software + - Value 5 * - SUCCESS - 1 - - Either 0 or 1 (FAILED,OK). Will end this bootloader session and reset the processor - -\ -\ + - Either 0 or 1 (FAILED and OK, respectively). Will end this + bootloader session and reset the processor. diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index bc9d6cd..39828e3 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -123,4 +123,4 @@ Recommended Reading * `All `_ * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) + * `Reference Manual `_ (pdf) diff --git a/source/foo.rst b/source/foo.rst index 5631922..1da021c 100644 --- a/source/foo.rst +++ b/source/foo.rst @@ -46,6 +46,7 @@ Finished: arduino/detachinterrupt arduino/digitalread arduino/double + arduino/doublecast arduino/dowhile arduino/else arduino/float @@ -77,7 +78,7 @@ Finished: arduino/sq arduino/static arduino/string - + Unfinished; straightforward to convert: .. toctree:: diff --git a/source/index.rst b/source/index.rst index fdaf801..ac91c4f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -15,19 +15,19 @@ Table of contents: .. TODO: be more Pythonic with a "parts of the documentation" thing .. toctree:: - :maxdepth: 2 - - Maple Quickstart Guide - Maple IDE Installation Guide - Maple IDE Documentation - Maple/Arduino Compatibility Reference - Maple Language Reference - Maple Library Reference - libmaple Command-Line Tools and APIs + :maxdepth: 1 + + Quickstart Guide + IDE Installation Guide + IDE Documentation + Language Reference + Arduino Compatibility Reference + Library Reference + Command-Line Tools and APIs Troubleshooting Hardware-Specific Documentation External Interrupts - Maple bootloader + Bootloader Known Problems [Temporary] Arduino docs TOC [Temporary] Wirish-only docs TOC diff --git a/source/language.rst b/source/language.rst index b2ef017..bbdbf90 100644 --- a/source/language.rst +++ b/source/language.rst @@ -9,16 +9,6 @@ The Maple can be programmed in the `Wiring `_ language, which is the same language used to program the `Arduino `_ boards. -Please see the extensive `language reference -`_ on the Arduino webpage for -more information, or follow a direct link below. - -.. warning:: - - The Arduino boards have different sizes for data types, so don't - trust their documentation for how many bytes an ``int``, ``long``, - etc. take up. The sizes of each data type on the Maple are given - in the :ref:`table below `. C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the @@ -59,268 +49,207 @@ Unique Maple Additions .. _language-arduino-docs: -Arduino Documentation Links ---------------------------- - -(This table was copied from http://arduino.cc/en/Reference/Extended). - -+------------------------------------+------------------------------------+-----------------------------------------+ -| Structure | Variables | Functions | -| | | | -+====================================+====================================+=========================================+ -| |**Constants** |**Digital I/O** | -|* `setup()`_ | | | -| |* `HIGH`_ | `LOW`_ |* `pinMode()`_ | -|* `loop()`_ | | | -| |* `INPUT`_ | `OUTPUT`_ |* `digitalWrite()`_ | -| | | | -|**Control Structures** |* `true`_ | `false`_ |* `digitalRead()`_ | -| | | | -|* `if`_ |* `integer constants`_ | | -| | |**Analog I/O** | -|* `if...else`_ |* `floating point constants`_ | | -| | |* `analogReference()`_ | -|* `for`_ | | | -| |**Data Types** |* `analogRead()`_ | -|* `switch/case`_ | | | -| |Primitive data types on the Maple |* `analogWrite()`_ - PWM | -|* `while`_ |have different sizes than on the | | -| |Arduino, since the Maple has a full | | -|* `do...while`_ |32-bit processor. The size of each |**Advanced I/O** | -| |such type on the Maple is given | | -|* `break`_ |below. |* `tone()`_ | -| | | | -|* `continue`_ |The ``word`` type is (deliberately) |* `noTone()`_ | -| |:ref:`not supported | | -|* `return`_ |`. |* `shiftOut()`_ | -| | | | -|* `goto`_ |* `void`_ |* `pulseIn()`_ | -| | | | -| |* `boolean`_ (1 byte) | | -|**Further syntax** | |**Time** | -| |* `char`_ (1 byte) | | -|* `;`_ (semicolon) | |* `millis()`_ | -| |* `unsigned char`_ (1 byte) | | -|* `{}`_ (curly braces) | |* `micros()`_ | -| |* `byte`_ (1 byte) | | -|* `//`_ (single line comment) | |* `delay()`_ | -| |* `int`_ (4 bytes) | | -|* `/\* \*/`_ (multi-line comment) | |* `delayMicroseconds()`_ | -| |* `unsigned int`_ (4 bytes) | | -|* `#define`_ | | | -| |* `long`_ (8 bytes) |**Math** | -|* `#include`_ | | | -| |* `unsigned long`_ (8 bytes) |* `min()`_ | -| | | | -|**Arithmetic Operators** |* `float`_ (4 bytes) |* `max()`_ | -| | | | -|* `=`_ (assignment operator) |* `double`_ (8 bytes) |* `abs()`_ | -| | | | -|* `+`_ (addition) |* `string`_ |* `constrain()`_ | -| | | | -|* `-`_ (subtraction) |* `array`_ |* `map()`_ | -| | | | -|* `*`_ (multiplication) | |* `pow()`_ | -| |**Conversion** | | -|* `/`_ (division) | |* `sqrt()`_ | -| |* `char()`_ | | -|* `%`_ (modulo) | | | -| |* `byte()`_ |**Trigonometry** | -| | | | -|**Comparison Operators** |* `int()`_ |* `sin()`_ | -| | | | -|* `==`_ (equal to) |* `word()`_ |* `cos()`_ | -| | | | -|* `!=`_ (not equal to) |* `long()`_ |* `tan()`_ | -| | | | -|* `<`_ (less than) |* `float()`_ | | -| | |**Random Numbers** | -|* `>`_ (greater than) | | | -| |**Variable Scope & Qualifiers** |* `randomSeed()`_ | -|* `<=`_ (less than or equal to) | | | -| |* `variable scope`_ |* `random()`_ | -|* `>=`_ (greater than or equal to) | | | -| |* `static`_ | | -| | |**Bits and Bytes** | -|**Boolean Operators** |* `volatile`_ | | -| | |* `lowByte()`_ | -|* `&&`_ (and) |* `const`_ | | -| | |* `highByte()`_ | -|* `||`_ (or) | | | -| |**Utilities** |* `bitRead()`_ | -|* `!`_ (not) | | | -| |* `sizeof()`_ (sizeof operator) |* `bitWrite()`_ | -| | | | -|**Pointer Access Operators** | |* `bitSet()`_ | -| | | | -|* `* dereference operator`_ | |* `bitClear()`_ | -| | | | -|* `& reference operator`_ | |* `bit()`_ | -| | | | -| | | | -|**Bitwise Operators** | |**External Interrupts** | -| | | | -|* `&`_ (bitwise and) | |For more information on external | -| | |interrupts on Maple, see | -|* `|`_ (bitwise or) | |`our reference page`_. | -| | | | -|* `^`_ (bitwise xor) | | | -| | |* `attachInterrupt()`_ | -|* `~`_ (bitwise not) | | | -| | |* `detachInterrupt()`_ | -|* `<<`_ (shift left) | | | -| | | | -|* `>>`_ (shift right) | |**Interrupts** | -| | | | -| | |* `interrupts()`_ | -|**Compound Operators** | | | -| | |* `noInterrupts()`_ | -|* `++`_ (increment) | | | -| | | | -|* `- -`_ (decrement) | |**Communication** | -| | | | -|* `+=`_ (compound addition) | |* `Serial`_ | -| | | | -|* `-=`_ (compound subtraction) | |**Looking for something else?** | -| | | | -|* `*=`_ (compound multiplication) | |See the :ref:`libraries` page for | -| | |interfacing with particular types of | -|* `/=`_ (compound division) | |hardware. Try the list of | -| | |`community-contributed code`_. Maple | -|* `&=`_ (compound bitwise and) | |links against `newlib`_ and allows the | -| | |use of any of its functions; see its | -|* `|=`_ (compound bitwise or) | |documentation for more details. | -| | | | -+------------------------------------+------------------------------------+-----------------------------------------+ +Maple Language Reference +------------------------ + ++-------------------------------------------------+----------------------------------------------+---------------------------------------------------+ +| Structure | Variables | Functions | +| | | | ++=================================================+==============================================+===================================================+ +|* :ref:`setup() ` |**Constants** |**Digital I/O** | +| | | | +|* :ref:`loop() ` |* :ref:`HIGH ` | |* :ref:`pinMode() ` | +| | :ref:`LOW ` | | +| | |* :ref:`digitalWrite() ` | +|**Control Structures** |* :ref:`INPUT ` | | | +| | :ref:`OUTPUT ` |* :ref:`digitalRead() ` | +|* :ref:`if ` | | | +| |* :ref:`true ` | | | +|* :ref:`if...else ` | :ref:`false ` |**Analog I/O** | +| | | | +|* :ref:`for ` |* :ref:`integer constants |* :ref:`analogRead() ` | +| | ` | | +|* :ref:`switch/case ` | |* :ref:`pwmWrite() ` | +| |* :ref:`floating point constants | (:ref:`analogWrite() ` is | +|* :ref:`while ` | ` | also available, though its use is discouraged) | +| | | | +|* :ref:`do...while ` | | | +| |**Data Types** |**Advanced I/O** | +|* :ref:`break ` | | | +| | The size of each datatype, in bytes, is |* tone(): TODO | +|* :ref:`continue ` | given in parentheses where appropriate. | | +| | |* noTone(): TODO | +|* :ref:`return ` | *Note*: The ``word`` type is (deliberately) | | +| | :ref:`not supported `. |* shiftOut(): TODO | +|* :ref:`goto ` | | | +| |* :ref:`void ` |* pulseIn(): TODO | +| | | | +|**Further syntax** |* :ref:`boolean ` (1 byte) | | +| | |**Time** | +|* :ref:`; ` (semicolon) |* :ref:`char ` (1 byte) | | +| | |* :ref:`millis() ` | +|* :ref:`{} ` (curly braces) |* :ref:`unsigned char | | +| | ` (1 byte) |* :ref:`micros() ` | +|* :ref:`// ` | | | +| (single line comment) |* :ref:`byte ` (1 byte) |* :ref:`delay() ` | +| | | | +|* :ref:`/\* \*/ |* :ref:`int ` (4 bytes) |* :ref:`delayMicroseconds() | +| ` | | ` | +| (multi-line comment) |* :ref:`unsigned int ` | | +| | (4 bytes) | | +|* :ref:`#define ` | |**Math** | +| |* :ref:`long ` (8 bytes) | | +|* :ref:`#include ` | |* :ref:`min() ` | +| |* :ref:`unsigned long ` | | +| | (8 bytes) |* :ref:`max() ` | +|**Arithmetic Operators** | | | +| |* :ref:`float ` (4 bytes) |* :ref:`abs() ` | +|* :ref:`= ` | | | +| (assignment operator) |* :ref:`double ` (8 bytes) |* :ref:`constrain() ` | +| | | | +|* :ref:`+ ` (addition) |* :ref:`string ` |* :ref:`map() ` | +| | | | +|* :ref:`- ` |* :ref:`array ` |* :ref:`pow() ` | +| (subtraction) | | | +| |* Also provided: ``int8``, ``int16``, |* :ref:`sqrt() ` | +|* :ref:`* ` | ``int32``, ``int64``, and their unsigned | | +| (multiplication) | counterparts ``uint8``, ``uint16``, | | +| | ``uint32``, ``uint64``. |**Trigonometry** | +|* :ref:`/ ` (division) | | | +| | |* :ref:`sin() ` | +|* :ref:`% ` (modulo) |**Conversion** | | +| | |* :ref:`cos() ` | +| |* :ref:`char() ` | | +|**Comparison Operators** | |* :ref:`tan() ` | +| |* :ref:`byte() ` | | +|* :ref:`== ` (equal to) | | | +| |* :ref:`int() ` |**Random Numbers** | +|* :ref:`\!= ` | | | +| (not equal to) |* :ref:`long() ` |* :ref:`randomSeed() ` | +| | | | +|* :ref:`< ` (less than) |* :ref:`float() ` |* :ref:`random() ` | +| | | | +|* :ref:`> ` |* :ref:`double() ` | | +| (greater than) | |**Bits and Bytes** | +| | | | +|* :ref:`<= ` |**Variable Scope & Qualifiers** |* :ref:`lowByte() ` | +| (less than or equal to) | | | +| |* :ref:`variables `, |* :ref:`highByte() ` is | +|* :ref:`>= ` | :ref:`scope ` | provided, though its use is discouraged. | +| (greater than or equal to) | | | +| |* :ref:`static ` |* :ref:`bitRead() ` | +| | | | +|**Boolean Operators** |* :ref:`volatile ` |* :ref:`bitWrite() ` | +| | | | +|* :ref:`&& ` (and) |* :ref:`const ` |* :ref:`bitSet() ` | +| | | | +|* :ref:`|| ` (or) | |* :ref:`bitClear() ` | +| |**Utilities** | | +|* :ref:`\! ` (not) | |* :ref:`bit() ` | +| |* :ref:`sizeof() ` | | +| | (``sizeof`` operator) | | +|**Pointer Access Operators** | |**External Interrupts** | +| | | | +|* :ref:`* dereference operator | |* :ref:`Reference Page ` | +| ` | | | +| | |* :ref:`attachInterrupt() | +|* :ref:`& reference operator | | ` | +| ` | | | +| | |* :ref:`detachInterrupt() | +| | | ` | +|**Bitwise Operators** | | | +| | | | +|* :ref:`& ` | |**Interrupts** | +| (bitwise and) | | | +| | |* interrupts(): TODO | +|* :ref:`| ` | | | +| (bitwise or) | |* noInterrupts(): TODO | +| | | | +|* :ref:`^ ` | | | +| (bitwise xor) | |**Communication** | +| | | | +|* :ref:`~ ` | |* :ref:`SerialUSB ` | +| (bitwise not) | | | +| | |* :ref:`Serial ` | +|* :ref:`\<\< ` | | | +| (shift left) | |**Looking for something else?** | +| | | | +|* :ref:`>> ` | | See the :ref:`libraries` page for interfacing with| +| (shift right) | | particular types of hardware. Try the list of | +| | | `community-contributed code` . Maple links | +| | | against `newlib` and allows the use of any of its | +|**Compound Operators** | | functions; see its documentation for more details.| +| | | | +|* :ref:`++ ` | | | +| (increment) | | | +| | | | +|* :ref:`- - ` | | | +| (decrement) | | | +| | | | +|* :ref:`+= ` | | | +| (compound add) | | | +| | | | +|* :ref:`-= | | | +| ` (compound | | | +| subtract) | | | +| | | | +|* :ref:`*= | | | +| ` (compound | | | +| multiply) | | | +| | | | +|* :ref:`/= | | | +| ` (compound | | | +| divide) | | | +| | | | +|* :ref:`&= | | | +| ` (compound | | | +| bitwise and) | | | +| | | | +|* :ref:`|= | | | +| ` (compound | | | +| bitwise or) | | | +| | | | ++-------------------------------------------------+----------------------------------------------+---------------------------------------------------+ .. _language-missing-features: -Stub TODO: fill in other missing features, like analogReference() - -.. note:: - - The ``word`` data type is not supported on the Maple. This is by - choice. - - We decided not to include it because, while the Maple has 32-bit - words, the word size on an Arduino board is only 16 bits, and code - that uses the ``word`` type is likely to rely on that fact. - - By not supporting ``word``, you'll get a compile error when porting - Arduino code to your Maple instead of potentially weird, - hard-to-debug runtime behavior. - - If you're porting over Arduino code and really want ``word``, you - can put the following at the top of the file you're porting:: - - typedef uint16 word; - -.. _if: http://arduino.cc/en/Reference/If -.. _if...else: http://arduino.cc/en/Reference/Else -.. _for: http://arduino.cc/en/Reference/For -.. _switch/case: http://arduino.cc/en/Reference/SwitchCase -.. _while: http://arduino.cc/en/Reference/While -.. _do...while: http://arduino.cc/en/Reference/DoWhile -.. _break: http://arduino.cc/en/Reference/Break -.. _continue: http://arduino.cc/en/Reference/Continue -.. _return: http://arduino.cc/en/Reference/Return -.. _goto: http://arduino.cc/en/Reference/Goto - -.. _;: http://arduino.cc/en/Reference/SemiColon -.. _{}: http://arduino.cc/en/Reference/Braces -.. _//: http://arduino.cc/en/Reference/Comments -.. _/\* \*/: http://arduino.cc/en/Reference/Comments -.. _#define: http://arduino.cc/en/Reference/Define -.. _#include: http://arduino.cc/en/Reference/Include - -.. _=: http://arduino.cc/en/Reference/Assignment -.. _+: http://arduino.cc/en/Reference/Arithmetic -.. _-: http://arduino.cc/en/Reference/Arithmetic -.. _*: http://arduino.cc/en/Reference/Arithmetic -.. _/: http://arduino.cc/en/Reference/Arithmetic -.. _%: http://arduino.cc/en/Reference/Modulo - -.. _==: http://arduino.cc/en/Reference/If -.. _!=: http://arduino.cc/en/Reference/If -.. _<: http://arduino.cc/en/Reference/If -.. _>: http://arduino.cc/en/Reference/If -.. _<=: http://arduino.cc/en/Reference/If -.. _>=: http://arduino.cc/en/Reference/If - -.. _&&: http://arduino.cc/en/Reference/Boolean -.. _||: http://arduino.cc/en/Reference/Boolean -.. _!: http://arduino.cc/en/Reference/Boolean - -.. _* dereference operator: http://arduino.cc/en/Reference/Pointer -.. _& reference operator: http://arduino.cc/en/Reference/Pointer - -.. _&: http://arduino.cc/en/Reference/BitwiseAnd -.. _|: http://arduino.cc/en/Reference/BitwiseAnd -.. _^: http://arduino.cc/en/Reference/BitwiseAnd -.. _~: http://arduino.cc/en/Reference/BitwiseXorNot -.. _<<: http://arduino.cc/en/Reference/Bitshift -.. _>>: http://arduino.cc/en/Reference/Bitshift - -.. _++: http://arduino.cc/en/Reference/Increment -.. FIXME can't freaking get two hyphens to show up! sphinx turns "--" -.. into an endash, whatever, fine, try to escape like "\-\-", that -.. ALSO becomes endash (!@#$), damn, well, maybe someone else is -.. eating my slash, try "\\-\\-", nope, that turns into a motherfing -.. \-\-. i hate everything. -.. _- -: http://arduino.cc/en/Reference/Increment -.. _+=: http://arduino.cc/en/Reference/IncrementCompound -.. _-=: http://arduino.cc/en/Reference/IncrementCompound -.. _*=: http://arduino.cc/en/Reference/IncrementCompound -.. _/=: http://arduino.cc/en/Reference/IncrementCompound -.. _&=: http://arduino.cc/en/Reference/BitwiseCompound -.. _|=: http://arduino.cc/en/Reference/BitwiseCompound - -.. _HIGH: http://arduino.cc/en/Reference/Constants -.. _LOW: http://arduino.cc/en/Reference/Constants -.. _INPUT: http://arduino.cc/en/Reference/Constants -.. _OUTPUT: http://arduino.cc/en/Reference/Constants -.. _true: http://arduino.cc/en/Reference/Constants -.. _false: http://arduino.cc/en/Reference/Constants -.. _integer constants: http://arduino.cc/en/Reference/IntegerConstants -.. _floating point constants: http://arduino.cc/en/Reference/Fpconstants - -.. _void: http://arduino.cc/en/Reference/Void -.. _boolean: http://arduino.cc/en/Reference/BooleanVariables -.. _char: http://arduino.cc/en/Reference/Char -.. _unsigned char: http://arduino.cc/en/Reference/UnsignedChar -.. _byte: http://arduino.cc/en/Reference/Byte -.. _int: http://arduino.cc/en/Reference/Int -.. _unsigned int: http://arduino.cc/en/Reference/UnsignedInt -.. _word: http://arduino.cc/en/Reference/Word -.. _long: http://arduino.cc/en/Reference/Long -.. _unsigned long: http://arduino.cc/en/Reference/UnsignedLong -.. _float: http://arduino.cc/en/Reference/Float -.. _double: http://arduino.cc/en/Reference/Double -.. _string: http://arduino.cc/en/Reference/String -.. _array: http://arduino.cc/en/Reference/Array - -.. _char(): http://arduino.cc/en/Reference/CharCast -.. _byte(): http://arduino.cc/en/Reference/ByteCast -.. _int(): http://arduino.cc/en/Reference/IntCast -.. _word(): http://arduino.cc/en/Reference/WordCast -.. _long(): http://arduino.cc/en/Reference/LongCast -.. _float(): http://arduino.cc/en/Reference/FloatCast - -.. _variable scope: http://arduino.cc/en/Reference/Scope -.. _static: http://arduino.cc/en/Reference/Static -.. _volatile: http://arduino.cc/en/Reference/Volatile -.. _const: http://arduino.cc/en/Reference/Const -.. _sizeof(): http://arduino.cc/en/Reference/Sizeof - -.. Links for the standard Arduino built-in functions are included as -.. part of the standard epilog. +Missing Arduino Features +------------------------ + +Stub TODO: fill in other missing features + +**analogReference()** + + It is not possible to implement this function on the Maple + hardware. It will be possible on the upcoming Maple Native. + +.. _language-no-word: + +**word** + + Readers familiar with the Arduino environment may notice that the + ``word`` datatype is missing from the above table's list of data + types. We chose **not to provide** the ``word`` data type on the + Maple. If you want a 16-bit unsigned integer, use the ``uint16`` + type instead. + + While the Maple has 32-bit words, the word size on an Arduino + board is only 16 bits, and code that uses the ``word`` type is + likely to rely on that fact. + + By not supporting ``word``, you'll get a compile error when + porting Arduino code to the Maple instead of potentially weird, + hard-to-debug runtime behavior. + + If you really must have ``word``, you can include the following + ``typedef`` in your program:: + + typedef uint16 word; + .. _our reference page: http://leaflabs.com/docs/external-interrupts/ -.. _Serial: http://arduino.cc/en/Reference/Serial -.. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary .. _newlib: http://sourceware.org/newlib/ - .. _arduino_c_for_c_hackers: Note for C/C++ Programmers @@ -331,7 +260,11 @@ you C programmers should remember that `C++ is not a superset of C `_) who want a better understanding of the differences between C++ and the Wiring language. The good news is that the differences are relatively -few. +few; Wiring is just a thin wrapper around C++. + +Some potentially better news is that the Maple can be programmed using +a :ref:`standard Unix toolchain `, so if you'd rather +stick with :command:`gcc`, :command:`make`, and friends, you can. A *sketch* is the IDE's notion of a project; it consists of one or more files written in the Wiring language, which is mostly the same as @@ -361,8 +294,8 @@ The Wiring language also does not require you to define your own are required to define two functions, ``setup`` and ``loop``, with type signatures :: - void setup(void) - void loop(void) + void setup(void); + void loop(void); Once a sketch is uploaded to a Maple and begins to run, ``setup()`` is called once, and then ``loop()`` is called repeatedly. The IDE diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index b595f70..2bb584a 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -32,20 +32,16 @@ GCC compiler tools `_ please post in the forums, so we can fold your tips into this document! -* :ref:`Linux setup ` -* :ref:`OS X setup ` -* :ref:`Test compilation ` -* :ref:`Upload a program ` -* :ref:`Communicate over USB-serial interface ` -* :ref:`Starting your own projects ` -* :ref:`Debug with OpenOCD ` -* :ref:`Do it all with Code::Blocks ` -* :ref:`Go forth exuberantly! ` +.. contents:: Contents + :local: .. _toolchain-linux-setup: -Linux Setup ------------ +Setup +----- + +Linux +^^^^^ These instructions are oriented towards Linux users using a contemporary Debian-based distribution. @@ -55,7 +51,7 @@ contemporary Debian-based distribution. First I'll give the commands to run, then explain:: $ sudo aptitude install build-essential git-core wget screen dfu-util \ - openocd python python-serial + openocd python python-serial You'll want to install a bunch of developer "basics" like :command:`make`, :command:`tar`, etc. A good catch-all for these @@ -90,12 +86,12 @@ package; this could also be installed with `easy_install **2. Fetch libmaple and Compiler Toolchain** :: - $ cd ~ - $ git clone git://github.com/leaflabs/libmaple.git libmaple - $ cd libmaple + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git libmaple + $ cd libmaple $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz $ tar xvf arm-*-linux32.tar.gz - $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up + $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up This step is fairly straightforward: do a git clone of the `libmaple repository `_ to some directory, @@ -114,9 +110,9 @@ relative path calls and references. From the libmaple directory, :: - $ groups # make sure it includes plugdev; if not add, yourself to it - $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules - $ sudo /etc/init.d/udev restart + $ groups # make sure it includes plugdev; if not add, yourself to it + $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules + $ sudo /etc/init.d/udev restart As a security precaution on linux, unknown USB devices can only be accessed by the superuser. This udev script identifies the Maple based @@ -132,8 +128,8 @@ Great! Test your setup by :ref:`compiling a sample program .. _toolchain-osx-setup: -OS X Setup ----------- +OS X +^^^^ These instructions have been tested successfully on OS X 10.6.4. As stated previously, this document assumes a general level of Unix @@ -185,7 +181,7 @@ You will need the following tools to get started: $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ /somewhere/on/your/PATH/dfu-util - .. note:: + .. note:: Just copying the binary somewhere doesn't work, as it relies on dynamically linked libraries found elsewhere in the .app bundle. It's possible to pull just the relevant pieces out of the @@ -426,7 +422,7 @@ then `install Code::Blocks `_. You can do this on Linux with:: - $ sudo aptitude install codeblocks + $ sudo aptitude install codeblocks The first time it runs you'll maybe want to disable all the glitzy "Getting Started" crap (when will they learn?). We've added a .cbp diff --git a/source/wirish.rst b/source/wirish.rst index 2773e24..e8e608e 100644 --- a/source/wirish.rst +++ b/source/wirish.rst @@ -7,3 +7,4 @@ wirish/pwmwrite wirish/types + wirish/serialusb diff --git a/source/wirish/pwmwrite.rst b/source/wirish/pwmwrite.rst index b1f0515..7667a72 100644 --- a/source/wirish/pwmwrite.rst +++ b/source/wirish/pwmwrite.rst @@ -24,26 +24,25 @@ Example Sets the output to the LED proportional to the value read from the potentiometer (adapted for Maple from the Arduino `analogWrite() -reference `_\ ):: +reference `_):: - - int ledPin = 13; // LED connected to pin 13 (Maple-specific) + + int ledPin = 13; // LED connected to pin 13 (Maple) int analogPin = 3; // potentiometer connected to analog pin 3 int val = 0; // variable to store the read value - + void setup() { pinMode(ledPin, OUTPUT); // sets the LED pin as output pinMode(analogPin, PWM); // sets the potentiometer pin as PWM - // output (Maple-specific) + // output } - + void loop() { val = analogRead(analogPin); // read the input pin analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, // analogWrite values from 0 to 65535 - // (Maple-specific) } See Also -- cgit v1.2.3 From 546b34076d230b617ba86defb6b90cd934b01878 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 21 Nov 2010 04:41:22 -0500 Subject: bootloader spec tweaks to be closer to stk-500 --- source/arduino/doublecast.rst | 30 ++++++++++++++++++++++++++++++ source/bootloader.rst | 27 +++++++++++++++++---------- source/wirish/serialusb.rst | 6 ++++++ 3 files changed, 53 insertions(+), 10 deletions(-) create mode 100644 source/arduino/doublecast.rst create mode 100644 source/wirish/serialusb.rst diff --git a/source/arduino/doublecast.rst b/source/arduino/doublecast.rst new file mode 100644 index 0000000..9aaf12c --- /dev/null +++ b/source/arduino/doublecast.rst @@ -0,0 +1,30 @@ +.. highlight:: cpp + +.. _arduino-doublecast: + +double() (cast) +=============== + +Description +----------- + +Converts a value to the :ref:`double ` floating point +data type. Here is an example:: + + int x = 2; + double d = double(x); // d now holds 2.0, a double value + +The value ``x`` can be of any type. However, if ``x`` is not a number +(like an ``int`` or ``long``), you will get strange results. + +See the :ref:`double ` reference for details about the +precision and limitations of ``double`` values on the Maple. + +See Also +-------- + +- :ref:`double ` +- :ref:`float ` +- :ref:`float() ` + +.. include:: cc-attribution.txt diff --git a/source/bootloader.rst b/source/bootloader.rst index 4be8e93..46c2cf0 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -218,20 +218,25 @@ A bootloader packet is composed of a sequence of fields, as follows. - Description * - START - - 2 - - 0x7EAF + - 1 + - 0x1B - Magic constant, indicates bootloader packet * - SEQUENCE_NUM - 1 - - 0--255 + - 0--0xFF - Queries and responses must have the same sequence number; rolls - over to 0 after 255. + over to 0 after 0xFF. * - MESSAGE_SIZE - 2 - - 0--65,535 - - Size of message body, currently limited to a 512B maximum + - 0--0xFFFF + - Size of message body, currently limited to a 1024B maximum + + * - TOKEN + - 1 + - 0x7F + - Differs from STK500 value of 0x0E * - MESSAGE_BODY - Variable, determined by MESSAGE_SIZE field @@ -240,8 +245,10 @@ A bootloader packet is composed of a sequence of fields, as follows. * - CHECKSUM - 4 - - XOR of all other bytes in packet - - + - XOR of all other 32-bit words in packet + - Words are checksummed little-endian; however, like all + multi-byte fields, the CHECKSUM is transmitted between PC and + device in network (big-endian) order. .. _bootloader-commands: @@ -253,8 +260,8 @@ and responses are transacted inside of the message body. Following in the footsteps of the STK-500 protocol, each query or response begins with the single byte CMD field. For each query, the resultant response must begin with the same CMD byte. For each type of CMD, the structure -of queries and responses are of fixed size. As in STK-500, fields -longer than 1 byte are transmitted MSB first (big endian). However, +of queries and responses is of fixed size. Following STK-500, fields +longer than 1 byte are transmitted MSB first (big-endian). However, READ and WRITE commands operate byte-wise (not word-wise); it is up to the host PC to ensure that alignment and ordering issues are handled appropriately. diff --git a/source/wirish/serialusb.rst b/source/wirish/serialusb.rst new file mode 100644 index 0000000..d0eac98 --- /dev/null +++ b/source/wirish/serialusb.rst @@ -0,0 +1,6 @@ +.. _wirish-serialusb: + +Serial over USB Communications +============================== + +Stub. -- cgit v1.2.3 From d9cbd78e29d42e70bb46641dd43ee0772c8c975f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 28 Nov 2010 11:23:33 -0500 Subject: reorganized all the arduino/ docs into a lang/ subdirectory since they're properly CC attributed now. --- source/arduino/abs.rst | 42 ----- source/arduino/analogread.rst | 152 ---------------- source/arduino/analogwrite.rst | 164 ----------------- source/arduino/arithmetic.rst | 129 -------------- source/arduino/arithmeticcompound.rst | 46 ----- source/arduino/array.rst | 123 ------------- source/arduino/assignment.rst | 70 -------- source/arduino/attachinterrupt.rst | 102 ----------- source/arduino/bit.rst | 48 ----- source/arduino/bitclear.rst | 47 ----- source/arduino/bitread.rst | 49 ------ source/arduino/bitset.rst | 49 ------ source/arduino/bitshift.rst | 148 ---------------- source/arduino/bitwisecompound.rst | 231 ------------------------ source/arduino/bitwisemath.rst | 186 -------------------- source/arduino/bitwrite.rst | 40 ----- source/arduino/boolean.rst | 91 ---------- source/arduino/booleanvariables.rst | 55 ------ source/arduino/braces.rst | 97 ----------- source/arduino/break.rst | 35 ---- source/arduino/byte.rst | 34 ---- source/arduino/bytecast.rst | 53 ------ source/arduino/cc-attribution.txt | 9 - source/arduino/char.rst | 52 ------ source/arduino/charcast.rst | 39 ----- source/arduino/comments.rst | 67 ------- source/arduino/comparison.rst | 87 --------- source/arduino/const.rst | 52 ------ source/arduino/constants.rst | 302 -------------------------------- source/arduino/constrain.rst | 65 ------- source/arduino/continue.rst | 34 ---- source/arduino/cos.rst | 33 ---- source/arduino/define.rst | 56 ------ source/arduino/delay.rst | 70 -------- source/arduino/delaymicroseconds.rst | 65 ------- source/arduino/detachinterrupt.rst | 37 ---- source/arduino/digitalread.rst | 61 ------- source/arduino/digitalwrite.rst | 116 ------------ source/arduino/double.rst | 49 ------ source/arduino/doublecast.rst | 30 ---- source/arduino/dowhile.rst | 27 --- source/arduino/else.rst | 54 ------ source/arduino/float.rst | 58 ------ source/arduino/floatcast.rst | 31 ---- source/arduino/for.rst | 142 --------------- source/arduino/goto.rst | 130 -------------- source/arduino/highbyte.rst | 53 ------ source/arduino/if.rst | 81 --------- source/arduino/include.rst | 71 -------- source/arduino/increment.rst | 44 ----- source/arduino/int.rst | 70 -------- source/arduino/intcast.rst | 32 ---- source/arduino/interrupts.rst | 62 ------- source/arduino/long.rst | 55 ------ source/arduino/longcast.rst | 30 ---- source/arduino/loop.rst | 45 ----- source/arduino/lowbyte.rst | 45 ----- source/arduino/map.rst | 122 ------------- source/arduino/max.rst | 63 ------- source/arduino/micros.rst | 69 -------- source/arduino/millis.rst | 70 -------- source/arduino/min.rst | 66 ------- source/arduino/modulo.rst | 77 -------- source/arduino/nointerrupts.rst | 59 ------- source/arduino/notone.rst | 50 ------ source/arduino/pinmode.rst | 76 -------- source/arduino/pointer.rst | 28 --- source/arduino/pow.rst | 29 --- source/arduino/pulsein.rst | 82 --------- source/arduino/random.rst | 95 ---------- source/arduino/randomseed.rst | 73 -------- source/arduino/return.rst | 61 ------- source/arduino/scope.rst | 62 ------- source/arduino/semicolon.rst | 25 --- source/arduino/serial.rst | 68 -------- source/arduino/setup.rst | 34 ---- source/arduino/shiftout.rst | 136 --------------- source/arduino/sin.rst | 28 --- source/arduino/sizeof.rst | 64 ------- source/arduino/sq.rst | 42 ----- source/arduino/sqrt.rst | 25 --- source/arduino/static.rst | 57 ------ source/arduino/string.rst | 131 -------------- source/arduino/stringclass.rst | 9 - source/arduino/stringobject.rst | 91 ---------- source/arduino/switchcase.rst | 117 ------------- source/arduino/tan.rst | 38 ---- source/arduino/tone.rst | 81 --------- source/arduino/unsignedchar.rst | 44 ----- source/arduino/unsignedint.rst | 80 --------- source/arduino/unsignedlong.rst | 66 ------- source/arduino/variables.rst | 191 -------------------- source/arduino/void.rst | 40 ----- source/arduino/volatile.rst | 73 -------- source/arduino/while.rst | 49 ------ source/arduino/word.rst | 32 ---- source/arduino/wordcast.rst | 54 ------ source/bootloader.rst | 51 ++++-- source/external-interrupts.rst | 2 +- source/foo.rst | 122 ------------- source/ide.rst | 12 ++ source/index.rst | 16 +- source/lang/abs.rst | 42 +++++ source/lang/analogread.rst | 152 ++++++++++++++++ source/lang/analogwrite.rst | 164 +++++++++++++++++ source/lang/arithmetic.rst | 129 ++++++++++++++ source/lang/arithmeticcompound.rst | 46 +++++ source/lang/array.rst | 123 +++++++++++++ source/lang/assignment.rst | 70 ++++++++ source/lang/attachinterrupt.rst | 102 +++++++++++ source/lang/bit.rst | 48 +++++ source/lang/bitclear.rst | 47 +++++ source/lang/bitread.rst | 49 ++++++ source/lang/bitset.rst | 49 ++++++ source/lang/bitshift.rst | 148 ++++++++++++++++ source/lang/bitwisecompound.rst | 231 ++++++++++++++++++++++++ source/lang/bitwisemath.rst | 186 ++++++++++++++++++++ source/lang/bitwrite.rst | 40 +++++ source/lang/boolean.rst | 91 ++++++++++ source/lang/booleanvariables.rst | 55 ++++++ source/lang/braces.rst | 109 ++++++++++++ source/lang/break.rst | 35 ++++ source/lang/byte.rst | 34 ++++ source/lang/bytecast.rst | 53 ++++++ source/lang/cc-attribution.txt | 9 + source/lang/char.rst | 53 ++++++ source/lang/charcast.rst | 39 +++++ source/lang/comments.rst | 67 +++++++ source/lang/comparison.rst | 87 +++++++++ source/lang/const.rst | 52 ++++++ source/lang/constants.rst | 302 ++++++++++++++++++++++++++++++++ source/lang/constrain.rst | 65 +++++++ source/lang/continue.rst | 34 ++++ source/lang/cos.rst | 32 ++++ source/lang/define.rst | 56 ++++++ source/lang/delay.rst | 72 ++++++++ source/lang/delaymicroseconds.rst | 65 +++++++ source/lang/detachinterrupt.rst | 37 ++++ source/lang/digitalread.rst | 61 +++++++ source/lang/digitalwrite.rst | 116 ++++++++++++ source/lang/double.rst | 51 ++++++ source/lang/doublecast.rst | 30 ++++ source/lang/dowhile.rst | 27 +++ source/lang/else.rst | 54 ++++++ source/lang/enum.rst | 8 + source/lang/float.rst | 53 ++++++ source/lang/floatcast.rst | 31 ++++ source/lang/for.rst | 142 +++++++++++++++ source/lang/goto.rst | 130 ++++++++++++++ source/lang/highbyte.rst | 53 ++++++ source/lang/if.rst | 81 +++++++++ source/lang/include.rst | 71 ++++++++ source/lang/increment.rst | 44 +++++ source/lang/int.rst | 67 +++++++ source/lang/intcast.rst | 32 ++++ source/lang/interrupts.rst | 62 +++++++ source/lang/keywords.rst | 11 ++ source/lang/long.rst | 55 ++++++ source/lang/longcast.rst | 30 ++++ source/lang/loop.rst | 45 +++++ source/lang/lowbyte.rst | 45 +++++ source/lang/map.rst | 122 +++++++++++++ source/lang/max.rst | 63 +++++++ source/lang/micros.rst | 69 ++++++++ source/lang/millis.rst | 70 ++++++++ source/lang/min.rst | 66 +++++++ source/lang/modulo.rst | 77 ++++++++ source/lang/nointerrupts.rst | 59 +++++++ source/lang/notone.rst | 50 ++++++ source/lang/pinmode.rst | 76 ++++++++ source/lang/pointer.rst | 28 +++ source/lang/pow.rst | 29 +++ source/lang/pulsein.rst | 82 +++++++++ source/lang/pwmwrite.rst | 51 ++++++ source/lang/random.rst | 95 ++++++++++ source/lang/randomseed.rst | 73 ++++++++ source/lang/return.rst | 61 +++++++ source/lang/scope.rst | 120 +++++++++++++ source/lang/semicolon.rst | 25 +++ source/lang/serial.rst | 68 ++++++++ source/lang/serialusb.rst | 8 + source/lang/setup.rst | 34 ++++ source/lang/shiftout.rst | 136 +++++++++++++++ source/lang/sin.rst | 32 ++++ source/lang/sizeof.rst | 64 +++++++ source/lang/sq.rst | 42 +++++ source/lang/sqrt.rst | 25 +++ source/lang/static.rst | 57 ++++++ source/lang/string.rst | 131 ++++++++++++++ source/lang/stringclass.rst | 9 + source/lang/stringobject.rst | 91 ++++++++++ source/lang/switchcase.rst | 117 +++++++++++++ source/lang/tan.rst | 31 ++++ source/lang/tone.rst | 81 +++++++++ source/lang/types.rst | 7 + source/lang/unsignedchar.rst | 36 ++++ source/lang/unsignedint.rst | 58 ++++++ source/lang/unsignedlong.rst | 44 +++++ source/lang/variables.rst | 170 ++++++++++++++++++ source/lang/void.rst | 40 +++++ source/lang/volatile.rst | 73 ++++++++ source/lang/while.rst | 49 ++++++ source/language-index.rst | 131 ++++++++++++++ source/language.rst | 320 +++++++++++++++++----------------- source/wirish.rst | 10 -- source/wirish/pwmwrite.rst | 51 ------ source/wirish/serialusb.rst | 6 - source/wirish/types.rst | 6 - 208 files changed, 7240 insertions(+), 7280 deletions(-) delete mode 100644 source/arduino/abs.rst delete mode 100644 source/arduino/analogread.rst delete mode 100644 source/arduino/analogwrite.rst delete mode 100644 source/arduino/arithmetic.rst delete mode 100644 source/arduino/arithmeticcompound.rst delete mode 100644 source/arduino/array.rst delete mode 100644 source/arduino/assignment.rst delete mode 100644 source/arduino/attachinterrupt.rst delete mode 100644 source/arduino/bit.rst delete mode 100644 source/arduino/bitclear.rst delete mode 100644 source/arduino/bitread.rst delete mode 100644 source/arduino/bitset.rst delete mode 100644 source/arduino/bitshift.rst delete mode 100644 source/arduino/bitwisecompound.rst delete mode 100644 source/arduino/bitwisemath.rst delete mode 100644 source/arduino/bitwrite.rst delete mode 100644 source/arduino/boolean.rst delete mode 100644 source/arduino/booleanvariables.rst delete mode 100644 source/arduino/braces.rst delete mode 100644 source/arduino/break.rst delete mode 100644 source/arduino/byte.rst delete mode 100644 source/arduino/bytecast.rst delete mode 100644 source/arduino/cc-attribution.txt delete mode 100644 source/arduino/char.rst delete mode 100644 source/arduino/charcast.rst delete mode 100644 source/arduino/comments.rst delete mode 100644 source/arduino/comparison.rst delete mode 100644 source/arduino/const.rst delete mode 100644 source/arduino/constants.rst delete mode 100644 source/arduino/constrain.rst delete mode 100644 source/arduino/continue.rst delete mode 100644 source/arduino/cos.rst delete mode 100644 source/arduino/define.rst delete mode 100644 source/arduino/delay.rst delete mode 100644 source/arduino/delaymicroseconds.rst delete mode 100644 source/arduino/detachinterrupt.rst delete mode 100644 source/arduino/digitalread.rst delete mode 100644 source/arduino/digitalwrite.rst delete mode 100644 source/arduino/double.rst delete mode 100644 source/arduino/doublecast.rst delete mode 100644 source/arduino/dowhile.rst delete mode 100644 source/arduino/else.rst delete mode 100644 source/arduino/float.rst delete mode 100644 source/arduino/floatcast.rst delete mode 100644 source/arduino/for.rst delete mode 100644 source/arduino/goto.rst delete mode 100644 source/arduino/highbyte.rst delete mode 100644 source/arduino/if.rst delete mode 100644 source/arduino/include.rst delete mode 100644 source/arduino/increment.rst delete mode 100644 source/arduino/int.rst delete mode 100644 source/arduino/intcast.rst delete mode 100644 source/arduino/interrupts.rst delete mode 100644 source/arduino/long.rst delete mode 100644 source/arduino/longcast.rst delete mode 100644 source/arduino/loop.rst delete mode 100644 source/arduino/lowbyte.rst delete mode 100644 source/arduino/map.rst delete mode 100644 source/arduino/max.rst delete mode 100644 source/arduino/micros.rst delete mode 100644 source/arduino/millis.rst delete mode 100644 source/arduino/min.rst delete mode 100644 source/arduino/modulo.rst delete mode 100644 source/arduino/nointerrupts.rst delete mode 100644 source/arduino/notone.rst delete mode 100644 source/arduino/pinmode.rst delete mode 100644 source/arduino/pointer.rst delete mode 100644 source/arduino/pow.rst delete mode 100644 source/arduino/pulsein.rst delete mode 100644 source/arduino/random.rst delete mode 100644 source/arduino/randomseed.rst delete mode 100644 source/arduino/return.rst delete mode 100644 source/arduino/scope.rst delete mode 100644 source/arduino/semicolon.rst delete mode 100644 source/arduino/serial.rst delete mode 100644 source/arduino/setup.rst delete mode 100644 source/arduino/shiftout.rst delete mode 100644 source/arduino/sin.rst delete mode 100644 source/arduino/sizeof.rst delete mode 100644 source/arduino/sq.rst delete mode 100644 source/arduino/sqrt.rst delete mode 100644 source/arduino/static.rst delete mode 100644 source/arduino/string.rst delete mode 100644 source/arduino/stringclass.rst delete mode 100644 source/arduino/stringobject.rst delete mode 100644 source/arduino/switchcase.rst delete mode 100644 source/arduino/tan.rst delete mode 100644 source/arduino/tone.rst delete mode 100644 source/arduino/unsignedchar.rst delete mode 100644 source/arduino/unsignedint.rst delete mode 100644 source/arduino/unsignedlong.rst delete mode 100644 source/arduino/variables.rst delete mode 100644 source/arduino/void.rst delete mode 100644 source/arduino/volatile.rst delete mode 100644 source/arduino/while.rst delete mode 100644 source/arduino/word.rst delete mode 100644 source/arduino/wordcast.rst delete mode 100644 source/foo.rst create mode 100644 source/lang/abs.rst create mode 100644 source/lang/analogread.rst create mode 100644 source/lang/analogwrite.rst create mode 100644 source/lang/arithmetic.rst create mode 100644 source/lang/arithmeticcompound.rst create mode 100644 source/lang/array.rst create mode 100644 source/lang/assignment.rst create mode 100644 source/lang/attachinterrupt.rst create mode 100644 source/lang/bit.rst create mode 100644 source/lang/bitclear.rst create mode 100644 source/lang/bitread.rst create mode 100644 source/lang/bitset.rst create mode 100644 source/lang/bitshift.rst create mode 100644 source/lang/bitwisecompound.rst create mode 100644 source/lang/bitwisemath.rst create mode 100644 source/lang/bitwrite.rst create mode 100644 source/lang/boolean.rst create mode 100644 source/lang/booleanvariables.rst create mode 100644 source/lang/braces.rst create mode 100644 source/lang/break.rst create mode 100644 source/lang/byte.rst create mode 100644 source/lang/bytecast.rst create mode 100644 source/lang/cc-attribution.txt create mode 100644 source/lang/char.rst create mode 100644 source/lang/charcast.rst create mode 100644 source/lang/comments.rst create mode 100644 source/lang/comparison.rst create mode 100644 source/lang/const.rst create mode 100644 source/lang/constants.rst create mode 100644 source/lang/constrain.rst create mode 100644 source/lang/continue.rst create mode 100644 source/lang/cos.rst create mode 100644 source/lang/define.rst create mode 100644 source/lang/delay.rst create mode 100644 source/lang/delaymicroseconds.rst create mode 100644 source/lang/detachinterrupt.rst create mode 100644 source/lang/digitalread.rst create mode 100644 source/lang/digitalwrite.rst create mode 100644 source/lang/double.rst create mode 100644 source/lang/doublecast.rst create mode 100644 source/lang/dowhile.rst create mode 100644 source/lang/else.rst create mode 100644 source/lang/enum.rst create mode 100644 source/lang/float.rst create mode 100644 source/lang/floatcast.rst create mode 100644 source/lang/for.rst create mode 100644 source/lang/goto.rst create mode 100644 source/lang/highbyte.rst create mode 100644 source/lang/if.rst create mode 100644 source/lang/include.rst create mode 100644 source/lang/increment.rst create mode 100644 source/lang/int.rst create mode 100644 source/lang/intcast.rst create mode 100644 source/lang/interrupts.rst create mode 100644 source/lang/keywords.rst create mode 100644 source/lang/long.rst create mode 100644 source/lang/longcast.rst create mode 100644 source/lang/loop.rst create mode 100644 source/lang/lowbyte.rst create mode 100644 source/lang/map.rst create mode 100644 source/lang/max.rst create mode 100644 source/lang/micros.rst create mode 100644 source/lang/millis.rst create mode 100644 source/lang/min.rst create mode 100644 source/lang/modulo.rst create mode 100644 source/lang/nointerrupts.rst create mode 100644 source/lang/notone.rst create mode 100644 source/lang/pinmode.rst create mode 100644 source/lang/pointer.rst create mode 100644 source/lang/pow.rst create mode 100644 source/lang/pulsein.rst create mode 100644 source/lang/pwmwrite.rst create mode 100644 source/lang/random.rst create mode 100644 source/lang/randomseed.rst create mode 100644 source/lang/return.rst create mode 100644 source/lang/scope.rst create mode 100644 source/lang/semicolon.rst create mode 100644 source/lang/serial.rst create mode 100644 source/lang/serialusb.rst create mode 100644 source/lang/setup.rst create mode 100644 source/lang/shiftout.rst create mode 100644 source/lang/sin.rst create mode 100644 source/lang/sizeof.rst create mode 100644 source/lang/sq.rst create mode 100644 source/lang/sqrt.rst create mode 100644 source/lang/static.rst create mode 100644 source/lang/string.rst create mode 100644 source/lang/stringclass.rst create mode 100644 source/lang/stringobject.rst create mode 100644 source/lang/switchcase.rst create mode 100644 source/lang/tan.rst create mode 100644 source/lang/tone.rst create mode 100644 source/lang/types.rst create mode 100644 source/lang/unsignedchar.rst create mode 100644 source/lang/unsignedint.rst create mode 100644 source/lang/unsignedlong.rst create mode 100644 source/lang/variables.rst create mode 100644 source/lang/void.rst create mode 100644 source/lang/volatile.rst create mode 100644 source/lang/while.rst create mode 100644 source/language-index.rst delete mode 100644 source/wirish.rst delete mode 100644 source/wirish/pwmwrite.rst delete mode 100644 source/wirish/serialusb.rst delete mode 100644 source/wirish/types.rst diff --git a/source/arduino/abs.rst b/source/arduino/abs.rst deleted file mode 100644 index 0ec6b47..0000000 --- a/source/arduino/abs.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _arduino-abs: - -abs(x) -====== - -Description ------------ - -(Macro) computes the absolute value of a number. - -Parameters ----------- - -**x**: the number. - -Returns -------- - -**x**: if **x** is greater than or equal to 0. - -**-x**: if **x** is less than 0. - -Warning -------- - -Because of the way ``abs()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - abs(a++); // avoid this - yields incorrect results - - abs(a); // use this instead - - a++; // keep other operations outside abs() - - -Arduino Compatibility ---------------------- - -Maple's implementation of ``abs()`` is compatible with Arduino. - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/analogread.rst b/source/arduino/analogread.rst deleted file mode 100644 index cd18567..0000000 --- a/source/arduino/analogread.rst +++ /dev/null @@ -1,152 +0,0 @@ -.. highlight:: cpp - -.. _arduino-analogread: - -analogRead() -============ - -Used to perform ADC conversion. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: analogRead - -Discussion ----------- - -Reads the value from the specified analog pin. The Maple board -contains a 16-channel, 12-bit analog to digital converter. This means -that it will map input voltages between 0 and 3.3 volts into integer -values between 0 and 4095. This yields a resolution between readings -of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors -interfere with getting full accuracy and precision. For more -information, see :ref:`adc`. - -Before calling analogRead() on a pin, that pin must first be -configured for analog input, using :ref:`arduino-pinMode` (you only -have to do this once, so it's usually done in :ref:`arduino-setup`\ ). - -It takes about 0.8 microseconds (.0000008 seconds) to read an analog -input, so the maximum sample rate using this function is approximately -1.3 million samples per second\ [#fsamp]_. - - -Parameter Discussion --------------------- - -The pin parameter is the number of the analog input pin to read from. -Header pins on the Maple with ADC functionality (marked as "AIN" on -the silkscreen) are: - - 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 - -Note that pins 3, 27, and 28 are not marked AIN on the silkscreen -for Maple revisions through Rev 5, however, they **do work** as -analog input pins. - -Note ----- - -If the analog input pin is not connected to anything, the value -returned by analogRead() will fluctuate based on a number of factors -(e.g. the values of the other analog inputs, how close your hand is to -the board, etc.) in a seemingly random way. - - -Example -------- - - :: - - - int analogPin = 3; // potentiometer wiper (middle terminal) connected - // to analog pin 3. outside leads to ground and +3.3V - int val = 0; // variable to store the value read - - void setup() { - pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input - SerialUSB.begin(); // set up usb virtual COM port - } - - void loop() { - val = analogRead(analogPin); // read the input pin - SerialUSB.println(val); // print the value, for debugging with - // a serial monitor - } - - -Arduino Compatibility ---------------------- - -The Arduino board contains a 6 channel (8 channels on the Mini and -Nano, 16 on the Mega), 10-bit analog to digital converter with an -input voltage range of 0V--5V. This means that it will map input -voltages between 0 and 5 volts (which is **larger** than Maple's range -of 0V-3.3V) into integer values between 0 and 1023 (which is -**smaller** than the Maple's range of 0--4095). - -This yields a theoretical resolution between readings of: 5 volts / -1024 units or .0049 volts (4.9 mV) per unit on Arduino boards, which -is larger, and thus less precise, than Maple's 0.0008 volts (0.8 mV). - -If your program expects Arduino-style 10-bit ADC, you can :ref:`right -shift ` the value of a Maple readout by 2, like so:: - - // right shift means that the result will be between 0 and 1023; - // be aware that you're losing a lot of precision if you do this - int adc_reading = analogRead(pin) >> 2; - -On the Arduino, the input range and resolution can be changed using -their implementation of `analogReference() -`_\ . Because of the -way its hardware (as of Rev 5) was designed, it's not possible to -implement analogReference on the Maple, so this function doesn't -exist. If your inputs lie in a different voltage range than 0V--3.3V, -you'll need to bring them into that range before using analogRead. -Some basic tools to accomplish this are `resistor dividers -`_ and `Zener diodes -`_\ -. However, opamps and other powered components can also be used if -greater precision is required. - -Finally, On the Arduino, it takes significantly longer to read analog -input: about 100 microseconds (0.0001 s), so the maximum reading rate -is 10,000 times a second. - - -See also --------- - -- :ref:`ADC note ` -- `(Arduino) Tutorial: Analog Input Pins `_ - - -.. rubric:: Footnotes - -.. [#fsamp] This is based on the current configuration of a 55.5 cycle - sample time, at 72 MHz. However, the minimum sample time *possible* - is 1.5 cycles, leading to a theoretical maximum of approximately 48 - million samples per second (of course, doing anything with the - readings also consumes cycles, so this maximum can't be reached in - practice). - - See the `STM32 Reference Manual `_, §§11.12.4--5 - (pp. 225--226), for more information on the low-level bit twiddling - currently necessary to change the sample time. For examples of how - the ADCs are configured in libmaple, see `adc.h - `_ - and `adc.c - `_\ - . Be aware that changing the sample time has important - consequences related to the impedance of the device connected to - the input pin. If you want to make changes, as a minimum, you - should first read ST's application notes on `ADC modes - `_ and `ADC oversampling - `_. - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/analogwrite.rst b/source/arduino/analogwrite.rst deleted file mode 100644 index a1057ab..0000000 --- a/source/arduino/analogwrite.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. highlight:: cpp - -.. _arduino-analogwrite: - -analogWrite() -============= - -.. note:: - - On the Maple, calling analogWrite() is the same as calling - :ref:`wirish-pwmwrite`\ ; see that function's documentation for more - information. - - This is because PWM is not true analog output (i.e., is not the - output of a `DAC - `_\ ), so - the function is badly named. For instance, **analogWrite() has - absolutely nothing to do with** :ref:`arduino-analogread`\ , which - is potentially confusing. - - The alias of analogWrite() to pwmWrite() is provided (sigh) for the - sake of compatibility with Arduino, but we recommend using - :ref:`wirish-pwmwrite` when writing new software, for clarity. - -.. contents:: Contents - :local: - -Arduino Compatibility ---------------------- - -There are a few important differences between Arduino's `analogWrite() -`_ and Maple's -:ref:`wirish-pwmwrite` that you should keep in mind. In each case, we -have some recommendations you can use to help converting from Arduino -to Maple. - -Difference 1: Duty cycle range is different -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The first and most important difference is that the largest possible -value for the duty cycle is much bigger on the Maple. Using Arduino's -analogWrite(), the duty cycle ranges between 0--255 (always off -- -always on)\ [#fbytemax]_\ . Using Maple's pwmWrite(), the duty cycle -ranges from 0--65,535 by default\ [#fuint16max]_\ . - -This is a good thing! The greater range of values on the Maple gives -you much more precise control over the duty cycle of your PWM output. - -If you're porting code from the Arduino and want a quick-and-dirty -fix, one solution is to :ref:`map ` the argument to -analogWrite into the right range:: - - // Arduino code: - analogWrite(pin, duty); - - // Becomes Maple code: - analogWrite(pin, map(duty, 0, 255, 0, 65535)); - -This will convert values in the range 0-255 to values in the range -0--65,635, which is the correct default range for all of the timers -which control PWM output. See the :ref:`timers reference ` -for more information. - -Another fix is to consult the :ref:`pin mapping mega table -` to find the timer which controls PWM on the -pin you're using, then set that Timer's overflow to 255. Subsequent -calls to analogWrite() should work as on the Arduino (with the same -loss of precision). Note, however, that that affects the overflow for -the **entire timer**, so other code relying on that timer (such as any -:ref:`interrupts ` the timer controls) will -likely need to be modified as well. - -Difference 2: You must use pinMode() to set up PWM -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The second difference is that on the Maple, you **must** set up the pin -for PWM output using :ref:`arduino-pinmode`\ , with argument ``PWM``. -This should just be one extra line of code in your -:ref:`arduino-setup` function. Example:: - - void setup() { - // set up pin 9 for PWM - pinMode(9, PWM); - } - -This also means that you can't later call :ref:`arduino-digitalread` -or :ref:`arduino-digitalwrite` on that pin (unless some time in -between, you use pinMode() to reconfigure that pin for ``INPUT`` or -``OUTPUT``; see the :ref:`arduino-pinmode` page for more information). - -Difference 3: No PWM on pin 10 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, -9, 11, 12, and 14, or twelve pins in total. That is at least as -*many* PWM pins as any Arduino board, but there are differences in -*which* pins support it. - -* On **most Arduino boards** (those with the ATmega168 or ATmega328; - this includes the **Arduino Uno**), this function works on pins 3, - 5, 6, 9, 10, and 11, or six pins total. Note that these boards - support PWM on pin 10, while Maple does not. - -* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins - total. Note that this board supports PWM on pins 4, 10, and 13, - while the Maple does not. Maple supports PWM on pins 0, 1, and 14, - which the Mega does not, making the total number of pins supporting - PWM equal on these boards. - -* **Older Arduino boards** with an ATmega8 only support analogWrite() on - pins 9, 10, and 11. Maple does not support PWM on pin 10. - -In all cases, Arduino boards support PWM on pin 10, unlike Maple. We -did our best to make PWM as pin-compatible as possible; however, -circuit layout constraints prevented us from achieving perfect -compatibility. - -The "safest" pins to use for PWM output are pins 9 and 11. These pins -work on any Arduino board and on Maple. The "safe" pins, which work -on most recent Arduino boards, the Arduino Mega and the Maple, are -pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as -portable as possible between Maple and Arduino, we recommend using the -"safest" pins first, then the "safe" pins, as necessary. - -Difference 4: PWM frequency -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The frequency of the PWM signal (i.e., the frequency of a complete -on/off cycle) on the Arduino is approximately 490 Hz. - -On the Maple, the frequency is configurable, defaulting to about 1100 -Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of -the timer which controls PWM output on the particular pin (\ -:ref:`the PWM tutorial has the details `\ ). - -If your application absolutely requires Arduino's PWM frequency (it -probably doesn't), then the steps are: - -1. Figure out which timer controls PWM output on your pin (\ :ref:`this table ` is your friend here). Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4. - -2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of approximately 490 Hz. - -Be aware that this will change the period for the **entire timer**\ , -and will affect anything else in your program that depends on that -timer. One example is :ref:`interrupts `\ . -You've been :ref:`warned `\ . - -See also --------- - -- :ref:`Maple PWM tutorial ` - -.. rubric:: Footnotes - -.. [#fbytemax] This is because the value for the duty cycle on Arduino - must fit in 1 byte of memory, and an unsigned (i.e., nonnegative) - integer with size 1 byte can hold the values between 0 and 255. - -.. [#fuint16max] This is because the value for the duty cycle on the - Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) - integer with size 2 bytes can hold the values between 0 and 65,535. - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/arithmetic.rst b/source/arduino/arithmetic.rst deleted file mode 100644 index 69cf166..0000000 --- a/source/arduino/arithmetic.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. highlight:: cpp - -.. _arduino-arithmetic: - -Addition, Subtraction, Multiplication, & Division -================================================= - -.. contents:: Contents - :local: - -Description ------------ - -These operators return the sum, difference, product, or quotient -(respectively) of the two operands. The operation is conducted using -the data type of the operands, so, for example, ``9 / 4`` gives ``2`` -since 9 and 4 are :ref:`int variables `. - -This also means that the operation can overflow if the result is -larger than that which can be stored in the data type (e.g. adding 1 -to an :ref:`arduino-int` with the value 2147483647 gives --2147483648). If the operands are of different types, the "larger" -type is used for the calculation. - -.. _arduino-arithmetic-typeconversion: - -.. note:: The specifics of these rules are beyond the scope of this - documentation; for more information, see `The C++ Programming - Language `_\ , by Bjarne - Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks - entry on C++ type conversion - `_. - -.. note:: For more information on how computers represent integers, - see the Wikipedia page on `two's complement - `_. - -If one of the numbers (operands) are of the type **float** or of type -**double**, floating point math will be used for the -calculation. - -Examples --------- - - :: - - y = y + 3; - x = x - 7; - i = j * 6; - r = r / 5; - - -Syntax ------- - - :: - - result = value1 + value2; - result = value1 - value2; - result = value1 * value2; - result = value1 / value2; - - -Parameters ----------- - -**value1**: any numeric variable or constant - -**value2**: any numeric variable or constant - -Programming Tips ----------------- - -- Know that :ref:`integer constants ` - default to :ref:`int `, so some constant calculations - may overflow (e.g., 200000 * 5000000 will yield a negative result). - -- Choose variable sizes that are large enough to hold the largest - results from your calculations. - -- Know at what point your variable will "roll over" and also what - happens in the other direction e.g. (0 - 1) for unsigned arithmetic, - or (0 - -2,147,483,648) for signed arithmetic. - -- For math that requires fractions, float variables may be used, but - be aware of their drawbacks: large size and slow computation speeds - (the STM32 has no floating point hardware, so all floating point - calculations have to be done in software). - -- Use cast operator, e.g. ``(int)myFloat`` to convert one variable type - to another on the fly. - -Arduino Compatibility ---------------------- - -Since the STM32 processor on the Maple is a 32-bit machine, the int -type overflows at a much higher value on Maple than on Arduino. In -particular, on Maple, ints do not overflow (become negative) until -they reach 2,147,483,648; on the Arduino, they overflow at 32,767. -Because of this, programs running on Maple are much less likely to run -into overflow issues. The following table summarizes the sizes and -ranges of integer datatypes on the Maple (the ranges of long long -types are approximate): - -.. _arduino-arithmetic-int-sizes: - -.. csv-table:: - :header: Datatype, Unsigned range, Signed range, Size (bytes) - :widths: 8, 12, 17, 8 - - ``char``, 0 --- 255, -128 --- 127, 1 - ``short``, "0 --- 65,535", "-32,768 --- 32,767", 2 - ``int``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 - ``long``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 - ``long long``, "0 --- 1.8*10\ :sup:`19`\ " (approx.), "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 - - -See Also --------- - -- The individual sizes (in bits) of various available types are - defined in `libmaple_types.h - `_\ - . - -- :ref:`sizeof `\ () - - -.. include:: cc-attribution.txt diff --git a/source/arduino/arithmeticcompound.rst b/source/arduino/arithmeticcompound.rst deleted file mode 100644 index 734ef9d..0000000 --- a/source/arduino/arithmeticcompound.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. highlight:: cpp - -.. _arduino-arithmeticcompound: - -Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) -=============================================================== - -Description ------------ - -Perform a mathematical operation on a variable with another constant -or variable. These operators are just a convenient shorthand:: - - x += y; // equivalent to the expression x = x + y; - x -= y; // equivalent to the expression x = x - y; - x *= y; // equivalent to the expression x = x * y; - x /= y; // equivalent to the expression x = x / y; - -Here is an example:: - - int x = 2; - int y = 10; - - x += 4; // x now contains 6 - x -= 3; // x now contains 3 - x *= y; // x now contains 30 - x /= 2; // x now contains 15 - x += max(20, 6); // x now contains 35 - x -= sq(5); // x now contains 15 - -Parameters ----------- - -**x**: a numeric variable - -**y**: a numeric variable, number constant, or any other expression -that evaluates to a number (e.g. call to a function that returns a -number). - -See Also --------- - -- :ref:`Arithmetic operators ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/array.rst b/source/arduino/array.rst deleted file mode 100644 index e49cc18..0000000 --- a/source/arduino/array.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. highlight:: cpp - -.. _arduino-array: - -Arrays -====== - -An array is a collection of variables that are accessed with an index -number. Arrays in the C++ programming language, in which the Maple is -programmed, can be complicated, but using simple arrays is relatively -straightforward. - -.. contents:: Contents - :local: - -Creating (Declaring) an Array ------------------------------ - -All of the methods below are valid ways to create (declare) an -array. :: - - int myInts[6]; - int myPins[] = {2, 4, 8, 3, 6}; - int mySensVals[6] = {2, 4, -8, 3, 2}; - char message[6] = "hello"; - -You can declare an array without initializing it, as with myInts. In -the line referring to myPins, we declare an array without explicitly -choosing a size. The compiler counts the elements and creates an -array of the appropriate size. - -Finally, you can both initialize and size your array, as in -mySensVals. Note that when declaring an array with elements of type -char, one more element than your initialization is required, to hold -the required `null character `_. - - -Accessing an Array ------------------- - - -.. compound:: - - Arrays are **zero indexed**; that is, referring to the array - initialization above, the first element of the array is at index 0, - hence :: - - mySensVals[0] == 2; - mySensVals[1] == 4 - - and so forth. - -It also means that in an array with ten elements, index nine is the -last element. Hence:: - - int myArray[10]={9,3,2,4,3,2,7,8,9,11}; - // myArray[9] contains 11 - // myArray[10] is invalid and contains random information (other memory address) - -For this reason, you should be careful in accessing arrays. Accessing -past the end of an array (using an index number greater than your -declared array size - 1) is reading from memory that is in use for -other purposes. Reading from these locations is probably not going to -do much except yield invalid data. Writing to random memory locations -is definitely a bad idea, and can often lead to unhappy results such -as crashes or program malfunction. This can also be a difficult bug to -track down. - -Unlike Basic or Java, the C compiler does no checking to see if array -access is within legal bounds of the array size that you have -declared. - - -To assign a value to an array ------------------------------ - :: - - mySensVals[0] = 10; - - -To retrieve a value from an array ---------------------------------- - - :: - - x = mySensVals[4]; - - -Arrays and ``for`` Loops ------------------------- - -Arrays are often manipulated inside :ref:`for loops `, where -the loop counter is used as the index for each array element. For -example, to print the elements of an array over the serial port, you -could do something like this:: - - int i; - for (i = 0; i < 5; i = i + 1) { - SerialUSB.println(myPins[i]); - } - - -Example -------- - -For a complete program that demonstrates the use of arrays, see the -Arduino `Knight Rider example -`_\ (which will run -unmodified on the Maple). - -Arduino Compatibility ---------------------- - -Arrays on Maple are identical those on Arduino. - -See also --------- - -- :ref:`Storing arrays in FLASH memory ` - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/assignment.rst b/source/arduino/assignment.rst deleted file mode 100644 index 4907473..0000000 --- a/source/arduino/assignment.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. highlight:: cpp - -.. _arduino-assignment: - -= assignment operator (single equal sign) -========================================= - -Stores the value to the right of the equal sign in the variable to -the left of the equal sign. - -The single equal sign in the C++ programming language is called the -assignment operator. It has a different meaning than in algebra -class, where it indicated an equation or equality. The assignment -operator tells the microcontroller to evaluate whatever value or -expression is on the right side of the equal sign, and store it in -the variable to the left of the equal sign [#fgross]_. - - - -Example -------- - -:: - - int sensVal; // declare an integer variable named sensVal - senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal - - - -Programming Tips ----------------- - -The variable on the left side of the assignment operator ( = sign ) -needs to be able to hold the value stored in it. If it is not large -enough to hold a value, the value stored in the variable will be -incorrect. - -Don't confuse the assignment operator [ = ] (single equal sign) -with the comparison operator [ == ] (double equal signs), which -evaluates whether two expressions are equal. - - -Arduino Compatibility ---------------------- - -Assignments on the Maple are identical to those on Arduino. - - - -See Also --------- - - -- `if (comparison operators) `_ -- `char `_ -- `int `_ -- `long `_ - - -.. rubric:: Footnotes - -.. [#fgross] Experienced C++ programmers know this to be an - oversimplification of what happens when the variable on the left - hand side is an object. See Richard Gillam's wonderful and scary - `The Anatomy of the Assignment Operator - `_ - for more information. - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/attachinterrupt.rst b/source/arduino/attachinterrupt.rst deleted file mode 100644 index 3714709..0000000 --- a/source/arduino/attachinterrupt.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. highlight:: cpp - -.. _arduino-attachinterrupt: - -attachInterrupt() -================= - -Used to specify a function to call when an external interrupt (like an -GPIO changing from LOW to HIGH, a button getting pressed, etc.) -occurs. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: attachInterrupt - -.. doxygenenum:: ExtIntTriggerMode - -.. doxygentypedef:: voidFuncPtr - -Discussion ----------- - -Because the function will run in interrupt context, inside of it, -:ref:`arduino-delay` won't work, and the value returned by -:ref:`arduino-millis` will not increment. Serial data received while -in the function may be lost. You should declare as ``volatile`` any -global variables that you modify within the attached function. - -There are a few constraints you should be aware of if you're using -more than one interrupt at a time; the :ref:`external-interrupts` page -has the details. - - -Using Interrupts ----------------- - -Interrupts are useful for making things happen automatically in -microcontroller programs, and can help solve timing problems. A -good task for using an interrupt might be reading a rotary encoder, -or monitoring user input. - - -If you wanted to insure that a program always caught the pulses -from a rotary encoder, never missing a pulse, it would make it very -tricky to write a program to do anything else, because the program -would need to constantly poll the sensor lines for the encoder, in -order to catch pulses when they occurred. Other sensors have a -similar interface dynamic too, such as trying to read a sound -sensor that is trying to catch a click, or an infrared slot sensor -(photo-interrupter) trying to catch a coin drop. In all of these -situations, using an interrupt can free the microcontroller to get -some other work done while not missing the doorbell. - - -Example -------- - -:: - - int maple_led_pin = 13; - volatile int state = LOW; // must declare volatile, since it's - // modified within the blink handler - - void setup() { - pinMode(maple_led_pin, OUTPUT); - attachInterrupt(0, blink, CHANGE); - } - - void loop() { - digitalWrite(maple_led_pin, state); - } - - void blink() { - state = !state; - } - - -Arduino Compatibility ---------------------- - -Most Arduino boards have two external interrupts: numbers 0 (on -digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an -additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 -(pin 18). On the Maple, you don't have to remember which interrupt -number goes with which pin -- just tell ``attachInterrupt()`` the pin -you want. - - -See also --------- - - -- :ref:`detachInterrupt ` -- :ref:`external-interrupts` - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bit.rst b/source/arduino/bit.rst deleted file mode 100644 index f25236c..0000000 --- a/source/arduino/bit.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _arduino-bit: - -bit() -===== - -Description ------------ - -(Macro) Computes the value of an (unsigned) integer with the specified -bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8, -16, 32, etc.). - - -Syntax ------- - -``bit(n)`` - - -Parameters ----------- - -* **n** the bit to set. - - -Value ------ - -The value of an integer with the given bit set. - - -Arduino Compatibility ---------------------- - -The Maple implementation of bit is compatible with Arduino. - - -See also --------- - - -- :ref:`arduino-bitread` -- :ref:`arduino-bitwrite` -- :ref:`arduino-bitset` -- :ref:`arduino-bitclear` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitclear.rst b/source/arduino/bitclear.rst deleted file mode 100644 index 14261a6..0000000 --- a/source/arduino/bitclear.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _arduino-bitclear: - -bitClear() -========== - -Description ------------ - -(Macro) Clears (writes a 0 to) a bit of a numeric variable. - -Syntax ------- - -``bitClear(x, n)`` - - -Parameters ----------- - -* **x** the numeric variable whose bit to clear - -* **n** which bit to clear, starting at 0 for the least-significant - (rightmost) bit - - -Returns -------- - -None. - - -Arduino Compatibility ---------------------- - -This implementation is compatible with that of Arduino. - - -See also --------- - -- :ref:`bit `\ () -- :ref:`bitRead `\ () -- :ref:`bitWrite `\ () -- :ref:`bitSet `\ () - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitread.rst b/source/arduino/bitread.rst deleted file mode 100644 index f2cb037..0000000 --- a/source/arduino/bitread.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _arduino-bitread: - -bitRead() -========= - -Description ------------ - -(Macro) Gets the value of a bit in a number. - - -Syntax ------- - -``bitRead(x, n)`` - - -Parameters ----------- - -* **x** the number from which to read the bit. - -* **n** which bit to read, starting at 0 for the least-significant - (rightmost) bit - - -Value ------ - -The value of the bit (0 or 1). - - -Arduino Compatibility ---------------------- - -The Maple implementation of ``bitRead`` is compatible with Arduino. - - -See also --------- - - -- :ref:`arduino-bit` -- :ref:`arduino-bitwrite` -- :ref:`arduino-bitset` -- :ref:`arduino-bitclear` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitset.rst b/source/arduino/bitset.rst deleted file mode 100644 index b6964a0..0000000 --- a/source/arduino/bitset.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _arduino-bitset: - -bitSet() -======== - -Description ------------ - -(Macro) Sets (writes a 1 to) a bit of a numeric variable. - - -Syntax ------- - -``bitSet(x, n)`` - - -Parameters ----------- - -* **x** the numeric variable whose bit to set - -* **n** which bit to set, starting at 0 for the least-significant - (rightmost) bit - - -Value ------ - -None. - - -Arduino Compatibility ---------------------- - -The Maple implementation of bitSet is compatible with Arduino. - - -See Also --------- - -- :ref:`arduino-bit` -- :ref:`arduino-bitread` -- :ref:`arduino-bitwrite` -- :ref:`arduino-bitclear` - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitshift.rst b/source/arduino/bitshift.rst deleted file mode 100644 index 00c466f..0000000 --- a/source/arduino/bitshift.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. highlight:: cpp - -.. _arduino-bitshift: - -Bit shift left (``<<``), bit shift right (``>>``) -================================================= - -Description ------------ - -(Adapted from `The Bit Math Tutorial -`_ in `The Arduino -Playground `_\ ) - - -There are two bit shift operators in C++: the left shift operator -``<<`` and the right shift operator ``>>``. These operators cause the -bits in the left operand to be shifted left or right by the number of -positions specified by the right operand. - -More information on bitwise math can be obtained in the Wikipedia -article on `bitwise operations -`_\ , especially the -section on shifts in `C, C++, and Java -`_\ . - - -Syntax ------- - -``some_int << number_of_bits`` - -``some_int >> number_of_bits`` - - -Parameters ----------- - -* **some_int** An integer value or variable. - -* **number_of_bits** integer whose value is at most ``8 * - sizeof(variable)`` (so ``number_of_bits`` can be at most 32 for - ``int`` values, at most ``8`` for ``char`` values, etc.; the various - integer sizes are summarized :ref:`in this table - `\ ). - - - -Example: --------- - -Here are some examples of bit shifting, with the binary representation of the number in comments:: - - int a = 5; // binary: 101 - int b = a << 3; // binary: 101000, or 40 in decimal - int c = b >> 3; // binary: 101, or back to 5 like we started with - - -When you left shift a value x by y bits (x << y), the leftmost y bits -in x are lost, literally shifted out of existence. We'll do this -example with ``char`` values (which are integers in the range 0-255, -and take up 8 bits of memory):: - - char a = 5; // binary (all 8 bits): 00000101 - char b = a << 7; // binary: 10000000 - the first 1 in 101 was discarded - - -If you are certain that none of the ones in a value are being shifted -into oblivion, a simple way to think of the left-shift operator is -that it multiplies the left operand by 2 raised to the right operand -power (in math notation, ``x << y`` equals x * 2\ :sup:`y`\ , as long -as none of the bits of x get shifted out). For example, to generate -powers of 2, the following expressions can be employed:: - - 1 << 0 == 1 - 1 << 1 == 2 - 1 << 2 == 4 - 1 << 3 == 8 - ... - 1 << 8 == 256 - 1 << 9 == 512 - 1 << 10 == 1024 - ... - -.. _arduino-bitshift-signbit-gotcha: - -When you shift x right by y bits (``x >> y``), and the highest bit in -x is a 1, the behavior depends on the exact data type of x. If x is of -type ``int``, the highest bit is special, and determines whether x is -negative or not; the details are too complicated to explain here, but -they are thoroughly explained in the Wikipedia article on `two's -complement arithmetic -`_\ , which the -system most computers use to store integers. In that case, the sign -bit is copied into lower bits, for esoteric historical reasons:: - - int x = -16; // binary (all 32 bits): 11111111111111111111111111110000 - int y = x >> 3; // binary: 11111111111111111111111111111110 - - - -This behavior, called "sign extension", is often not what you -want. You probably wish zeros to be shifted in from the left. It -turns out that the right shift rules are different for ``unsigned -int`` values, so you can use a type cast to suppress ones being copied -from the left:: - - int x = -16; // binary: 11111111111111111111111111110000 - int y = (unsigned int)x >> 3; // binary: 00011111111111111111111111111110 - - - -If you are careful to avoid sign extension, you can use the -right-shift operator, ``>>``, as a way to divide by powers of 2. For -example:: - - int x = 1000; - int y = x >> 3; // integer division of 1000 by 8, causing y = 125. - - -Arduino Compatibility ---------------------- - -Since it's part of the C++ language, bit shifting on the Maple is -compatible with the Arduino; however, you should keep in mind that the -Maple has bigger integer types (as in, more bits) than the Arduino. - -Since the STM32 is a 32-bit processor, the ``int`` type takes up 32 -bits instead of 16, like on Arduino's 16-bit microcontroller. This -means that you can shift left, like ``x << y``, with bigger values of -``y`` on the Maple before ones in ``x`` start to get shifted out. - -To calculate the number of bits of an integer type on the Maple, -multiply its size in bytes (see :ref:`this table -` for these) by 8, since there are 8 -bits in 1 byte. For example, a ``short`` takes up 2 bytes of memory, -or 2 * 8 = 16 bits. - -See Also --------- - -- :ref:`arduino-bit` -- :ref:`arduino-bitread` -- :ref:`arduino-bitwrite` -- :ref:`arduino-bitclear` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitwisecompound.rst b/source/arduino/bitwisecompound.rst deleted file mode 100644 index 92f3fdd..0000000 --- a/source/arduino/bitwisecompound.rst +++ /dev/null @@ -1,231 +0,0 @@ -.. highlight:: cpp - -.. _arduino-bitwisecompound: - -Compound bitwise and (&=), or (\|=), XOR (^=) -============================================= - -The compound bitwise operators perform their calculations at the -bit level of variables. They are often used to clear and set -specific bits of a variable. - -See the :ref:`bitwise math tutorial ` for more -information on bitwise operators. - -.. contents:: Contents - :local: - -.. _arduino-bitwisecompound-and: - -Compound bitwise AND (&=) -------------------------- - -The compound bitwise AND operator ``&=`` is often used with a variable -and a constant to force particular bits in a variable to be zero. This -is often referred to in programming guides as "clearing" or -"resetting" bits. In a program, writing the line ``x &= y;`` is -equivalent to writing ``x = x & y;``. That is, the value of ``x`` -after the line will be equal to its old value bitwise ANDed with the -value of ``y``:: - - x &= y; // equivalent to x = x & y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any :ref:`integer value -` (like ``3`` or ``0x20``) for ``y``. - -Before doing an example of ``&=``, let's first review the Bitwise AND -(``&``) operator:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 0 0 1 (operand1 & operand2) = result - -As shown above, bits that are "bitwise ANDed" with 0 become 0, while -bits that are "bitwise ANDed" with 1 are left unchanged. So, if ``b`` -is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b & -B11111111`` equals ``b``. - -.. _arduino-bitwisecompound-binconst: - -.. note:: The above uses :ref:`binary constants - `\ . The numbers are still the same - value in other representations, they just might not be as easy to - understand. - - Normally, in C and C++ code, :ref:`hexadecimal - ` or :ref:`octal - ` are used when we're interested in - an integer's bits, rather than its value as a number. - - While hexadecimal and octal literals might be harder to understand - at first, you should really take the time to learn them. They're - part of C, C++, and many other programming languages, while binary - constants are available only for compatibility with Arduino. - - Also, ``B00000000`` is shown for clarity, but zero in any number - format is zero. - -So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while -leaving the rest of the variable's bits unchanged, use the compound -bitwise AND operator ``&=`` with the constant ``B11111100`` -(hexadecimal ``0xFC``\ ):: - - 1 0 1 0 1 0 1 0 variable - 1 1 1 1 1 1 0 0 mask - ---------------------- - 1 0 1 0 1 0 0 0 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged cleared - - -Here is the same representation with the variable's bits replaced -with the symbol ``x``\ :: - - x x x x x x x x variable - 1 1 1 1 1 1 0 0 mask - ---------------------- - x x x x x x 0 0 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged cleared - - -So, using a byte variable ``b``\ , if we say:: - - b = B10101010; // B10101010 == 0xAA - b &= B11111100; // B11111100 == 0xFC - -then we will have :: - - b == B10101000; // B10101000 == 0xA8 - -.. _arduino-bitwisecompound-or: - -Compound bitwise OR (\|=) -------------------------- - -The compound bitwise OR operator ``|=`` is often used with a variable -and a constant to "set" (set to 1) particular bits in a variable. In -a program, writing the line ``x |= y;`` is equivalent to writing ``x = -x | y;``. That is, the value of ``x`` after the line will be equal to -its old value bitwise ORed with the value of ``y``:: - - x |= y; // equivalent to x = x | y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`compound bitwise AND -`\ , ``&=``). - -Before doing an example of ``|=``, let's first review the Bitwise OR -(``|``) operator:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) = result - -Bits that are "bitwise ORed" with 0 are unchanged, while bits that are -"bitwise ORed" with 1 are set to 1. So if ``b`` is a ``byte`` -variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111`` -equals ``B11111111`` (here we've used binary constants; see the -:ref:`note ` above). - -So, to set bits 0 and 1 of a one-byte variable, while leaving the rest -of the variable unchanged, use the compound bitwise OR operator -(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``):: - - 1 0 1 0 1 0 1 0 variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - 1 0 1 0 1 0 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged set - -Here is the same representation with the variable's bits replaced with -the symbol ``x``:: - - x x x x x x x x variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - x x x x x x 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged set - -So, using a byte variable ``b``, if we say:: - - b = B10101010; // B10101010 == 0xAA - b |= B00000011; // B00000011 == 0x3 - -then we will have :: - - b == B10101011; // B10101011 == 0xAB - -.. _arduino-bitwisecompound-xor: - -Compound bitwise XOR (\^=) --------------------------- - -The compound bitwise XOR operator ``^=`` is used with a variable and a -constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a -variable. In a program, writing the line ``x ^= y;`` is equivalent to -writing ``x = x ^ y;``. That is, the value of ``x`` after the line -will be equal to its old value bitwise XORed with the value of ``y``:: - - x ^= y; // equivalent to x = x ^ y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`&= -` and :ref:`\|= -`; in fact, these three operators all -work the same in this way). - -Before doing an example of ``^=``, let's first review the Bitwise -XOR operator, ``^``:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 0 (operand1 ^ operand2) = result - -One way to look at bitwise XOR is that each bit in the result is a 1 -if the input bits are different, or 0 if they are the same. Another -way to think about it is that the result bit will be 1 when *exactly* -one (no more, no less) of the input bits is 1; otherwise, it will be -zero. This means that if you XOR a bit with 1, it will change (or -toggle) its value, while if you XOR a bit with 0, it stays the same. - -So, to toggle bits 0 and 1 of a one-byte variable, while leaving the -rest of the variable unchanged, use the compound bitwise XOR operator -``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see -:ref:`note ` above):: - - 1 0 1 0 1 0 1 0 variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - 1 0 1 0 1 0 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged toggled - -So, using a byte variable ``b``, if we say:: - - b = B10101010; // B10101010 == 0xAA - b ^= B00000011; // B00000011 == 0x3 - -then we will have :: - - b == B10101001; // B10101001 == 0xA9 - -See Also --------- - -- :ref:`Boolean operations ` (``&&``, ``||``) -- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bitwisemath.rst b/source/arduino/bitwisemath.rst deleted file mode 100644 index 40c3d7a..0000000 --- a/source/arduino/bitwisemath.rst +++ /dev/null @@ -1,186 +0,0 @@ -.. highlight:: cpp - -.. _arduino-bitwisemath: - -Bitwise AND (&), OR (\|), XOR (^), NOT (~) -========================================== - -The bitwise operators perform their calculations at the bit level of -variables. They help solve a wide range of common programming -problems. - -Much of the material here is adapted for Maple from an (Arduino) -`tutorial on bitwise math -`_\ . Another great -resource is the Wikipedia article on `bitwise operations -`_\ . - -Below are descriptions and syntax for all of the operators. - -.. contents:: Contents - :local: - -.. _arduino-bitwisemath-and: - -Bitwise AND (&) ---------------- - -The bitwise AND operator in C++ is a single ampersand, ``&``, used -between two other integer expressions. Bitwise AND operates on each -bit position of the surrounding expressions independently, according -to this rule: if both input bits are 1, the resulting output is 1, -otherwise the output is 0. Another way of expressing this is:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 0 0 1 (operand1 & operand2) = result - - -On the Maple, the type ``int`` is a 32-bit value, so using ``&`` -between two ``int`` expressions causes 32 simultaneous AND operations -to occur. In a code fragment like:: - - int a = 92; // in binary: 00000000000000000000000001011100 - int b = 101; // in binary: 00000000000000000000000001100101 - int c = a & b; // result: 00000000000000000000000001000100, - // (or 68 in decimal). - - -Each of the 32 bits in ``a`` and ``b`` are processed using bitwise -AND, and all 32 resulting bits are stored in ``c``, resulting in the -value 1000100 in binary, which is 68 in decimal. - - -.. _arduino-bitwisemath-or: - -Bitwise OR (\|) ---------------- - -The bitwise OR operator in C++ is the vertical bar symbol, ``|``. Like -the ``&`` operator, ``|`` operates independently on each bit in its -two surrounding integer expressions, but what it does is -different. The bitwise OR of two bits is 1 if either or both of the -input bits is 1, otherwise it is 0. For example:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) = result - -Here is an example of bitwise OR used in a snippet of C++ code (using -``char``, which takes up 8 bits of memory, instead of ``int``, which -uses 32):: - - char a = 92; // in binary: 01011100 - char b = 101; // in binary: 01100101 - char c = a | b; // result: 01111101, or 125 in decimal. - -.. _arduino-bitwisemath-xor: - -Bitwise XOR (^) ---------------- - -There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE -OR, also known as bitwise XOR. (In English, this is usually pronounced -"zor" or "ex-or"). The bitwise XOR operator is written using the caret -symbol, ``^``. This operator is very similar to the bitwise OR -operator ``|``, except it evaluates to 0 for a given bit position when -both of the input bits for that position are 1:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 0 (operand1 ^ operand2) = result - - -Another way to look at bitwise XOR is that each bit in the result -is a 1 if the input bits are different, or 0 if they are the same. - -Here is a simple example:: - - int x = 12; // binary (ignoring extra bits): 1100 - int y = 10; // binary: 1010 - int z = x ^ y; // binary: 0110, or decimal 6 - - - -The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 -to 0) some of the bits in an integer expression. In a bitwise OR -operation if there is a 1 in the mask bit, that bit is inverted; if -there is a 0, the bit is not inverted and stays the same. Below is a -program to blink digital pin 13 (the LED pin on Maple):: - - // Blink Maple LED pin - - int led_pin = 13; - int toggle = 0; - - // demo for Exclusive OR - void setup(){ - pinMode(led_pin, OUTPUT); - } - - void loop(){ - toggle = toggle ^ 1; - digitalWrite(led_pin, toggle); - delay(100); - } - -.. _arduino-bitwisemath-not: - -Bitwise NOT (~) ---------------- - -The bitwise NOT operator in C++ is the tilde character ``~``. Unlike -``&`` and ``|``, the bitwise NOT operator is applied to a single -operand to its right. Bitwise NOT changes each bit to its opposite: 0 -becomes 1, and 1 becomes 0. For example:: - - 0 1 operand1 - ---- - 1 0 ~operand1 = result - -Another example:: - - char a = 103; // binary: 01100111 - char b = ~a; // binary: 10011000 = -104 - -You might be surprised to see a negative number like -104 as the -result of this operation. This is because the highest bit in an int -variable is the so-called "sign bit". If the highest bit is 1, the -number is interpreted as negative. This encoding of positive and -negative numbers is referred to as *two's complement*. For more -information, see the Wikipedia article on `two's -complement. `_ - -As an aside, it is interesting to note that (under two's complement -arithmetic) for any integer ``x``, ``~x`` is the same as ``-x-1``. - -At times, the sign bit in a signed integer expression can cause -some unwanted surprises. - - -Uses ----- - -One of the most common uses of bitwise operations is to select or -manipulate a particular bit (or bits) from an integer value, often -called `bit masking -`_\ . See the -linked Wikipedia article for more information and examples. - -If you really want to see bit-twiddling techniques in their full -glory, you could do much worse than to get yourself a copy of -`Hacker's Delight `_\ . - - -See Also --------- - -- :ref:`Boolean operations ` (``&&``, ``||``) -- :ref:`Compound bitwise operations ` (``&=``, - ``|=``, ``^=``). - - -.. include:: cc-attribution.txt diff --git a/source/arduino/bitwrite.rst b/source/arduino/bitwrite.rst deleted file mode 100644 index 0e57cc4..0000000 --- a/source/arduino/bitwrite.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _arduino-bitwrite: - -bitWrite(x, n, b) -================= - -Description ------------ - -(Macro) Writes a bit of a numeric variable. - -Parameters ----------- - -**x**: the numeric variable whose bit to write. - -**n**: which bit of the number to write, starting at 0 for the -least-significant (rightmost) bit. - -**b**: the value to write to the bit (0 or 1). - -Returns -------- - -Nothing. - -Arduino Compatibility ---------------------- - -Maple's version of ``bitWrite()`` is compatible with Arduino. - -See also --------- - -- :ref:`bit() ` -- :ref:`bitRead() ` -- :ref:`bitSet() ` -- :ref:`bitClear() ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/boolean.rst b/source/arduino/boolean.rst deleted file mode 100644 index 1d834d3..0000000 --- a/source/arduino/boolean.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. highlight:: cpp - -.. _arduino-boolean: - -Boolean Operators -================= - -These can be used inside the condition of an :ref:`if ` -statement. Evaluate to :ref:`true ` or -:ref:`false `. - -.. contents:: Contents - :local: - -.. _arduino-boolean-and: - -&& (logical and) ----------------- - -True only if both operands are true. For example:: - - if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches - // ... - } - -is true only if both inputs are high. Another example:: - - if (a >= 10 && a <= 20){} // true if a is between 10 and 20 - -**Be careful** not to say ``10 <= a <= 20``! This won't work the way -you want. You have to separately test whether ``a`` is at least 10 -using ``a >= 10``, then test whether ``a`` is at most 20 using ``a <= -20``, then combine the results using ``&&``. - - -.. _arduino-boolean-or: - -\|\| (logical or) ------------------ - -True if either operand is true. For example:: - - if (x > 0 || y > 0) { - // ... - } - -is true if either ``x`` or ``y`` is greater than 0. - -.. _arduino-boolean-not: - -! (logical not) ---------------- - -True if the operand is false. For example:: - - if (!x) { - // ... - } - -is true if ``x`` is false (i.e. if ``x`` is zero). - -Some Advice ------------ - -.. warning:: - - Make sure you don't mistake the boolean AND operator ``&&`` - (double ampersand) for the :ref:`bitwise AND operator - ` ``&`` (single ampersand). They are - entirely different beasts. - - Similarly, do not confuse the boolean OR operator ``||`` (double - pipe) with the :ref:`bitwise OR operator ` - ``|`` (single pipe). - - The :ref:`bitwise NOT operator ` ``~`` - (tilde) looks much different than the boolean not operator ``!`` - (exclamation point, or "bang", as some programmers say), but you - still have to be sure which one you want. - - -See Also --------- - -- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) -- :ref:`Compound bitwise operators ` (``&=``, - ``|=``, ``^=``). -- :ref:`if statement ` - - -.. include:: cc-attribution.txt diff --git a/source/arduino/booleanvariables.rst b/source/arduino/booleanvariables.rst deleted file mode 100644 index a5f2c51..0000000 --- a/source/arduino/booleanvariables.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. highlight:: cpp - -.. _arduino-booleanvariables: - -Booleans -======== - -A **boolean** holds one of two values, :ref:`true -` or :ref:`false `. -On a Maple, each boolean variable occupies one byte of memory, and has -type ``bool``. - -.. warning:: - - On an Arduino, the type ``boolean`` is also provided. While the - Maple also has this type for compatibility, **its use is strongly - discouraged**. The ``bool`` type is a standard part of C++, while - ``boolean`` is a non-standard extension that serves no purpose. - -Example -------- - -:: - - int ledPin = 13; // LED on pin 13 - int switchPin = 12; // momentary switch on 12, other side connected to ground - - // running is a boolean variable: - bool running = false; - - void setup() { - pinMode(ledPin, OUTPUT); - pinMode(switchPin, INPUT); - digitalWrite(switchPin, HIGH); // turn on pullup resistor - } - - void loop() { - if (digitalRead(switchPin) == LOW) { - // switch is pressed - pullup keeps pin high normally - delay(100); // delay to debounce switch - running = !running; // toggle running variable - digitalWrite(ledPin, running) // indicate via LED - } - } - -See also --------- - - -- :ref:`Boolean constants ` -- :ref:`Boolean operators ` -- :ref:`Variables ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/braces.rst b/source/arduino/braces.rst deleted file mode 100644 index 04518b3..0000000 --- a/source/arduino/braces.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. highlight:: cpp - -.. _arduino-braces: - -Curly Braces ({}) -================= - -.. contents:: Contents - :local: - -Introduction ------------- - -Curly braces (also referred to as just "braces" or as "curly -brackets") are a major part of the C and C++ programming -languages. They are used in several different constructs, outlined -below, and this can sometimes be confusing for beginners. - -An opening curly brace, ``{`` must always be followed by a closing -curly brace ``}``. This is a condition that is often referred to as -the braces being *balanced*. The Maple IDE (integrated development -environment) includes a convenient feature to check the balance of -curly braces. Just select a brace, or even click the insertion point -immediately following a brace, and its companion will be highlighted\ -[#fbug]_\ . - -Beginning programmers, and programmers coming to C++ from languages -without braces, often find using them confusing or daunting. - -Because the use of the curly brace is so varied, it is good -programming practice to type the closing brace immediately after -typing the opening brace when inserting a construct which requires -curly braces. Then insert some blank lines between your braces and -begin inserting statements. Your braces, and your attitude, will never -become unbalanced. - -Unbalanced braces can often lead to cryptic, impenetrable compiler -errors that can sometimes be hard to track down in a large program. -Because of their varied usages, braces are also incredibly important -to the syntax of a program and moving a brace one or two lines will -usually dramatically affect the meaning of a program. - -The main uses of curly braces ------------------------------ - -**Functions**:: - - // a function body needs braces around it - void myfunction(datatype argument) { - // ... function body goes in here ... - } - -**Loops** (see the :ref:`while `\ , :ref:`for -`\ , and :ref:`do/while ` loop reference -pages for more information):: - - // you should put braces around the body of a loop: - - while (boolean expression) { - // code inside the loop goes here - } - - for (initialisation; termination condition; incrementing expr) { - // code inside the loop goes here - } - - do { - // code inside the loop goes here - } while (boolean expression); - - -**Conditional statements** (see the :ref:`if statement ` -reference page for more information):: - - // you should put braces around the body of an "if", "else if", - // or "else": - - if (boolean expression) { - // code inside the "if" - } - else if (boolean expression) { - // code inside the "else if" - } - else { - // code inside the "else" - } - -.. rubric:: Footnotes - -.. TODO remove this once IDE 0.1.0 released - -.. [#fbug] At present this feature is slightly buggy as the IDE will - often find (incorrectly) a brace in text that has been commented - out. - - -.. include:: cc-attribution.txt diff --git a/source/arduino/break.rst b/source/arduino/break.rst deleted file mode 100644 index 3e1e9ee..0000000 --- a/source/arduino/break.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. highlight:: cpp - -.. _arduino-break: - -break -===== - -``break`` is used to exit from a :ref:`while `\ , -:ref:`for `\ , or :ref:`do/while ` loop, -bypassing the normal loop condition. It is also used to exit from a -:ref:`switch ` statement. - - -Example -------- - -:: - - for (x = 0; x < 255; x ++) - { - digitalWrite(PWMpin, x); - sens = analogRead(sensorPin); - if (sens > threshold){ // bail out on sensor detect - x = 0; - // this line of code means that we'll immediately exit - // from the "for" loop: - break; - } - delay(50); - } - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/byte.rst b/source/arduino/byte.rst deleted file mode 100644 index 8478d0b..0000000 --- a/source/arduino/byte.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. highlight:: cpp - -.. _arduino-byte: - -byte -==== - -The ``byte`` type stores a 1-byte (8-bit) unsigned integer number, -from 0 to 255. - -.. warning:: - - The ``byte`` type is provided for compatibility with Arduino. - However, it is a non-standard extension. The standard C++ type for - storing an 8-bit unsigned integer is ``unsigned char``; we - recommend using that instead. (Your code will still work on an - Arduino). - - -Example -------- - -:: - - byte b = 134; - -See Also --------- - -- :ref:`byte() ` (casting a value to a byte) -- :ref:`Variables ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/bytecast.rst b/source/arduino/bytecast.rst deleted file mode 100644 index 348c9fb..0000000 --- a/source/arduino/bytecast.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. highlight:: cpp - -.. _arduino-bytecast: - -byte() (cast) -============= - -Description ------------ - -Converts a value to the :ref:`byte ` data type. - -.. note:: - - Casting to the byte type is provided for compatibility with - Arduino. However, the recommended Maple type for storing an 8-bit - unsigned integer is ``uint8``. (C and C++ programmers: ``stdint.h`` - is also available). - - In order to cast a variable ``x`` to a ``uint8``, the - following syntax can be used:: - - uint8(x); - -Syntax ------- - -``byte(x)`` - - -Parameters ----------- - -**x**: a value of any integer type - - -Returns -------- - -The value, converted to a ``byte``. Note, however, that if the value -is larger than the maximum value you can store in a byte (255), then -the results might be strange and unexpected. - - -See Also --------- - -- :ref:`arduino-byte` - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/cc-attribution.txt b/source/arduino/cc-attribution.txt deleted file mode 100644 index e100140..0000000 --- a/source/arduino/cc-attribution.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. Included in all this directory's files in order to satisfy the -.. Arduino CC Attribution-ShareAlike 3.0 License - -.. admonition:: License and Attribution - - This documentation page was adapted from the `Arduino Reference - Documentation `_\ , which - is released under a `Creative Commons Attribution-ShareAlike 3.0 - License `_. diff --git a/source/arduino/char.rst b/source/arduino/char.rst deleted file mode 100644 index 72d5ef2..0000000 --- a/source/arduino/char.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _arduino-char: - -char -==== - -Description ------------ - -The ``char`` type stores a 1-byte character value (or integer with -value from -128 to 127). Character literals are written in single -quotes, like this: ``'A'`` (for multiple characters - strings - use -double quotes: ``"ABC"``). - - -Just like everything else on a computer, characters are stored as -numbers. You can see the specific encoding in the `ASCII chart -`_\ -. This means that it is possible to do arithmetic on characters, in -which the ASCII value of the character is used (e.g. ``'A' + 1`` has the -decimal value 66, since the ASCII value of the capital letter A in -decimal is 65). See the :ref:`Serial.println() -` documentation for more information about how -characters are converted into numbers. - -The ``char`` datatype is a signed type, meaning that it encodes -numbers from -128 to 127. For an unsigned type, which stores values -from 0 to 255, just use the type ``unsigned char`` (two words). - - -Example -------- - -:: - - // the following two lines are equivalent: - char c = 'A'; - char c = 65; - - -See also --------- - - -- :ref:`arduino-int` -- :ref:`arduino-array` (a string is just an array of ``char``\ s) -- :ref:`Serial.println() ` - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/charcast.rst b/source/arduino/charcast.rst deleted file mode 100644 index 91a0f8f..0000000 --- a/source/arduino/charcast.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. highlight:: cpp - -.. _arduino-charcast: - -char() (cast) -============= - -Description ------------ - -Converts a value to the :ref:`char ` data type. - -Syntax ------- - -``char(x)`` - - -Parameters ----------- - -**x**: a value of any type - - -Returns -------- - -The value, converted to a ``char``. Note, however, that if the value -is outside the range of a ``char`` (-128 to 127), then the results -might be strange and unexpected. - - -See Also --------- - -- :ref:`char ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/comments.rst b/source/arduino/comments.rst deleted file mode 100644 index b50aa0f..0000000 --- a/source/arduino/comments.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. highlight:: cpp - -.. _arduino-comments: - -Comments -======== - -Comments are lines in the program that are used to inform yourself or -others about the way the program works. They are ignored by the -compiler, and not exported to the processor, so they don't take up any -space in RAM or Flash. - -One use for comments is to help you understand (or remember) how your -program works, or to inform others how your program works. There are -two different ways of making comments. - -.. _arduino-comments-singleline: - -**Single line comment**: Anything following two slashes, ``//``, until -the end of the line, is a comment:: - - x = 5; // the rest of this line is a comment - -.. _arduino-comments-multiline: - -**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` -is a comment:: - - /* <-- a slash-star begins a multi-line comment - - all of this in the multi-line comment - you can use it to comment - out whole blocks of code - - if (gwb == 0){ // single line comment is OK inside a multi-line comment - x = 3; - } - - // don't forget the "closing" star-slash - they have to be balanced: - */ - -Note that it's okay to use single-line comments within a multi-line -comment, but you can't use multi-line comments within a multi-line -comment. Here's an example:: - - /* ok, i started a multi-line comment - - x = 3; /* this next star-slash ENDS the multi-line comment: */ - - x = 4; // this line is outside of the multi-line comment - - // next line is also outside of the comment, and causes a compile error: - */ - -Programming Tip ---------------- - -When experimenting with code, "commenting out" parts of your program -is a convenient way to remove lines that may be buggy. This leaves -the lines in the code, but turns them into comments, so the compiler -just ignores them. This can be especially useful when trying to locate -a problem, or when a program refuses to compile and the compiler error -is cryptic or unhelpful. - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/comparison.rst b/source/arduino/comparison.rst deleted file mode 100644 index e5e92d7..0000000 --- a/source/arduino/comparison.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. highlight:: cpp - -.. _arduino-comparison: - -Comparison Operators -==================== - -The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and -``>=`` are used to compare two numbers. They are :ref:`true -` when the comparison is true, and :ref:`false -` otherwise. They are based on the symbols -=, ≠, <, >, ≤, and ≥ from mathematics. - -Here are some examples, with their meaning in comments:: - - // "eq" is true when x is equal to y - bool eq = (x == y); - - // "neq" is true when x is different than y - bool neq = (x != y); - - // "lt" is true when x is less than, but NOT equal to, y - bool lt = (x < y); - - // "gt" is true when x is greater than, but NOT equal to, y - bool gt = (x > y); - - // "lte" is true when x is less than or equal to y - bool lte = (x <= y); - - // "gte" is true when x is greater than or equal to y - bool gte = (x >= y); - -The parentheses are optional; they are present only for clarity. For -example, the following two lines are the same:: - - bool eq = x == y; - - bool eq = (x == y); - -Uses ----- - -Comparison operators, along with :ref:`boolean operators -`, are useful inside the conditionals of :ref:`if -` statements. Here's one example:: - - if (x < 50) { - // only execute these lines if x is less than 50 - SerialUSB.println("delaying:"); - SerialUSB.println(x); - delay(x); - } - -.. warning:: - Beware of accidentally using the single equal sign (``=``) when you - meant to test if two numbers are equal (``==``). This is a common - mistake inside of ``if`` statement conditionals, e.g.:: - - // DON'T MAKE THIS MISTAKE - if (x = 10) { - // body - } - - The single equal sign is the assignment operator, and sets x to 10 - (puts the value 10 into the variable x). Instead use the double equal - sign (e.g. ``if (x == 10)``), which is the comparison operator, and - tests *whether* x is equal to 10 or not. The latter statement is only - true if x equals 10, but the former statement will always be true. - - This is because C evaluates the statement ``if (x=10)`` as follows: 10 - is assigned to x (remember that the single equal sign is the - :ref:`assignment operator `), so x now - contains 10. Then the 'if' conditional evaluates 10, which evaluates - to :ref:`true `, since any non-zero number - evaluates to ``true``. - - Consequently, the conditional of an ``if`` statement like ``if (x = - 10) {...}`` will always evaluate to ``true``, and the variable x - will be set to 10, which is probably not what you meant. - - (This sometimes has uses, though, so just because an assignment - appears within a conditional doesn't mean it's automatically wrong. - Be careful to know what you mean.) - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/const.rst b/source/arduino/const.rst deleted file mode 100644 index b008144..0000000 --- a/source/arduino/const.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _arduino-const: - -const Keyword -============= - -The ``const`` keyword stands for "constant". It is a variable -*qualifier* that modifies the behavior of the variable, making a -variable "*read-only*". This means that the variable can be used just -as any other variable of its type, but its value cannot be -changed. You will get a compiler error if you try to assign a value to -a ``const`` variable. - -Constants defined with the ``const`` keyword obey the same rules of -:ref:`variable scoping ` that govern other -variables. This, and the pitfalls of using :ref:`#define -`, often makes using the ``const`` keyword a superior -method for defining constants than ``#define``. - -Example -------- - -:: - - // this defines a variable called "pi", which cannot be changed: - const float pi = 3.14; - float x; - - // .... - - x = pi * 2; // it's fine to find the value of a const variable - - pi = 7; // illegal - you can't write to (modify) a constant - - -**#define** or **const** ------------------------- - -You can use either ``const`` or ``#define`` for creating numeric or -string constants. For :ref:`arrays `\ , you will need -to use ``const``. In general, ``const`` is preferred over ``#define`` -for defining constants. - -See Also --------- - -- :ref:`#define ` -- :ref:`volatile ` - - -.. include:: cc-attribution.txt diff --git a/source/arduino/constants.rst b/source/arduino/constants.rst deleted file mode 100644 index e841c9b..0000000 --- a/source/arduino/constants.rst +++ /dev/null @@ -1,302 +0,0 @@ -.. _arduino-constants: - -constants -========= - -Constants are predefined variables in the Arduino language. They -are used to make the programs easier to read. We classify constants -in groups. - -.. contents:: Contents - :local: - -.. _arduino-constants-bool: - -Boolean Constants ------------------ - -There are two constants used to represent truth and falsity in the -Arduino language: **true**, and **false**. - -.. _arduino-constants-false: - -false -^^^^^ - -false is the easier of the two to define. false is defined as 0 -(zero). - -.. _arduino-constants-true: - -true -^^^^ - -true is often said to be defined as 1, which is correct, but true -has a wider definition. Any integer which is *non-zero* is TRUE, in -a Boolean sense. So -1, 2 and -200 are all defined as true, too, in -a Boolean sense. - - -Note that the *true* and *false* constants are typed in lowercase -unlike HIGH, LOW, INPUT, & OUTPUT. - - -Defining Pin Levels, HIGH and LOW ---------------------------------- - -When reading or writing to a digital pin there are only two -possible values a pin can take/be-set-to: **HIGH** and **LOW**. - -.. _arduino-constants-high: - -**HIGH** - - - -The meaning of HIGH (in reference to a pin) is somewhat different -depending on whether a pin is set to an INPUT or OUTPUT. When a pin -is configured as an INPUT with pinMode, and read with digitalRead, -the microcontroller will report HIGH if a voltage of 3 volts or -more is present at the pin. - - - -A pin may also be configured as an INPUT with pinMode, and -subsequently made HIGH with digitalWrite, this will set the -internal 20K pullup resistors, which will *steer* the input pin to -a HIGH reading unless it is pulled LOW by external circuitry. - - - -When a pin is configured to OUTPUT with pinMode, and set to HIGH -with digitalWrite, the pin is at 5 volts. In this state it can -*source* current, e.g. light an LED that is connected through a -series resistor to ground, or to another pin configured as an -output, and set to LOW. - -.. _arduino-constants-low: - -**LOW** - - - -The meaning of LOW also has a different meaning depending on -whether a pin is set to INPUT or OUTPUT. When a pin is configured -as an INPUT with pinMode, and read with digitalRead, the -microcontroller will report LOW if a voltage of 2 volts or less is -present at the pin. - - - -When a pin is configured to OUTPUT with pinMode, and set to LOW -with digitalWrite, the pin is at 0 volts. In this state it can -*sink* current, e.g. light an LED that is connected through a -series resistor to, +5 volts, or to another pin configured as an -output, and set to HIGH. - - - -Defining Digital Pins, INPUT and OUTPUT ---------------------------------------- - -Digital pins can be used either as **INPUT** or **OUTPUT**. -Changing a pin from INPUT TO OUTPUT with pinMode() drastically -changes the electrical behavior of the pin. - -.. _arduino-constants-input: - -Pins Configured as Inputs -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Arduino (Atmega) pins configured as **INPUT** with pinMode() are -said to be in a high-impedance state. One way of explaining this is -that pins configured as INPUT make extremely small demands on the -circuit that they are sampling, say equivalent to a series resistor -of 100 Megohms in front of the pin. This makes them useful for -reading a sensor, but not powering an LED. - -.. _arduino-constants-output: - -Pins Configured as Outputs -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Pins configured as **OUTPUT** with pinMode() are said to be in a -low-impedance state. This means that they can provide a substantial -amount of current to other circuits. Atmega pins can source -(provide positive current) or sink (provide negative current) up to -40 mA (milliamps) of current to other devices/circuits. This makes -them useful for powering LED's but useless for reading sensors. -Pins configured as outputs can also be damaged or destroyed if -short circuited to either ground or 5 volt power rails. The amount -of current provided by an Atmega pin is also not enough to power -most relays or motors, and some interface circuitry will be -required. - -.. _arduino-constants-fp: - -Floating-Point Constants ------------------------- - -Similar to integer constants, floating point constants are used to -make code more readable. Floating point constants are swapped at -compile time for the value to which the expression evaluates. - -.. TODO explain that floating point literals are doubles - -.. _arduino-constants-fp-f: - -.. TODO f modifiers - -Examples: - -``n = .005;`` - -Floating point constants can also be expressed in a variety of -scientific notation. 'E' and 'e' are both accepted as valid -exponent indicators. - -:: - - - floating-point evaluates to: also evaluates to: - constant - - 10.0 10 - 2.34E5 2.34 * 10^5 234000 - 67e-12 67.0 * 10^-12 .000000000067 - -.. _arduino-constants-integers: - -Integer Constants ------------------ - -Integer constants are numbers used directly in a sketch, like -``123``. By default, these numbers are treated as -`int `_'s but you can change -this with the U and L modifiers (see below). - - - -Normally, integer constants are treated as base 10 (decimal) -integers, but special notation (formatters) may be used to enter -numbers in other bases. - - - -:: - - Base Example Formatter Comment - - 10 (decimal) 123 none - - 2 (binary) B1111011 leading 'B' only works with 8 bit values (0 to 255) - characters 0-1 valid - - 8 (octal) 0173 leading "0" characters 0-7 valid - - 16 (hexadecimal) 0x7B leading "0x" characters 0-9, A-F, a-f valid - -.. _arduino-constants-integers-dec: - -**Decimal** is base 10. This is the common-sense math with which -you are acquainted. Constants without other prefixes are assumed to -be in decimal format. - - - -Example: -:: - - 101 // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) - -.. _arduino-constants-integers-bin: - -**Binary** is base two. Only characters 0 and 1 are valid. - - - -Example: -:: - - B101 // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) - -The binary formatter only works on bytes (8 bits) between 0 (B0) -and 255 (B11111111). If it is convenient to input an int (16 bits) -in binary form you can do it a two-step procedure such as: - - - -:: - - myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte - -.. _arduino-constants-integers-oct: - -**Octal** is base eight. Only characters 0 through 7 are valid. Octal -values are indicated by the prefix "0". - -Example: - -:: - - 0101 // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) - -Warning -It is possible to generate a hard-to-find bug by (unintentionally) -including a leading zero before a constant and having the compiler -unintentionally interpret your constant as octal. - -.. _arduino-constants-integers-hex: - -**Hexadecimal (or hex)** is base sixteen. Valid characters are 0 -through 9 and letters A through F; A has the value 10, B is 11, up -to F, which is 15. Hex values are indicated by the prefix "0x". -Note that A-F may be syted in upper or lower case (a-f). - - - -Example: - -:: - - 0x101 // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) - -.. _arduino-constants-integers-u-l: - -U & L formatters -^^^^^^^^^^^^^^^^ - -By default, an integer constant is treated as an -`int `_ with the attendant -limitations in values. To specify an integer constant with another -data type, follow it with: - - - - -- a 'u' or 'U' to force the constant into an unsigned data format. - Example: ``33u`` -- a 'l' or 'L' to force the constant into a long data format. - Example: ``100000L`` -- a 'ul' or 'UL' to force the constant into an unsigned long - constant. Example: ``32767ul`` - - - - -See also --------- - - -- `pinMode() `_ -- `Integer Constants `_ -- `boolean variables `_ -- `#define `_ -- `byte `_ -- `int `_ -- `unsigned int `_ -- `long `_ -- `unsigned long `_ - - -.. include:: cc-attribution.txt diff --git a/source/arduino/constrain.rst b/source/arduino/constrain.rst deleted file mode 100644 index a43b8f8..0000000 --- a/source/arduino/constrain.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. highlight:: cpp - -.. _arduino-constrain: - -constrain(x, a, b) -================== - -Description ------------ - -(Macro) Constrains a number to be within a range. - - -Parameters ----------- - -**x**: the number to constrain - -**a**: the lower end of the range - -**b**: the upper end of the range - -Returns -------- - -**x**: if **x** is between **a** and **b** - -**a**: if **x** is less than **a** - -**b**: if **x** is greater than **b** - -Example -------- - -:: - - // limits range of sensor values to between 10 and 150: - sensVal = constrain(sensVal, 10, 150); - - -Warning -------- - -Because of the way ``constrain()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - constrain(x,a++,b); // avoid this - yields incorrect results - - constrain(x,a,b); // use this instead- - a++; // keep other math outside constrain() - -Arduino Compatibility ---------------------- - -Maple's implementation of ``constrain()`` is compatible with Arduino. - -See also --------- - -- :ref:`min() ` -- :ref:`max() ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/continue.rst b/source/arduino/continue.rst deleted file mode 100644 index bda1c95..0000000 --- a/source/arduino/continue.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. highlight:: cpp - -.. _arduino-continue: - -========== - continue -========== - -The ``continue`` keyword skips the rest of the current iteration of a -:ref:`while `\ , :ref:`for `\ , or -:ref:`do/while ` loop. It continues by checking the -conditional expression of the loop, and proceeding with any subsequent -iterations. - - -Example -======= - -:: - - - for (x = 0; x < 255; x ++) { - if (x > 40 && x < 120) { // create jump in values - continue; // skips the next two lines and goes to the - // beginning of the loop, with the next value of x - } - - digitalWrite(PWMpin, x); - delay(50); - } - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/cos.rst b/source/arduino/cos.rst deleted file mode 100644 index e1188d0..0000000 --- a/source/arduino/cos.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _arduino-cos: - -cos(rad) -======== - -Calculate the cosine of an angle (in radians). - -Library Documentation ---------------------- - -.. doxygenfunction:: cos - - -Arduino Compatibility ---------------------- - -The Maple ``cos()`` implementation is compatible with Arduino. - -Note that the Maple implementation comes from `newlib -`_\ , while Arduino's is that of -`avr-libc `_\ . - -See also --------- - - -- :ref:`sin() ` -- :ref:`tan() ` -- :ref:`float ` -- :ref:`double ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/define.rst b/source/arduino/define.rst deleted file mode 100644 index 6a403d4..0000000 --- a/source/arduino/define.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. highlight:: cpp - -.. _arduino-define: - -#define -======= - -``#define`` is a useful C and C++ feature that allows the programmer -to give a name to a constant value before the program is compiled. -The compiler will replace references to these constants with the -defined value at compile time. - -This can have some unwanted side effects. In general, the :ref:`const -` keyword is preferred for defining constants. - - -Syntax ------- - -The following line would define the name ``MY_CONSTANT`` to have value -``value``:: - - #define MY_CONSTANT value - -Note that the ``#`` is necessary. It is usually good style for the -name to be capitalized, although this is not required. - -There is no semicolon after the #define statement. If you include one, -the compiler will likely throw cryptic errors in unrelated places. -That is, **don't do this**:: - - // DON'T DO THIS! THE SEMICOLON SHOULDN'T BE THERE! - #define NAME value; - -Similarly, including an equal sign after the ``#define`` line will -also generate a cryptic compiler error further down the page. That -is, **don't do this, either**:: - - // DON'T DO THIS, EITHER! THE EQUALS SIGN SHOULDN'T BE THERE! - #define NAME = value - -Example -------- - -:: - - #define LED_PIN 13 - // The compiler will replace any mention of LED_PIN with - // the value 3 at compile time. - -See Also --------- -- :ref:`const ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/delay.rst b/source/arduino/delay.rst deleted file mode 100644 index 64d78aa..0000000 --- a/source/arduino/delay.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. highlight:: cpp - -.. _arduino-delay: - -delay() -======= - -Pauses the program for at least a given number of milliseconds. (There -are 1000 milliseconds in a second.) - -Library Documentation ---------------------- - -.. doxygenfunction:: delay - - -Discussion ----------- - -While it is easy to create a blinking LED with the ``delay()`` -function, and many sketches use short delays for such tasks as switch -debouncing, the use of ``delay()`` in a sketch has significant -drawbacks. No other reading of sensors, mathematical calculations, or -pin manipulation can go on during the delay function, so in effect, it -brings most other activity to a halt. For alternative approaches to -controlling timing see the :ref:`millis() ` function -and the "Blink Without Delay" sketch cited :ref:`below -`\ . More knowledgeable programmers usually -avoid the use of ``delay()`` for timing of events longer than tens of -milliseconds, unless the sketch is very simple. - -Certain things *do* go on while the ``delay()`` function is -controlling the STM32 chip, however, because the delay function does -not disable interrupts. Serial communication that appears at the RX -pin is recorded, PWM (see :ref:`pwmWrite() `\ ) -values and pin states are maintained, and :ref:`interrupts -` will work as they should. - - -Example -------- - -:: - - int ledPin = 13; // LED connected to pin 13 - - void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output - } - - void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second - } - -.. _arduino-delay-seealso: - -See also --------- - - -- :ref:`millis() ` -- :ref:`micros() ` -- :ref:`delayMicroseconds() ` -- (Arduino) `Blink Without Delay `_ example (works unmodified on Maple) - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/delaymicroseconds.rst b/source/arduino/delaymicroseconds.rst deleted file mode 100644 index d1016f1..0000000 --- a/source/arduino/delaymicroseconds.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. highlight:: cpp - -.. _arduino-delaymicroseconds: - -delayMicroseconds() -=================== - -Pauses the program for the amount of time (in microseconds) -specified as parameter. There are a thousand microseconds in a -millisecond, and a million microseconds in a second. - -Library Documentation ---------------------- - -.. doxygenfunction:: delayMicroseconds - - -Example -------- - -The following example configures pin number 8 to work as an output -pin, and sends a train of pulses with a period of roughly 100 -microseconds:: - - int outPin = 8; - - void setup() { - pinMode(outPin, OUTPUT); // sets the digital pin as output - } - - void loop() { - digitalWrite(outPin, HIGH); // sets the pin on - delayMicroseconds(50); // pauses for 50 microseconds - digitalWrite(outPin, LOW); // sets the pin off - delayMicroseconds(50); // pauses for 50 microseconds - } - - -Caveats and Known Issues ------------------------- - -The longest time ``delayMicroseconds()`` can delay is bounded by its -argument type and the STM32 clock rate to be (2^32 - 1) / 12 -microseconds, or less than 6 minutes. For longer pauses, use of -:ref:`arduino-delay` is possible. - -Arduino Compatibility ---------------------- - -While we have made every effort we could to ensure that the timing of -delayMicroseconds is as accurate as possible, we cannot guarantee it -will behave as the Arduino implementation down to the microsecond, -especially for smaller values of ``us``. - -See Also --------- - -- :ref:`millis ` -- :ref:`micros ` -- :ref:`delay ` - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/detachinterrupt.rst b/source/arduino/detachinterrupt.rst deleted file mode 100644 index 6e037e6..0000000 --- a/source/arduino/detachinterrupt.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _arduino-detachinterrupt: - -detachInterrupt() -================= - -Used to disable an interrupt specified with -:ref:`arduino-attachinterrupt`\ . - - -Library Documentation ---------------------- - -.. doxygenfunction:: detachInterrupt - -Arduino Compatibility ---------------------- - -There is one important difference between the Maple version of -detachInterrupt and the Arduino version. On the Maple, the argument -to ``detachInterrupt()`` is the *pin* on which the interrupt is -attached, while on the Arduino, the argument is the *interrupt -number*, which is different from the pin the interrupt is enabled on. - -If you're calling this function, you've already called -:ref:`arduino-attachinterrupt` to set up your interrupt handler, so -just call ``detachInterrupt()`` with the same pin argument you gave to -``attachInterrupt()``. - -See Also --------- - -- :ref:`attachInterrupt() ` - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/digitalread.rst b/source/arduino/digitalread.rst deleted file mode 100644 index daf04f8..0000000 --- a/source/arduino/digitalread.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. highlight:: cpp - -.. _arduino-digitalread: - -digitalRead() -============= - -Description ------------ - -Reads the value from a specified digital pin, either :ref:`HIGH -` or :ref:`LOW `. - - -Library Documentation ---------------------- - -.. doxygenfunction:: digitalRead - - -Example -------- - -The following example turns the LED on when the button is pressed:: - - int ledPin = 13; // LED connected to Maple pin 13 - int buttonPin = 38; // BUT connected to Maple pin 38 - - void setup() { - pinMode(ledPin, OUTPUT); - pinMode(buttonPin, INPUT); - } - - void loop() { - int val = digitalRead(buttonPin); // reads the input pin - digitalWrite(ledPin, val); - } - -Note ----- - -If the pin isn't connected to anything, ``digitalRead()`` can return -either HIGH or LOW (and this can change in a way that seems random). - -Arduino Compatibility ---------------------- - -The Maple version of ``digitalRead()`` is compatible with Arduino. - - -See Also --------- - -- :ref:`pinMode ` -- :ref:`digitalWrite ` - - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/digitalwrite.rst b/source/arduino/digitalwrite.rst deleted file mode 100644 index b80d5c6..0000000 --- a/source/arduino/digitalwrite.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. _arduino-digitalwrite: - -digitalWrite() -============== - -Description ------------ - -Write a `HIGH `_ or a -`LOW `_ value to a -digital pin. - - - -If the pin has been configured as an OUTPUT with -`pinMode `_\ (), its voltage -will be set to the corresponding value: 5V (or 3.3V on 3.3V boards) -for HIGH, 0V (ground) for LOW. - - - -If the pin is configured as an INPUT, writing a HIGH value with -digitalWrite() will enable an internal 20K pullup resistor (see the -`tutorial on digital pins `_). -Writing LOW will disable the pullup. The pullup resistor is enough -to light an LED dimly, so if LEDs appear to work, but very dimly, -this is a likely cause. The remedy is to set the pin to an output -with the pinMode() function. - - - -**NOTE:** Digital pin 13 is harder to use as a digital input than -the other digital pins because it has an LED and resistor attached -to it that's soldered to the board on most boards. If you enable -its internal 20k pull-up resistor, it will hang at around 1.7 V -instead of the expected 5V because the onboard LED and series -resistor pull the voltage level down, meaning it always returns -LOW. If you must use pin 13 as a digital input, use an external -pull down resistor. - - - -Syntax ------- - -digitalWrite(pin, value) - - - -Parameters ----------- - -pin: the pin number - - - -value: `HIGH `_ or -`LOW `_ - - - -Returns -------- - -none - - - -Example -------- - -:: - - - int ledPin = 13; // LED connected to digital pin 13 - - void setup() - { - pinMode(ledPin, OUTPUT); // sets the digital pin as output - } - - void loop() - { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second - } - - - -Sets pin 13 to HIGH, makes a one-second-long delay, and sets the -pin back to LOW. - - - -Note ----- - -The analog input pins can be used as digital pins, referred to as -A0, A1, etc. - - - -See also --------- - - -- `pinMode `_\ () -- `digitalRead `_\ () -- `Tutorial: Digital Pins `_ - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/double.rst b/source/arduino/double.rst deleted file mode 100644 index d1c1076..0000000 --- a/source/arduino/double.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _arduino-double: - -double -====== - -Description ------------ - -Double precision floating point number. Occupies 8 bytes. - -Floating point numbers are not exact, and may yield strange results -when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You -should instead check that the absolute value of the difference between -the numbers is less than some small number. - -Floating point math is also much slower than integer math in -performing calculations, so should be avoided if, for example, a loop -has to run at top speed for a critical timing function. Programmers -often go to some lengths to convert floating point calculations to -integer math to increase speed. - -For more information about floating point math, see the `Wikipedia -article `_\ . - -Floating-point numbers represent numbers with "decimal point", unlike -integral types, which always represent whole numbers. Floating-point -numbers are often used to approximate analog and continuous values -because they have greater resolution than integers. - -The double implementation on the Maple uses twice the number of bytes -as a :ref:`float `, with the corresponding gains in -precision. - -Tip ---- - -Users who borrow code from other sources that includes double -variables may wish to examine the code to see if the implied -precision is different from that actually achieved on the Maple. - - -See Also --------- - -- :ref:`float ` - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/doublecast.rst b/source/arduino/doublecast.rst deleted file mode 100644 index 9aaf12c..0000000 --- a/source/arduino/doublecast.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. highlight:: cpp - -.. _arduino-doublecast: - -double() (cast) -=============== - -Description ------------ - -Converts a value to the :ref:`double ` floating point -data type. Here is an example:: - - int x = 2; - double d = double(x); // d now holds 2.0, a double value - -The value ``x`` can be of any type. However, if ``x`` is not a number -(like an ``int`` or ``long``), you will get strange results. - -See the :ref:`double ` reference for details about the -precision and limitations of ``double`` values on the Maple. - -See Also --------- - -- :ref:`double ` -- :ref:`float ` -- :ref:`float() ` - -.. include:: cc-attribution.txt diff --git a/source/arduino/dowhile.rst b/source/arduino/dowhile.rst deleted file mode 100644 index 7dffe50..0000000 --- a/source/arduino/dowhile.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. highlight:: cpp - -.. _arduino-dowhile: - -do/while Loop -============= - -A ``do`` loop works in the same manner as a :ref:`while -` loop, with the exception that the condition is tested -at the end of the loop, so the ``do`` loop will *always* run at least -once. - -This is the basic syntax:: - - do { - // statement block - } while (test condition); - -Example:: - - do { - delay(50); // wait for sensors to stabilize - x = readSensors(); // check the sensors - } while (x < 100); - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/else.rst b/source/arduino/else.rst deleted file mode 100644 index 9345e8a..0000000 --- a/source/arduino/else.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. highlight:: cpp - -.. _arduino-else: - -if/else -======= - -``if``/\ ``else`` allows greater control over the flow of code than -the basic :ref:`if ` statement, by allowing multiple tests -to be grouped together. For example, an :ref:`analog input -` could be tested, with one action taken if the -input was less than 500, and another action taken if the input was 500 -or greater. The code would look like this:: - - if (pinFiveInput < 500) { - // action A - } else { - // action B - } - -``else`` can precede another ``if`` test, so that multiple, mutually -exclusive tests can be run at the same time. - -Each test will proceed to the next one until a true test is -encountered. When a true test is found, its associated block of code -is run, and the program then skips to the line following the entire -if/else construction. If no test proves to be true, the default -``else`` block is executed, if one is present, and sets the default -behavior. - - -Note that an ``else if`` block may be used with or without a -terminating ``else`` block, and vice-versa. An unlimited number of -such ``else if`` branches is allowed. Here is a code example:: - - if (pinFiveInput < 500) { - // do Thing A - } else if (pinFiveInput >= 1000) { - // do Thing B - } else { - // do Thing C - } - -Another way to express branching, mutually exclusive tests, is with a -:ref:`switch/case ` statement. - -See Also --------- - -- :ref:`if ` -- :ref:`switch/case ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/float.rst b/source/arduino/float.rst deleted file mode 100644 index aa3bd99..0000000 --- a/source/arduino/float.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. highlight:: cpp - -.. _arduino-float: - -float -===== - -.. TODO move all the useful examples over to arduino/double.rst. We -.. want to discourage using floats, since most of the common cmath -.. functions are only declared with doubles. - -Description ------------ - -Single-precision floating point number. ``float`` values can be as -large as 3.4028235E+38 and as low as -3.4028235E+38. They are stored -as 32 bits (4 bytes) of information. - -``float``\ s have only 6-7 decimal digits of precision. That means the total -number of digits, not the number to the right of the decimal point. -You can get more precision by using a :ref:`double ` -(which has a precision of about 16 decimal digits). - -The following example declares a ``float`` value named ``myfloat``:: - - float myfloat; - -This example declares a ``float`` value named ``sensorCalibrate``, -with value 1.117:: - - float sensorCalibrate = 1.117; - -The general syntax for declaring a float named ``var`` with value -``val`` is:: - - float var = val; - -Here is a more extended example involving a :ref:`float cast -`:: - - int x; - int y; - float z; - - x = 1; - y = x / 2; // y now contains 0, ints can't hold fractions - z = float(x) / 2; // z now contains .5 - -See Also --------- - -- :ref:`int ` -- :ref:`double ` -- :ref:`Variables ` - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/floatcast.rst b/source/arduino/floatcast.rst deleted file mode 100644 index a8d1113..0000000 --- a/source/arduino/floatcast.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. highlight:: cpp - -.. _arduino-floatcast: - -float() (cast) -============== - -Description ------------ - -Converts a value to the :ref:`float ` data type. Here -is an example (see the :ref:`constants reference -` for an explanation of the "2.0f"):: - - int x = 2; - float f = float(x); // f now holds 2.0f, a float value - -The value ``x`` can be of any type. However, if ``x`` is not a number -(like an ``int``), you will get strange results. - -See the :ref:`float ` reference for details about the -precision and limitations of ``float`` values on the Maple. - -See Also --------- - -- :ref:`float ` -- :ref:`double ` -- :ref:`double() ` - -.. include:: cc-attribution.txt diff --git a/source/arduino/for.rst b/source/arduino/for.rst deleted file mode 100644 index 43b82fa..0000000 --- a/source/arduino/for.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. highlight:: cpp - -.. _arduino-for: - -for Loops -========= - -.. contents:: Contents - :local: - -Description ------------ - -A ``for`` loop is used to repeat a block of statements enclosed in -curly braces. ``for`` loops are useful for performing repetitive -operations, and are often used in combination with :ref:`arrays -` to operate on collections of data or multiple -:ref:`pins `. A ``for`` loop is composed of two parts: first, a -*header*, which sets up the for loop, and then a *body*, which is made -up of lines of code enclosed in curly braces. - -There are three parts to the ``for`` loop header: an *initialization* -expression, *loop condition* expression, and a *post-loop* -expression. The general syntax looks like this:: - - for (initialization; condition; post-loop) { - // all of these lines inside the curly braces are part - // of the loop body. - statement 1; - statement 2; - ... - } - -(Note that there is no semicolon after the post-loop). The -initialization happens first and exactly once, before the loop begins. -Each time through the loop, the condition is tested. The condition is -a :ref:`boolean arduino-boolean` expression. If it is true, then the -list of statements inside the curly braces are executed. Next, the -post-loop is executed. The loop then begins again by evaluating the -condition again, entering the loop body if it is true. This proceeds -until the condition becomes false. - -Examples --------- - -Here's an example:: - - // Dim an LED using a PWM pin - int pwmPin = 9; // LED in series with 470 ohm resistor on pin 9 - - void setup() { - pinMode(pwmPin, PWM); - } - - void loop() { - for (int i=0; i <= 65535; i++) { - pwmWrite(pwmPin, i); - delay(1); - } - } - -There is a ``for`` loop In the :ref:`loop() ` function -of the above example. This loop starts by declaring an ``int`` -variable named ``i``, whose value starts out at zero. The loop -proceeds by checking if ``i`` is less than or equal to 65535. Since -``i`` is zero, this is true, and so the calls to :ref:`pwmWrite() -` and :ref:`arduino-delay` happen next. At this -point, the post-loop expression ``i++`` is evaluated, which -:ref:`increments ` ``i``, so that ``i`` becomes -one. That concludes the first time through the loop. Each "time -through the loop" is referred to as an *iteration*. - -The loop then jumps back to the beginning, checking the condition as -the beginning of its second iteration (initialization is skipped, -since this only happens once, before the first iteration). One is -less than 65535, so the loop statements are executed again. This -proceeds over and over until the iteration when ``i`` finally -reaches 65536. At that point, the condition is no longer true, so the -loop stops executing, and the ``loop()`` function returns. - -Here's another example, using a ``for`` loop to brighten and fade an -LED (see the :ref:`pwmWrite() ` reference for more -information):: - - int pwmPin = 9; // hook up the LED to pin 9 - void loop() { - int x = 1; - for (int i = 0; i >= 0; i += x) { - analogWrite(pwmPin, i); // controls the brightness of the LED - if (i == 65535) { - x = -1; // switch direction, so i starts decreasing - } - delay(1); - } - } - -Coding Tips ------------ - -The C ``for`` loop is more flexible than ``for`` loops found in some -other computer languages, including BASIC. Any or all of the three -header elements may be left blank, although the semicolons are -required. Also the statements for initialization, condition, and -post-loop can be any valid C statements, and use any C datatypes, -including :ref:`floating point numbers `. These types -of unusual ``for`` loops sometimes provide solutions to less-common -programming problems. - -For example, using a multiplication in the post-loop line will -generate a `geometric progression -`_:: - - for(int x = 1; x <= 100; x = x * 2) { - SerialUSB.println(x); - } - - -This loop prints out the numbers 1, 2, 4, 8, ..., 64. Check -your understanding of ``for`` loops by answering the following two -questions (answers are in footnote [#fanswers]_\ ): - -1. How many iterations occur before the loop finishes? - -2. Why does it stop at 64? - -See also --------- - -- :ref:`while ` loops -- :ref:`do ` loops - -.. rubric:: Footnotes - -.. [#fanswers] - 1. Seven. - - 2. After the seventh iteration, the post-loop causes ``x`` to - equal 128. This is larger than 100, so the loop condition is - false, and the loop stops. - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/goto.rst b/source/arduino/goto.rst deleted file mode 100644 index 2901913..0000000 --- a/source/arduino/goto.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. highlight:: cpp - -.. _arduino-goto: - -Labels and goto -=============== - -A *label* gives a name to a line of code within a function. You can -label a line by writing a name for it, then a colon (``:``), before -the line starts. The ``goto`` keyword allows program flow to transfer -to a labeled line from anywhere within the same function. - -.. warning:: The use of ``goto`` is discouraged in C and C++ - programming. It is *never necessary* to use ``goto`` to write a - program. - - Unless you know what you're doing, using ``goto`` tends to - encourage code which is harder to debug and understand than - programs without ``goto`` that do the same thing. That said, - however, it's sometimes useful; :ref:`see below ` - for a concrete example. - -Using Labels and goto ---------------------- - -Labels and ``goto`` are probably best explained through example. -Let's start with an example of how to label lines. The first line -(``int x = analogRead(some_pin);``) in the :ref:`loop ` -function below has label ``readpin``. The third line (``delay(x);``) -has label ``startdelay``. The second line (``SerialUSB.println(x);``) -does not have a label:: - - void loop() { - readpin: - int x = analogRead(some_pin); - SerialUSB.println(x); // for debugging - startdelay: - delay(x); - // ... more code ... - } - -Anything which can be a :ref:`variable ` name can -be a label. - -Let's say that we wanted to print ``x`` only if it was very large, say -at least 2000. We might want to do this just so anybody watching on a -:ref:`serial monitor ` would know they were in for -a longer wait than usual. We can accomplish this through the use of a -``goto`` statement that skips the printing if ``x`` is less than -2000:: - - void loop() { - readpin: - int x = analogRead(some_pin); - if (x < 2000) { - goto startdelay; - } - SerialUSB.println(x); // for debugging - startdelay: - delay(x); - // ... more code ... - } - -In this modified program, whenever ``x`` is less than 2000, the body -of the :ref:`if ` statement in the second line is -executed. The ``goto`` statement inside the ``if`` body skips -straight to the line labeled ``startdelay``, passing over the line -doing the printing. - -A ``goto`` does not have to "move forwards"; it can go "backwards", -too. For example, the following program prints "5" forever (why?):: - - void loop() { - printfive: - SerialUSB.println(5); - goto printfive; - SerialUSB.println(6); - } - -.. _goto-when-to-use: - -When to Use goto ----------------- - -As mentioned above, use of ``goto`` is `generally discouraged -`_. However, -when used with care, ``goto`` can simplify certain programs. One -important use case for ``goto`` is breaking out of deeply nested -:ref:`for ` loops or :ref:`if ` logic blocks. -Here's an example:: - - for(int r = 0; r < 255; r++) { - for(int g = 255; g > -1; g--) { - for(int b = 0; b < 255; b++) { - if (analogRead(0) > 250) { - goto bailout; - } - // more statements ... - } - // innermost loop ends here - } - } - bailout: - // more code here - -In the above example, whenever the :ref:`analog reading -` on pin 0 was greater than 250, the program would -jump to the line labeled ``bailout``, exiting all three loops at once. - -While there is already a :ref:`break ` keyword for -breaking out of a loop, it will only break out of the *innermost* -loop. So, if instead of saying "``goto bailout;``", there was a -"``break;``" instead, the program would only exit from the loop with -header "``for(int b = 0; b < 255; b++)``". The program would continue -at the line which reads "``// innermost loop ends here``", which is -clearly undesirable if you wanted to leave all three loops at once. - -More examples of when ``goto`` is a good choice are given in Donald -Knuth's paper, "Structured Programming with go to Statements"; see -below for a link. - -See Also --------- - -- Dijkstra, Edsger W. `Go To Statement Considered Harmful `_ (PDF) - -- Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) - - -.. include:: cc-attribution.txt diff --git a/source/arduino/highbyte.rst b/source/arduino/highbyte.rst deleted file mode 100644 index 5b1c24e..0000000 --- a/source/arduino/highbyte.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _arduino-highbyte: - -highByte(x) -=========== - -.. warning:: This macro is provided for compatibility with Arduino - only. It returns the second-least significant byte in an integral - value. It makes sense to call this the "high" byte on a 16-bit - ``int`` microcontroller like the Atmel chips on Arduinos, but it - makes no sense at all on a 32-bit microcontroller like the STM32s - in the Maple line. - - In short: we provide this so that existing Arduino code works as - expected, but **strongly discourage its use** in new programs. - -Description ------------ - -(Macro) Extracts the second lowest byte of an integral data type. - -Parameters ----------- - -**x**: a value of any integral type. - -Returns -------- - -Second lowest byte in **x**. - -Example -------- - -:: - - int x = 0xDEADBEEF; - SerialUSB.println(x, HEX); // prints "BE" - -Arduino Compatibility ---------------------- - -The Maple version of ``highByte()`` is compatible with Arduino. - -See Also --------- - -- :ref:`lowByte() ` - - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/if.rst b/source/arduino/if.rst deleted file mode 100644 index 89af166..0000000 --- a/source/arduino/if.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. highlight:: cpp - -.. _arduino-if: - -if Statements -============= - -An ``if`` statement is used to execute code when certain conditions -are met. The general syntax for an ``if`` statement is:: - - if (condition) { - body - } - -An ``if`` statement first tests whether its *condition* is true (such -as an input being above a certain number). If the condition is true, -the ``if`` statement executes its *body*, which is made up of lines of -code inside :ref:`curly braces `. If the condition is -false, the body is not executed. Here's a more concrete example:: - - if (someVariable > 50) { - // do something here - } - -The program tests to see if ``someVariable`` is greater than 50. If it -is, the program executes every line in the curly braces (which in the -above example does nothing, since the body is just the :ref:`comment -` line "``// do something here``"). - -Put another way, if the statement in parentheses is true, the -statements inside the braces are run. If not, the program skips over -the code. - -An ``if`` statement's condition (which is inside the parentheses after -``if``) often uses one or more :ref:`boolean ` or -:ref:`comparison ` operators. - -Writing the if Body -------------------- - -The brackets may be omitted after an ``if`` statement's -conditional. If this is done, the next line (which ends in a -semicolon) becomes the only line in the body. The following three -``if`` statements all do the same thing:: - - if (x > 120) digitalWrite(ledPin, HIGH); - - if (x > 120) - digitalWrite(ledPin, HIGH); - - if (x > 120) { - digitalWrite(ledPin, HIGH); - } - -However, the following two examples are different:: - - // example 1: two lines of code in the if body - if (x > 120) { - digitalWrite(ledPin1, HIGH); - digitalWrite(ledPin2, HIGH); - } - - // example 2: one line of code in the if body, and - // another line of code after the if statement - if (x > 120) - digitalWrite(ledPin1, HIGH); // this is in the if body - digitalWrite(ledPin2, HIGH); // this is NOT in the if body - -In the first example, since the body is enclosed in curly braces, both -lines are included. In the second example, since the curly braces are -missing, only the first line is in the ``if`` body. - -See Also --------- - -- :ref:`boolean operators ` -- :ref:`comparison operators ` -- :ref:`else ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/include.rst b/source/arduino/include.rst deleted file mode 100644 index 37553f4..0000000 --- a/source/arduino/include.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. highlight:: cpp - -.. _arduino-include: - -#include -======== - -``#include`` is used to include outside libraries in your sketch. -This gives the programmer access to a large group of standard C -libraries (groups of pre-made functions and data types), and also -libraries written especially for Maple. - -Example -------- - -This example (from the `Arduino LiquidCrystal Tutorial -`_) includes a library -that is used to control :ref:`LCD displays `:: - - // include the library code: - #include - - // initialize the library with the numbers of the interface pins - LiquidCrystal lcd(12, 11, 5, 4, 3, 2); - - void setup() { - // set up the LCD's number of columns and rows: - lcd.begin(16, 2); - // Print a message to the LCD. - lcd.print("hello, world!"); - } - - void loop() { - // set the cursor to column 0, line 1 - // (note: line 1 is the second row, since counting begins with 0): - lcd.setCursor(0, 1); - // print the number of seconds since reset: - lcd.print(millis()/1000); - } - -Note that a ``#include`` line, like :ref:`#define `, -has **no semicolon**. The compiler will print strange error messages -if you add one. - -C Standard Library ------------------- - -The standard C library that comes with Maple is called `newlib -`_. Its main sources of documentation -are its `main reference `_ -page and its `math functions -`_ reference page. Here's an -example that imports the math.h library in order to take the `cube -root `_ of a number:: - - #include - - void setup() { - // no setup necessary - } - - void loop() { - // "cbrt" stands for "cube root" - double cubeRootOf3 = cbrt(3.0); - // prints a number that is approximately the cube root of 3: - SerialUSB.println(cubeRootOf3); - } - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/increment.rst b/source/arduino/increment.rst deleted file mode 100644 index 38dee6c..0000000 --- a/source/arduino/increment.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. highlight:: cpp - -.. _arduino-increment: - -Increment (``++``) and Decrement (``--``) -========================================= - -These operators increment (add one to) or decrement (subtract one -from) a variable. If they come before the variable, they return its -new value; otherwise, they return its old value. - -Some quick examples:: - - x++; // adds one to x, and returns the old value of x - ++x; // adds one to x, and returns the new value of x - - x--; // decrement x by one and returns the old value of x - --x; // decrement x by one and returns the new value of x - -A more extended example:: - - x = 2; - y = ++x; // x now contains 3, y contains 3 - y = x--; // x contains 2 again, y still contains 3 - -.. warning:: Be careful! You cannot put a space in between the two - ``+`` or ``-`` signs. This example is broken:: - - // this line won't compile (notice the extra space): - int y = x+ +; - -Parameters ----------- - -**x**: an integer value (like an ``int``, ``long``, ``unsigned int``, -etc.). - -See also --------- - -- :ref:`Compound arithmetic operators ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/int.rst b/source/arduino/int.rst deleted file mode 100644 index 690deb8..0000000 --- a/source/arduino/int.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. highlight:: cpp - -.. _arduino-int: - -int -=== - -Description ------------ - -The ``int`` data type represents integers. Integers are your primary -data type for number storage, and store a 4 byte value. This yields a -range of -2,147,483,648 to 2,147,483,647 (minimum value of -2^31 and a -maximum value of (2^31) - 1; that's about negative 2 billion to -positive 2 billion). - -An ``int`` stores a negative number with a technique called `two's -complement math -`_\ . -The highest bit in an ``int``, sometimes refered to as the "sign" bit, -flags the number as a negative number. (See the linked article on -two's complement for more information). - -The Maple takes care of dealing with negative numbers for you, so that -arithmetic operations work mostly as you'd expect. There can be an -:ref:`unexpected complication ` in -dealing with the :ref:`bitshift right operator (>>) -`, however. - -Here is an example of declaring an ``int`` variable named ``ledPin``, -then giving it value 13:: - - int ledPin = 13; - -The general syntax for declaring an ``int`` variable named ``var``, -then giving it value ``val``, looks like:: - - int var = val; - -.. _arduino-int-overflow: - -Integer Overflow ----------------- - -When ``int`` variables leave the range specified above, they "roll -over" in the other direction. It's like in the game *Pac-Man* -- when -Pac-Man goes past the right edge of the screen, he reappears on the -left, and when he goes past the left side of the screen, he reappears -on the right. Here are some examples:: - - int x; - x = -2,147,483,648; - x--; // x now contains 2,147,483,647; rolled over "left to right" - - x = 2,147,483,647; - x++; // x now contains -2,147,483,648; rolled over "right to left" - -See Also --------- - -- :ref:`unsigned int ` -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`long ` -- :ref:`unsigned long ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/intcast.rst b/source/arduino/intcast.rst deleted file mode 100644 index 0b34a39..0000000 --- a/source/arduino/intcast.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. highlight:: cpp - -.. _arduino-intcast: - -int() -===== - -Description ------------ - -Converts a value to the :ref:`int ` data type. Here is -an example:: - - double d = 2.5; - int i = int(d); // i holds "2", an int value - -The value inside of the parentheses (``int(...)``) can be of any type. -However, if it is not a numeric type (like ``double``, ``char``, -etc.), you will get strange results. - -See the :ref:`int ` reference for details about the -precision and limitations of ``int`` variables on the Maple. - -See Also --------- - -- :ref:`int ` - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/interrupts.rst b/source/arduino/interrupts.rst deleted file mode 100644 index b9c95b1..0000000 --- a/source/arduino/interrupts.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _arduino-interrupts: - -interrupts() -============ - -Description ------------ - -Re-enables interrupts (after they've been disabled by -`noInterrupts `_\ ()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None - - - -Returns -------- - -None - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `noInterrupts `_\ () -- `attachInterrupt `_\ () -- `detachInterrupt `_\ () - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/long.rst b/source/arduino/long.rst deleted file mode 100644 index cae659a..0000000 --- a/source/arduino/long.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. highlight:: cpp - -.. _arduino-long: - -long -==== - -Description ------------ - -The ``long`` data type stores extended size integer values. You can -use a ``long`` when your values are too large to fit into an :ref:`int -`. A ``long`` occupies 8 bytes of memory. This yields a -range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion -billion, or about 92 million times the number of stars in the Milky -Way galaxy). The exact range of a ``long`` on the Maple is from --9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to -(2^63-1). - -Here's an example of declaring a long (see :ref:`integer constants -` for explanation of the 'L'):: - - // Speed of light in nanometers per second (approximate). - long c = 299792458000000000L; - -The general syntax for declaring an ``long`` variable named ``var``, -then giving it value ``val``, looks like:: - - long var = val; - -This is identical to the ``int`` syntax, with ``long`` replacing -``int``. - -Note that ``long`` values will still :ref:`overflow -`, just like ``int`` values, but their much -larger range makes this less likely to happen. - -The downside to using a ``long`` instead of an ``int`` (besides the -extra storage) is that :ref:`arithmetic ` -operations on ``long``\ s will take longer than on ``int``\ s. - -See Also --------- - -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`int ` -- :ref:`unsigned int ` -- :ref:`unsigned long ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/longcast.rst b/source/arduino/longcast.rst deleted file mode 100644 index f247dae..0000000 --- a/source/arduino/longcast.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. highlight:: cpp - -.. _arduino-longcast: - -long() -====== - -Description ------------ - -Converts a value to the :ref:`long ` data type. Here is -an example:: - - double d = 2.5; - long i = long(d); // i holds "2L", an long value - -The value inside of the parentheses (``long(...)``) can be of any type. -However, if it is not a numeric type (like ``double``, ``char``, -etc.), you will get strange results. - -See the :ref:`long ` reference for details about the -precision and limitations of ``long`` variables on the Maple. - -See Also --------- - -- :ref:`long ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/loop.rst b/source/arduino/loop.rst deleted file mode 100644 index 4383ab6..0000000 --- a/source/arduino/loop.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. highlight:: cpp - -.. _arduino-loop: - -loop() -====== - -After creating a :ref:`setup() ` function, which -initializes your sketch, the ``loop()`` function gets called -repeatedly, allowing your program to change and respond. Use it to -actively control your Maple board. - -Example -------- - -:: - - - int buttonPin = 38; - - // setup initializes serial and the button pin - void setup() { - SerialUSB.begin(); - pinMode(buttonPin, INPUT); - } - - // loop() checks the button pin each time it executes, - // and will print 'H' if it is pressed, 'L' otherwise - void loop() { - if (digitalRead(buttonPin) == HIGH) { - SerialUSB.println('H'); - } else { - SerialUSB.println('L'); - } - - delay(1000); - } - -See Also --------- - -- :ref:`setup() ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/lowbyte.rst b/source/arduino/lowbyte.rst deleted file mode 100644 index 9331181..0000000 --- a/source/arduino/lowbyte.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _arduino-lowbyte: - -lowByte() -========= - -Description ------------ - -Extracts the low-order (rightmost) byte of a variable (e.g. a -word). - - - -Syntax ------- - -lowByte(x) - - - -Parameters ----------- - -x: a value of any type - - - -Returns -------- - -byte - - - -See also --------- - - -- `highByte `_\ () -- `word `_\ () - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/map.rst b/source/arduino/map.rst deleted file mode 100644 index 61aa626..0000000 --- a/source/arduino/map.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. _arduino-map: - -map(value, fromLow, fromHigh, toLow, toHigh) -============================================ - -Description ------------ - -Re-maps a number from one range to another. That is, a **value** of -**fromLow** would get mapped to **toLow**, a value of **fromHigh** -to **toHigh**, values in-between to values in-between, etc. - - - -Does not constrain values to within the range, because out-of-range -values are sometimes intended and useful. The constrain() function -may be used either before or after this function, if limits to the -ranges are desired. - - - -Note that the "lower bounds" of either range may be larger or -smaller than the "upper bounds" so the map() function may be used -to reverse a range of numbers, for example - - - -``y = map(x, 1, 50, 50, 1);`` - - - -The function also handles negative numbers well, so that this -example - - - -``y = map(x, 1, 50, 50, -100);`` - - - -is also valid and works well. - - - -The map() function uses integer math so will not generate -fractions, when the math might indicate that it should do so. -Fractional remainders are truncated, and are not rounded or -averaged. - - - -Parameters ----------- - -value: the number to map - - - -fromLow: the lower bound of the value's current range - - - -fromHigh: the upper bound of the value's current range - - - -toLow: the lower bound of the value's target range - - - -toHigh: the upper bound of the value's target range - - - -Returns -------- - -The mapped value. - - - -Example -------- - -:: - - /* Map an analog value to 8 bits (0 to 255) */ - void setup() {} - - void loop() - { - int val = analogRead(0); - val = map(val, 0, 1023, 0, 255); - analogWrite(9, val); - } - - - -Appendix -~~~~~~~~ - -For the mathematically inclined, here's the whole function - - - -:: - - long map(long x, long in_min, long in_max, long out_min, long out_max) - { - return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; - } - - - -See Also --------- - - -- `constrain `_\ () - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/max.rst b/source/arduino/max.rst deleted file mode 100644 index a80c421..0000000 --- a/source/arduino/max.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. highlight:: cpp - -.. _arduino-max: - -max(x, y) -========= - -Description ------------ - -(Macro) Calculates the maximum of two numbers. - - - -Parameters ----------- - -**x**: the first number; may be any number or numeric expression. - -**y**: the second number; may be any number or numeric expression. - - -Returns -------- - -The larger of the two parameter values. - -Example -------- - -:: - - sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 - // (effectively ensuring that it is at least 20) - -.. note:: Perhaps counter-intuitively, max() is often used to - constrain the lower end of a variable's range, while :ref:`min() - ` is used to constrain the upper end of the range. - -Warning -------- - -Because of the way ``max()`` is implemented, avoid using other -functions inside the parentheses. It may lead to incorrect results:: - - max(a--, 0); // avoid this - yields incorrect results - - a--; // use this instead - - max(a, 0); // keep other operations outside max() - -Arduino Compatibility ---------------------- - -The Maple version of ``max()`` is compatible with Arduino. - -See Also --------- - -- :ref:`min() ` -- :ref:`constrain() ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/micros.rst b/source/arduino/micros.rst deleted file mode 100644 index bd8b926..0000000 --- a/source/arduino/micros.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _arduino-micros: - -micros() -======== - -Description ------------ - -Returns the number of microseconds since the Arduino board began -running the current program. This number will overflow (go back to -zero), after approximately 70 minutes. On 16 MHz Arduino boards -(e.g. Duemilanove and Nano), this function has a resolution of four -microseconds (i.e. the value returned is always a multiple of -four). On 8 MHz Arduino boards (e.g. the LilyPad), this function -has a resolution of eight microseconds. - - - -*Note*: there are 1,000 microseconds in a millisecond and 1,000,000 -microseconds in a second. - - - -Parameters ----------- - -None - - - -Returns -------- - -Number of microseconds since the program started (*unsigned long*) - - - -Example -------- - -:: - - unsigned long time; - - void setup(){ - Serial.begin(9600); - } - void loop(){ - Serial.print("Time: "); - time = micros(); - //prints time since program started - Serial.println(time); - // wait a second so as not to send massive amounts of data - delay(1000); - } - - - -See also --------- - - -- `millis `_\ () -- `delay `_\ () -- `delayMicroseconds `_\ () - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/millis.rst b/source/arduino/millis.rst deleted file mode 100644 index f52d396..0000000 --- a/source/arduino/millis.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _arduino-millis: - -millis() -======== - -Description ------------ - -Returns the number of milliseconds since the Arduino board began -running the current program. This number will overflow (go back to -zero), after approximately 50 days. - - - -Parameters ----------- - -None - - - -Returns -------- - -Number of milliseconds since the program started (*unsigned long*) - - - -Example -------- - -:: - - unsigned long time; - - void setup(){ - Serial.begin(9600); - } - void loop(){ - Serial.print("Time: "); - time = millis(); - //prints time since program started - Serial.println(time); - // wait a second so as not to send massive amounts of data - delay(1000); - } - - - -Tip: ----- - -Note that the parameter for millis is an unsigned long, errors may -be generated if a programmer tries to do math with other datatypes -such as ints. - - - -See also --------- - - -- `micros `_\ () -- `delay `_\ () -- `delayMicroseconds `_\ () -- `Tutorial: Blink Without Delay `_ - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/min.rst b/source/arduino/min.rst deleted file mode 100644 index efe78ca..0000000 --- a/source/arduino/min.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. highlight:: cpp - -.. _arduino-min: - -min(x, y) -========= - -Description ------------ - -(Macro) Calculates the minimum of two numbers. - - - -Parameters ----------- - -**x**: the first number; may be any number or numeric expression. - -**y**: the second number; may be any number or numeric expression. - - -Returns -------- - -The smaller of the two numbers. - - -Example -------- - -:: - - sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 - // ensuring that it never gets above 100. - - -.. note:: Perhaps counter-intuitively, max() is often used to - constrain the lower end of a variable's range, while min() is used - to constrain the upper end of the range. - - -Warning -------- - -Because of the way ``min()`` is implemented, avoid using other -functions inside the parentheses. It may lead to incorrect results:: - - min(a++, 100); // avoid this - yields incorrect results - - a++; // use this instead - - min(a, 100); // keep other operations outside min() - -Arduino Compatibility ---------------------- - -The Maple version of ``min()`` is compatible with Arduino. - -See Also --------- - -- :ref:`max() ` -- :ref:`constrain() ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/modulo.rst b/source/arduino/modulo.rst deleted file mode 100644 index bb65600..0000000 --- a/source/arduino/modulo.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. highlight:: cpp - -.. _arduino-modulo: - -% (modulo) -========== - -Description ------------ - -Calculates the `remainder `_ -when one integer is divided by another. It is useful for keeping a -variable within a particular range (e.g. the size of an array). - -Syntax ------- - -:: - - result = dividend % divisor - - - -Parameters ----------- - -**dividend**: the number to be divided - -**divisor**: the number to divide by - -Returns -------- - -The remainder of **dividend**\ /\ **divisor**\ . - -Examples --------- - -:: - - int x; - x = 7 % 5; // x now contains 2 - x = 9 % 5; // x now contains 4 - x = 5 % 5; // x now contains 0 - x = 4 % 5; // x now contains 4 - -:: - - /* update one value in an array each time through a loop */ - - int values[10]; - int i = 0; - - void setup() { - // no setup necessary - } - - void loop() { - values[i] = analogRead(0); - i = (i + 1) % 10; // modulo operator makes sure i stays between 0 and 9 - } - -Tip ---- - -The modulo operator does not work on floats. For that, you can use -the C standard library function `fmod() -`_. - - -See Also --------- - -- :ref:`Arithmetic ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/nointerrupts.rst b/source/arduino/nointerrupts.rst deleted file mode 100644 index 8711ebb..0000000 --- a/source/arduino/nointerrupts.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _arduino-nointerrupts: - -noInterrupts() -============== - -Description ------------ - -Disables interrupts (you can re-enable them with interrupts()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None. - - - -Returns -------- - -None. - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `interrupts `_\ () - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/notone.rst b/source/arduino/notone.rst deleted file mode 100644 index 9e59065..0000000 --- a/source/arduino/notone.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _arduino-notone: - -noTone() -======== - -Description ------------ - -Stops the generation of a square wave triggered by -`tone `_\ (). Has no effect if -no tone is being generated. - - - -**NOTE:** if you want to play different pitches on multiple pins, -you need to call noTone() on one pin before calling tone() on the -next pin. - - - -Syntax ------- - -noTone(pin) - - - -Parameters ----------- - -pin: the pin on which to stop generating the tone - - - -Returns -------- - -nothing - - - -See also --------- - - -- `tone `_ () - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pinmode.rst b/source/arduino/pinmode.rst deleted file mode 100644 index e84e1e6..0000000 --- a/source/arduino/pinmode.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. highlight:: cpp - -.. _arduino-pinmode: - -pinMode() -========= - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: pinMode - -.. doxygenenum:: WiringPinMode - -Discussion ----------- - -pinMode() is usually called within :ref:`arduino-setup` in order to -configure a pin for a certain usage (although it may be called -anywhere). - - -Example -------- - - :: - - - int ledPin = 13; // LED connected to digital pin 13 - - void setup() - { - pinMode(ledPin, OUTPUT); // sets the digital pin as output - } - - void loop() - { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second - } - - - -Arduino Compatibility ---------------------- - -The libmaple implementation of pinMode() supports OUTPUT and INPUT -modes with a meaning identical to that of the Arduino function. - -INPUT_ANALOG and PWM modes were added because the Maple does not -distinguish between analog and digital pins the same way the Arduino -does. Unlike the Arduino, you **must call pinMode**\ () to set up a pin -for these purposes before a call to, e.g., :ref:`arduino-analogRead`. -In practice, this should only add a few lines of pinMode() calls to -your :ref:`arduino-setup` function. - -OUTPUT_OPEN_DRAIN, INPUT_PULLUP, INPUT_PULLDOWN, and PWM_OPEN_DRAIN -modes represent functionality not currently available on Arduino -boards. - -See also --------- - -- :ref:`arduino-constants` -- :ref:`arduino-digitalwrite` -- :ref:`arduino-digitalread` -- Maple :ref:`GPIO ` reference page - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pointer.rst b/source/arduino/pointer.rst deleted file mode 100644 index efc81ca..0000000 --- a/source/arduino/pointer.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _arduino-pointer: - -The pointer operators: & (reference) and \* (dereference) -========================================================= - - -Pointers are one of the more complicated subjects for beginners in -learning C, and it is possible to write the vast majority of -Arduino sketches without ever encountering pointers. However for -manipulating certain data structures, the use of pointers can -simplify the code, and and knowledge of manipulating pointers is -handy to have in one's toolkit. - -Introducing pointers is somewhat outside the scope of this -documentation. However, a good `pointer tutorial -`_ is available. -Also see the `Wikipedia article on pointers -`_, especially -the section on `pointers in C -`_. - -See Also -======== - -- http://xkcd.com/138/ - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pow.rst b/source/arduino/pow.rst deleted file mode 100644 index 0a7355c..0000000 --- a/source/arduino/pow.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _arduino-pow: - -pow(base, exponent) -=================== - -Calculates the value of a number raised to a power. - -Library Documentation ---------------------- - -.. doxygenfunction:: pow - -Example -------- - -``pow()`` can be used to raise a number to a fractional power. This -is useful for e.g. generating exponential mapping of values or -curves. See the `fscale `_ -function in the Arduino playground for more on this. - -See Also --------- - -- :ref:`sqrt() ` -- :ref:`float ` -- :ref:`double ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/pulsein.rst b/source/arduino/pulsein.rst deleted file mode 100644 index f26f754..0000000 --- a/source/arduino/pulsein.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _arduino-pulsein: - -pulseIn() -========= - -Description ------------ - -Reads a pulse (either HIGH or LOW) on a pin. For example, if -**value** is **HIGH**, **pulseIn()** waits for the pin to go -**HIGH**, starts timing, then waits for the pin to go **LOW** and -stops timing. Returns the length of the pulse in microseconds. -Gives up and returns 0 if no pulse starts within a specified time -out. - - - -The timing of this function has been determined empirically and -will probably show errors in longer pulses. Works on pulses from 10 -microseconds to 3 minutes in length. - - - -Syntax ------- - -pulseIn(pin, value) -pulseIn(pin, value, timeout) - - - -Parameters ----------- - -pin: the number of the pin on which you want to read the pulse. -(*int*) - - - -value: type of pulse to read: either -`HIGH `_ or -`LOW `_. (*int*) - - - -timeout (optional): the number of microseconds to wait for the -pulse to start; default is one second (*unsigned long*) - - - -Returns -------- - -the length of the pulse (in microseconds) or 0 if no pulse started -before the timeout (*unsigned long*) - - - -Example -------- - -:: - - - - int pin = 7; - unsigned long duration; - - void setup() - { - pinMode(pin, INPUT); - } - - void loop() - { - duration = pulseIn(pin, HIGH); - } - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/random.rst b/source/arduino/random.rst deleted file mode 100644 index 8da92b0..0000000 --- a/source/arduino/random.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. _arduino-random: - -random() -======== - -Description ------------ - -The random function generates pseudo-random numbers. - - - -Syntax ------- - -random(max) -random(min, max) - - - -Parameters ----------- - -min - lower bound of the random value, inclusive *(optional)* - - - -max - upper bound of the random value, exclusive - - - -Returns -------- - -a random number between min and max-1 (*long*) - - - -Note: ------ - -If it is important for a sequence of values generated by random() -to differ, on subsequent executions of a sketch, use randomSeed() -to initialize the random number generator with a fairly random -input, such as analogRead() on an unconnected pin. - - - -Conversely, it can occasionally be useful to use pseudo-random -sequences that repeat exactly. This can be accomplished by calling -randomSeed() with a fixed number, before starting the random -sequence. - - - -Example -------- - -:: - - long randNumber; - - void setup(){ - Serial.begin(9600); - - // if analog input pin 0 is unconnected, random analog - // noise will cause the call to randomSeed() to generate - // different seed numbers each time the sketch runs. - // randomSeed() will then shuffle the random function. - randomSeed(analogRead(0)); - } - - void loop() { - // print a random number from 0 to 299 - randNumber = random(300); - Serial.println(randNumber); - - // print a random number from 10 to 19 - randNumber = random(10, 20); - Serial.println(randNumber); - - delay(50); - } - - - -See also --------- - - -- `randomSeed `_\ () - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/randomseed.rst b/source/arduino/randomseed.rst deleted file mode 100644 index 983c66d..0000000 --- a/source/arduino/randomseed.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _arduino-randomseed: - -randomSeed(seed) -================ - -Description ------------ - -randomSeed() initializes the pseudo-random number generator, -causing it to start at an arbitrary point in its random sequence. -This sequence, while very long, and random, is always the same. - - - -If it is important for a sequence of values generated by random() -to differ, on subsequent executions of a sketch, use randomSeed() -to initialize the random number generator with a fairly random -input, such as analogRead() on an unconnected pin. - - - -Conversely, it can occasionally be useful to use pseudo-random -sequences that repeat exactly. This can be accomplished by calling -randomSeed() with a fixed number, before starting the random -sequence. - - - -Parameters ----------- - -long, int - pass a number to generate the seed. - - - -Returns -------- - -no returns - - - -Example -------- - -:: - - long randNumber; - - void setup(){ - Serial.begin(9600); - randomSeed(analogRead(0)); - } - - void loop(){ - randNumber = random(300); - Serial.println(randNumber); - - delay(50); - } - - - -See also --------- - - -- `random `_ - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/return.rst b/source/arduino/return.rst deleted file mode 100644 index fd1493d..0000000 --- a/source/arduino/return.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. highlight:: cpp - -.. _arduino-return: - -return -====== - -(Keyword) Terminates a function and return a value from a function to -the calling function, if the function has non-``void`` return type. - -Syntax: -------- - -:: - - // from within a "void" function: - return; - - // from within a non-"void" function: - return value; - -In the second case, ``value`` should have a type which is the same as -the return type of the function, or be convertible to it (like an -``int`` to a ``long``, etc.; see :ref:`this note -` for some references). - -Examples: ---------- - -A function to compare a sensor input to a threshold:: - - // converts analog readings between 0 and 400 to 0, and 400 up to 1. - int checkSensor() { - if (analogRead(0) > 400) { - return 1; - else { - return 0; - } - } - -An early ``return`` is also useful when testing a section of code -without having to "comment out" large sections of possibly buggy code, -like so:: - - void loop() { - - // brilliant code idea to test here - - return; - - // the rest of a dysfunctional sketch here - // this code will never be executed - } - -See Also --------- - -- :ref:`comments ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/scope.rst b/source/arduino/scope.rst deleted file mode 100644 index 5974825..0000000 --- a/source/arduino/scope.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. highlight:: cpp - -.. _arduino-scope: - -Variable Scope -============== - -Variables in the C++ programming language, which Maple uses (all of -your sketches are C++ programs in disguise), have a property called -*scope*. This is in contrast to languages such as BASIC where every -variable is a *global* variable. - -A global variable is one that can be "seen" by every function in a -program. Local variables are only usable within the function in which -they are declared. In the :ref:`Maple IDE `, any variable -declared outside of a function (like :ref:`setup() `, -:ref:`loop() `, etc.), is a global variable. - -When programs start to get larger and more complex, local variables -are a useful way to ensure that a function has exclusive access to its -own variables. This prevents programming errors when one function -inadvertently modifies variables used by another function. - -It is also sometimes useful to declare and initialize a variable -inside a :ref:`for ` loop. This creates a variable that -can only be accessed from inside the loop body. - -Scope in C++ is actually a fairly complex topic. More information is -available in the `C++ programming Wikibook -`_. - -Example: --------- - -:: - - int globalVar; // any function will see this variable - - void setup() { - // ... - } - - void loop() { - int i; // "i" is only "visible" inside of "loop" - float f; // "f" is only "visible" inside of "loop" - // ... - - for (int j = 0; j <100; j++){ - // variable j can only be accessed inside the for-loop brackets - i = j * j; - } - i = globalVar; // globalVar can be accessed from anywhere, including loop() - } - -See Also --------- - -- `C++ programming Wikibook `_. -- Wikipedia article on `scope `_ - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/semicolon.rst b/source/arduino/semicolon.rst deleted file mode 100644 index b90d925..0000000 --- a/source/arduino/semicolon.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. highlight:: cpp - -.. _arduino-semicolon: - -Semicolon (;) -============= - -Used to end a line of code. Example:: - - int a = 13; - -Tip ---- - -Forgetting to end a line in a semicolon will result in a compiler -error. The error text may be obvious, and refer to a missing -semicolon, or it may not. If an impenetrable or seemingly illogical -compiler error comes up, one of the first things to check is a -missing semicolon, in the immediate vicinity, preceding the line at -which the compiler complained. - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/serial.rst b/source/arduino/serial.rst deleted file mode 100644 index 1bcd28d..0000000 --- a/source/arduino/serial.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _arduino-serial: - -Serial -====== - -Used for communication between the Arduino board and a computer or -other devices. All Arduino boards have at least one serial port -(also known as a UART or USART): **Serial**. It communicates on -digital pins 0 (RX) and 1 (TX) as well as with the computer via -USB. Thus, if you use these functions, you cannot also use pins 0 -and 1 for digital input or output. - - - -You can use the Arduino environment's built-in serial monitor to -communicate with an Arduino board. Click the serial monitor button -in the toolbar and select the same baud rate used in the call to -begin(). - - - -The Arduino Mega has three additional serial ports: **Serial1** on -pins 19 (RX) and 18 (TX), **Serial2** on pins 17 (RX) and 16 (TX), -**Serial3** on pins 15 (RX) and 14 (TX). To use these pins to -communicate with your personal computer, you will need an -additional USB-to-serial adaptor, as they are not connected to the -Mega's USB-to-serial adaptor. To use them to communicate with an -external TTL serial device, connect the TX pin to your device's RX -pin, the RX to your device's TX pin, and the ground of your Mega to -your device's ground. (Don't connect these pins directly to an -RS232 serial port; they operate at +/- 12V and can damage your -Arduino board.) - - - -Functions ---------- - - -- `begin `_\ () -- `end `_\ () -- `available `_\ () -- `read `_\ () -- `flush `_\ () -- `print `_\ () - -.. _arduino-serial-println: - -- `println `_\ () -- `write `_\ () - - - -Examples --------- - - -- `ASCII Table `_ -- `Dimmer `_ -- `Graph `_ -- `Physical Pixel `_ -- `Virtual Color Mixer `_ -- `Serial Call Response `_ -- `Serial Call Response ASCII `_ - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/setup.rst b/source/arduino/setup.rst deleted file mode 100644 index 9cc96d4..0000000 --- a/source/arduino/setup.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _arduino-setup: - -setup() -======= - -The setup() function is called when a sketch starts. Use it to -initialize variables, pin modes, start using libraries, etc. The -setup function will only run once, after each powerup or reset of -the Arduino board. - - - -Example -~~~~~~~ - -:: - - - int buttonPin = 3; - - void setup() - { - Serial.begin(9600); - pinMode(buttonPin, INPUT); - } - - void loop() - { - // ... - } - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/shiftout.rst b/source/arduino/shiftout.rst deleted file mode 100644 index 3815dc5..0000000 --- a/source/arduino/shiftout.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. _arduino-shiftout: - -shiftOut() -========== - -Description ------------ - -Shifts out a byte of data one bit at a time. Starts from either the -most (i.e. the leftmost) or least (rightmost) significant bit. Each -bit is written in turn to a data pin, after which a clock pin is -pulsed to indicate that the bit is available. - - - -This is a software implementation; Arduino (as of 0019) also -provides an `SPI library `_ -that uses the hardware implementation. - - - -Syntax ------- - -shiftOut(dataPin, clockPin, bitOrder, value) - - - -Parameters ----------- - -dataPin: the pin on which to output each bit (*int*) - - - -clockPin: the pin to toggle once the **dataPin** has been set to -the correct value (*int*) - - - -bitOrder: which order to shift out the bits; either **MSBFIRST** or -**LSBFIRST**. -(Most Significant Bit First, or, Least Significant Bit First) - - - -value: the data to shift out. (*byte*) - - - -Returns -------- - -None - - - -Note ----- - -The **dataPin** and **clockPin** must already be configured as -outputs by a call to -`pinMode `_\ (). - - - -**shiftOut** is currently written to output 1 byte (8 bits) so it -requires a two step operation to output values larger than 255. - -:: - - // Do this for MSBFIRST serial - int data = 500; - // shift out highbyte - shiftOut(dataPin, clock, MSBFIRST, (data >> 8)); - // shift out lowbyte - shiftOut(data, clock, MSBFIRST, data); - - // Or do this for LSBFIRST serial - data = 500; - // shift out lowbyte - shiftOut(dataPin, clock, LSBFIRST, data); - // shift out highbyte - shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); - - - -Example -------- - -*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register `_.* - - - -:: - - //**************************************************************// - // Name : shiftOutCode, Hello World // - // Author : Carlyn Maw,Tom Igoe // - // Date : 25 Oct, 2006 // - // Version : 1.0 // - // Notes : Code for using a 74HC595 Shift Register // - // : to count from 0 to 255 // - //**************************************************************** - - //Pin connected to ST_CP of 74HC595 - int latchPin = 8; - //Pin connected to SH_CP of 74HC595 - int clockPin = 12; - ////Pin connected to DS of 74HC595 - int dataPin = 11; - - void setup() { - //set pins to output because they are addressed in the main loop - pinMode(latchPin, OUTPUT); - pinMode(clockPin, OUTPUT); - pinMode(dataPin, OUTPUT); - } - - void loop() { - //count up routine - for (int j = 0; j < 256; j++) { - //ground latchPin and hold low for as long as you are transmitting - digitalWrite(latchPin, LOW); - shiftOut(dataPin, clockPin, LSBFIRST, j); - //return the latch pin high to signal chip that it - //no longer needs to listen for information - digitalWrite(latchPin, HIGH); - delay(1000); - } - } - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/sin.rst b/source/arduino/sin.rst deleted file mode 100644 index b117f5f..0000000 --- a/source/arduino/sin.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _arduino-sin: - -sin() -===== - -Calculates the `sine `_ of an angle -(in radians). - -Library Documentation ---------------------- - -.. doxygenfunction:: sin - -Arduino Compatibility ---------------------- - -The Maple versino of ``sin()`` is compatible with Arduino. - -See Also --------- - -- :ref:`cos ` -- :ref:`tan ` -- :ref:`float ` -- :ref:`double ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/sizeof.rst b/source/arduino/sizeof.rst deleted file mode 100644 index 7c31809..0000000 --- a/source/arduino/sizeof.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. highlight:: cpp - -.. _arduino-sizeof: - -sizeof() -======== - -The ``sizeof`` operator on the Maple returns the number of bytes -needed to store a value of a given type\ [#fcharsize]_. This can be -an ordinary numeric type, like ``int``. It can be something more -complicated, like a ``struct`` or ``union``. If the argument to -``sizeof`` is an array, it returns the total number of bytes occupied -by the array. - -The general syntax looks like this:: - - sizeof(type) - sizeof(var) - -Example -------- - -The ``sizeof`` operator is useful for dealing with arrays (such as -strings) where it is convenient to be able to change the size of the -array without breaking other parts of the program. - -This program prints out a text string one character at a time. Try -changing the text phrase:: - - char myStr[] = "this is a test"; - int i; - - void setup() { - Serial.begin(9600); - } - - void loop() { - for (i = 0; i < sizeof(myStr) - 1; i++) { - Serial.print(i, DEC); - Serial.print(" = "); - Serial.println(myStr[i], BYTE); - } - } - - -Note that ``sizeof`` returns the total number of bytes. So for larger -variable types such as ``int``, the :ref:`for loop ` -would look something like this:: - - for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { - // do something with myInts[i] - } - -.. rubric:: Footnotes - -.. [#fcharsize] Technically (and pedantically) speaking, ``sizeof`` - returns a multiple of the number of bits a ``char`` occupies in - memory. However, on the Maple (this goes for most C++ - implementations), a ``char`` occupies 8 bits = 1 byte. All the C++ - standard guarantees, however, is that a ``char`` occupies at - *least* 8 bits. - -.. include:: cc-attribution.txt - diff --git a/source/arduino/sq.rst b/source/arduino/sq.rst deleted file mode 100644 index c918d50..0000000 --- a/source/arduino/sq.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. highlight:: cpp - -.. _arduino-sq: - -sq(a) -===== - -Description ------------ - -(Macro) computes the square of a number. - -Parameters ----------- - -**a**: the number. - -Returns -------- - -**a** squared (**a** × **a**). - -Warning -------- - -Because of the way ``sq()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - b = sq(a++); // avoid this - yields incorrect results - - b = sq(a); // use this instead - - a++; // keep other operations outside sq() - - -Arduino Compatibility ---------------------- - -Maple's implementation of ``sq()`` is compatible with Arduino. - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/sqrt.rst b/source/arduino/sqrt.rst deleted file mode 100644 index f93908e..0000000 --- a/source/arduino/sqrt.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _arduino-sqrt: - -sqrt() -====== - -Calculates the square root of a number. - -Library Documentation ---------------------- - -.. doxygenfunction:: sqrt - -Arduino Compatibility ---------------------- - -The Maple versino of ``sqrt()`` is compatible with Arduino. - -See Also --------- - -- :ref:`pow ` -- :ref:`sq ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/static.rst b/source/arduino/static.rst deleted file mode 100644 index 01f3dbf..0000000 --- a/source/arduino/static.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. highlight:: cpp - -.. _arduino-static: - -Static -====== - -The ``static`` keyword can be used to create variables that are -visible to only one function. However, unlike local variables that get -created and destroyed every time a function is called, ``static`` -variables persist beyond the function call, preserving their data -between function calls. - -Variables declared as ``static`` will only be created and initialized -the first time a function is called. - -.. note:: This is only one use of the ``static`` keyword in C++. It - has some other important uses that are not documented here; consult - a reliable C++ reference for details. - -Example -------- - -One use case for ``static`` variables is implementing counters that -last longer than the functions which need them, but shouldn't be -shared to other functions. Here's an example:: - - void setup() { - SerialUSB.begin(); - } - - void loop() { - int reading; - if (timeToReadSensors()) { - reading = readSensors(); - } - // do something with reading - } - - int readSensors() { - static int numSensorReadings = 0; - numSensorReadings++; - if (numSensorReadings % 100 == 0) { - SerialUSB.print("just got to another 100 sensor readings"); - } - return analogRead(...); - } - -In this example, the static variable ``numSensorReadings`` is -initialized to zero the first time ``readSensors()`` is called, and -then incremented, so it starts out at one. Subsequent calls to -``readSensors()`` won't reset ``numSensorReadings`` to zero, because -it was declared ``static``. Thus, ``numSensorReadings`` is a count of -the number of times that ``readSensors()`` has been called. - - -.. include:: cc-attribution.txt diff --git a/source/arduino/string.rst b/source/arduino/string.rst deleted file mode 100644 index 528e7de..0000000 --- a/source/arduino/string.rst +++ /dev/null @@ -1,131 +0,0 @@ -.. highlight:: cpp - -.. _arduino-string: - -Strings -======= - -Description ------------ - -Text strings can be represented in two ways. You can - -1. Use the :ref:`String ` data type, which is -part of the core as of version 0.0.9, or - -2. You can make a string out of an array of type :ref:`char -` and null-terminate it. - -This page describes the second method. - -Examples --------- - -All of the following are valid declarations for strings:: - - char str1[15]; - char str2[6] = {'m', 'a', 'p', 'l', 'e'}; - char str3[6] = {'m', 'a', 'p', 'l', 'e', '\0'}; - char str4[ ] = "maple"; - char str5[6] = "maple"; - char str6[15] = "maple"; - -As you can see, there are several methods available for declaring and -initializing strings: - -- Declare an array of ``char`` without initializing it, as with ``str1``. - -- Declare an array of ``char`` (with one extra ``char``) and the - compiler will add the required null character, as with ``str2``. - -- Explicitly add the null character (``'\0'``), as with ``str3``. - -- Initialize with a string constant in quotation marks (``"..."``); - the compiler will size the array to fit the string constant and a - terminating null character (``str4``). - -- Initialize the array with an explicit size and string constant, - (``str5``). - -- Initialize the array, leaving extra space for a larger string - (``str6``). - -Null Termination ----------------- - -Generally, strings are terminated with a null character (`ASCII -`_ code 0). This allows functions -(like ``SerialUSB.print()``) to tell where the end of a string is. -Otherwise, they would continue reading subsequent bytes of memory that -aren't actually part of the string. - -This means that your string needs to have space for one more character -than the text you want it to contain. That is why ``str2`` and -``str5`` need to be six characters, even though "maple" is only five --- the last position is automatically filled with a NULL -character. ``str4`` will be automatically sized to six characters, one -for the extra null. In the case of ``str3``, we've explicitly included -the null character (written ``'\0'``) ourselves. - -Note that it's possible to have a string without a final null -character (e.g. if you had specified the length of ``str2`` as five -instead of six). This will break most functions that use strings, so -you shouldn't do it intentionally. If you notice something behaving -strangely (operating on characters not in the string), however, this -could be the problem. - -Single quotes or double quotes? -------------------------------- - -Strings are always defined inside double quotes (``"Abc"``) and -characters are always defined inside single quotes (``'A'``). - -Wrapping long strings ---------------------- - -You can wrap long strings like this:: - - char myString[] = "This is the first line" - " this is the second line" - " etcetera"; - -Arrays of Strings ------------------ - -It is often convenient, when working with large amounts of text, -such as a project with an LCD display, to setup an array of -strings. Because strings themselves are arrays, this is in actually -an example of a two-dimensional array. - -In the code below, the asterisk after the datatype char ``char *`` -indicates that this is an array of "pointers". All array names are -actually pointers, so this is required to make an array of arrays. -Pointers are one of the more esoteric parts of C for beginners to -understand, but it isn't necessary to understand pointers in detail to -use them effectively here:: - - char* myStrings[] = {"This is string 1", "This is string 2", - "This is string 3", "This is string 4", - "This is string 5", "This is string 6"}; - - void setup() { - SerialUSB.begin(); - } - - void loop() { - for (int i = 0; i < 6; i++) { - SerialUSB.println(myStrings[i]); - delay(500); - } - } - - -See Also --------- - -- :ref:`array ` -- :ref:`__attribute__ ` -- :ref:`Variables ` - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/stringclass.rst b/source/arduino/stringclass.rst deleted file mode 100644 index ce508e7..0000000 --- a/source/arduino/stringclass.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _arduino-stringclass: - -String Class -============ - -Stub. - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/stringobject.rst b/source/arduino/stringobject.rst deleted file mode 100644 index 1844266..0000000 --- a/source/arduino/stringobject.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _arduino-stringobject: - -String -====== - -Description ------------ - -The String class, part of the core as of version 0019, allows you -to use and manipulate strings of text in more complex ways than -`character arrays `_ do. You -can concatenate Strings, append to them, search for and replace -substrings, and more. It takes more memory than a simple character -array, but it is also more useful. - - - -For reference, character arrays are referred to as strings with a -small s, and instances of the String class are referred to as -Strings with a capital S. Note that constant strings, specified in -"double quotes" are treated as char arrays, not instances of the -String class. - - - -Functions ---------- - - -- `String `_\ () -- `charAt `_\ () -- `compareTo `_\ () -- `concat `_\ () -- `endsWith `_\ () -- `equals `_\ () -- `equalsIgnoreCase `_\ () -- `getBytes `_\ () -- `indexOf `_\ () -- `lastIndexOf `_\ () -- `length `_\ () -- `replace `_\ () -- `setCharAt `_\ () -- `startsWith `_\ () -- `substring `_\ () -- `toCharArray `_\ () -- `toLowerCase `_\ () -- `toUpperCase `_\ () -- `trim `_\ () - - - -Operators ---------- - - -- `[] (element access) `_ -- `+ (concatenation) `_ -- `== (comparison) `_ - - - -Examples --------- - - -- `StringConstructors `_ -- `StringAdditionOperator `_ -- `StringIndexOf `_ -- `StringAppendOperator `_ -- `StringLengthTrim `_ -- `StringCaseChanges `_ -- `StringReplace `_ -- `StringCharacters `_ -- `StringStartsWithEndsWith `_ -- `StringComparisonOperators `_ -- `StringSubstring `_ - - - -See Also --------- - - -- `string `_: character - arrays -- `Variable Declaration `_ - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/switchcase.rst b/source/arduino/switchcase.rst deleted file mode 100644 index 9f66d0a..0000000 --- a/source/arduino/switchcase.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. highlight:: cpp - -.. _arduino-switchcase: - -switch / case statements -======================== - -Like :ref:`if/else ` blocks, A ``switch`` statement -controls program flow by allowing you to specify different code that -should be executed under various cases. - -The general syntax looks like this:: - - switch (var) { - case val1: - // statements - break; - case val2: - // statements - break; - ... - default: - // statements - } - -Where ``var`` is a variable whose value to investigate, and the -``val1``, ``val2`` after each ``case`` are constant values that -``var`` might be. - - -Description ------------ - -A ``switch`` statement compares the value of a variable to the values -specified in ``case`` statements. When a ``case`` statement is found -whose value matches that of the variable, the code in that case -statement is run. - -Here's a more concrete example:: - - switch (var) { - case 1: - doThing1(); - break; - case 2: - doThing2(); - break; - } - afterTheSwitch(); - -In the above example, if ``var == 1``, then the code beginning on the -line after ``case 1:`` gets executed. That is, if ``var`` is one, -``doThing1()`` gets called first, and then the ``break`` statement -gets executed. - -The ``break`` keyword exits the ``switch`` statement, and is typically -used at the end of each ``case``. Since there is a ``break`` at the -end of ``case 1:``, the ``switch`` statement gets exited, and the next -line to be run is the one which calls ``afterTheSwitch()``. - -Without a ``break``, the ``switch`` statement will continue executing -the following ``case`` expressions ("falling-through") until a -``break`` (or the end of the switch statement) is reached. Let's -pretend the ``switch`` looked like this instead:: - - switch (var) { - case 1: - doThing1(); - // no break statement anymore - case 2: - doThing2(); - break; - } - afterTheSwitch(); - -Now, if ``var`` is one, ``doThing1()`` gets executed like before. -However, without a ``break``, the code would continue to be executed -line-by-line, so ``doThing2()`` would be called next. At this point, -a ``break`` has been reached, so the program continues by calling -``afterTheSwitch()``. This is usually not what you want, which is why -each ``case`` usually has a ``break`` at the end. - -Writing "``default:``" instead of a ``case`` statement allows you to -specify what to do if none of the ``case`` statements matches. Having -a ``default`` is optional (you can leave it out), but if you have one, -it must appear after all of the ``case`` statements. Let's add a -``default`` to the ``switch`` we've been discussing:: - - switch (var) { - case 1: - doThing1(); - break; - case 2: - doThing2(); - break; - default: - doSomethingElse(); - } - afterTheSwitch(); - -If ``var`` is one, then ``doThing1()`` gets called. If ``var`` is -two, ``doThing2()`` gets called. If ``var`` is anything else, -``doSomethingElse()`` gets called. As stated above, a ``default`` is -optional. If you're missing one and none of the ``case`` statements -match, the ``switch`` does nothing at all, as if it wasn't there. - -``switch`` statements are often used with an ``enum`` value as the -variable to compare. In this case, you can write down all of the -values the ``enum`` takes as ``case`` statements, and be sure you've -covered all the possibilities. - -See also: ---------- - -- :ref:`if...else ` - -.. include:: cc-attribution.txt diff --git a/source/arduino/tan.rst b/source/arduino/tan.rst deleted file mode 100644 index f17ffcc..0000000 --- a/source/arduino/tan.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _arduino-tan: - -tan(rad) -======== - -Description ------------ - -Calculates the tangent of an angle (in radians). The result will be -between negative infinity and infinity. - - - -Parameters ----------- - -rad: the angle in radians (*float*) - - - -Returns -------- - -The tangent of the angle (*double*) - - - -See also --------- - - -- `sin `_\ () -- `cos `_\ () -- `float `_ -- `double `_ - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/tone.rst b/source/arduino/tone.rst deleted file mode 100644 index 8252804..0000000 --- a/source/arduino/tone.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. _arduino-tone: - -tone() -====== - -Description ------------ - -Generates a square wave of the specified frequency (and 50% duty -cycle) on a pin. A duration can be specified, otherwise the wave -continues until a call to -`noTone `_\ (). The pin can be -connected to a piezo buzzer or other speaker to play tones. - - - -Only one tone can be generated at a time. If a tone is already -playing on a different pin, the call to tone() will have no effect. -If the tone is playing on the same pin, the call will set its -frequency. - - - -Use of the tone() function will interfere with PWM output on pins 3 -and 11 (on boards other than the Mega). - - - -**NOTE:** if you want to play different pitches on multiple pins, -you need to call noTone() on one pin before calling tone() on the -next pin. - - - -Syntax ------- - -tone(pin, frequency) -tone(pin, frequency, duration) - - - -Parameters ----------- - -pin: the pin on which to generate the tone - - - -frequency: the frequency of the tone in hertz - - - -duration: the duration of the tone in milliseconds (optional) - - - -Returns -------- - -nothing - - - -See also --------- - - -- `noTone `_\ () -- `analogWrite `_\ () -- `Tutorial:Tone `_ -- `Tutorial:Pitch follower `_ -- `Tutorial:Simple Keyboard `_ -- `Tutorial: multiple tones `_ - - -- `Tutorial: PWM `_ - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/unsignedchar.rst b/source/arduino/unsignedchar.rst deleted file mode 100644 index 5c26d17..0000000 --- a/source/arduino/unsignedchar.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _arduino-unsignedchar: - -unsigned char -============= - -Description ------------ - -An unsigned data type that occupies 1 byte of memory. Same as the -`byte `_ datatype. - - - -The unsigned char datatype encodes numbers from 0 to 255. - - - -For consistency of Arduino programming style, the *byte* data type -is to be preferred. - - - -Example -------- - -:: - - unsigned char myChar = 240; - - - -See also --------- - - -- `byte `_ -- `int `_ -- `array `_ -- `Serial.println `_ - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/unsignedint.rst b/source/arduino/unsignedint.rst deleted file mode 100644 index 11412b1..0000000 --- a/source/arduino/unsignedint.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _arduino-unsignedint: - -unsigned int -============ - -Description ------------ - -Unsigned ints (unsigned integers) are the same as ints in that they -store a 2 byte value. Instead of storing negative numbers however -they only store positive values, yielding a useful range of 0 to -65,535 (2^16) - 1). - - - -The difference between unsigned ints and (signed) ints, lies in the -way the highest bit, sometimes refered to as the "sign" bit, is -interpreted. In the Arduino int type (which is signed), if the high -bit is a "1", the number is interpreted as a negative number, and -the other 15 bits are interpreted with -`2's complement math. `_ - - - -Example -------- - -:: - - unsigned int ledPin = 13; - - - -Syntax ------- - -:: - - unsigned int var = val; - - - - -- var - your unsigned int variable name -- val - the value you assign to that variable - - - -Coding Tip ----------- - -When variables are made to exceed their maximum capacity they "roll -over" back to their minimum capacitiy, note that this happens in -both directions - - - -:: - - unsigned int x - x = 0; - x = x - 1; // x now contains 65535 - rolls over in neg direction - x = x + 1; // x now contains 0 - rolls over - - - -See Also --------- - - -- `byte `_ -- `int `_ -- `long `_ -- `unsigned long `_ -- `Variable Declaration `_ - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/unsignedlong.rst b/source/arduino/unsignedlong.rst deleted file mode 100644 index c493c40..0000000 --- a/source/arduino/unsignedlong.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _arduino-unsignedlong: - -unsigned long -============= - -Description ------------ - -Unsigned long variables are extended size variables for number -storage, and store 32 bits (4 bytes). Unlike standard longs -unsigned longs won't store negative numbers, making their range -from 0 to 4,294,967,295 (2^32 - 1). - - - -Example -------- - -:: - - unsigned long time; - - void setup() - { - Serial.begin(9600); - } - - void loop() - { - Serial.print("Time: "); - time = millis(); - //prints time since program started - Serial.println(time); - // wait a second so as not to send massive amounts of data - delay(1000); - } - -Syntax ------- - -:: - - unsigned long var = val; - - - - -- var - your long variable name -- val - the value you assign to that variable - - - -See Also --------- - - -- `byte `_ -- `int `_ -- `unsigned int `_ -- `long `_ -- `Variable Declaration `_ - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/variables.rst b/source/arduino/variables.rst deleted file mode 100644 index 0720041..0000000 --- a/source/arduino/variables.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. highlight:: cpp - -.. _arduino-variables: - -Variables ---------- - -A variable is a way of naming and storing a value for later use by -the program, such as data from a sensor or an intermediate value -used in a calculation. - -.. _arduino-variables-declaring: - -Declaring Variables -^^^^^^^^^^^^^^^^^^^ - -Before they are used, all variables have to be declared. Declaring -a variable means defining its type, and optionally, setting an -initial value (initializing the variable). Variables do not have to -be initialized (assigned a value) when they are declared, but it is -often useful. - - - -:: - - int inputVariable1; - int inputVariable2 = 0; // both are correct - - - -Programmers should consider the size of the numbers they wish to -store in choosing variable types. Variables will -`roll over <#VariableRollover>`_ when the value stored exceeds the -space assigned to store it. See below for an example. - -.. _arduino-variables-scope: - -Variable Scope -^^^^^^^^^^^^^^ - -Another important choice that programmers face is where to declare -variables. The specific place that variables are declared -influences how various functions in a program will *see* the -variable. This is called variable -`scope `_. - -.. _arduino-variables-initializing: - -Initializing Variables -^^^^^^^^^^^^^^^^^^^^^^ - -Variables may be *initialized* (assigned a starting value) when -they are declared or not. It is always good programming practice -however to double check that a variable has valid data in it, -before it is accessed for some other purpose. - - - -Example: - -:: - - int calibrationVal = 17; // declare calibrationVal and set initial value - -.. _arduino-variables-rollover: - -Variable Rollover -^^^^^^^^^^^^^^^^^ - -When variables are made to exceed their maximum capacity they "roll -over" back to their minimum capacity, note that this happens in -both directions. - - - -:: - - int x - x = -32,768; - x = x - 1; // x now contains 32,767 - rolls over in neg. direction - - - -:: - - x = 32,767; - x = x + 1; // x now contains -32,768 - rolls over - - - -Using Variables -^^^^^^^^^^^^^^^ - -Once variables have been declared, they are used by setting the -variable equal to the value one wishes to store with the -`assignment operator `_ -(single equal sign). The assignment operator tells the program to -put whatever is on the right side of the equal sign into the -variable on the left side. - - - -:: - - inputVariable1 = 7; // sets the variable named inputVariable1 to 7 - inputVariable2 = analogRead(2); // sets the variable named inputVariable2 to the - // (digitized) input voltage read from analog pin #2 - - - -Examples -^^^^^^^^ - -:: - - int lightSensVal; - char currentLetter; - unsigned long speedOfLight = 186000UL; - char errorMessage = {"choose another option"}; // see string - - - -Once a variable has been set (assigned a value), you can test its -value to see if it meets certain conditions, or you can use its -value directly. For instance, the following code tests whether the -inputVariable2 is less than 100, then sets a delay based on -inputVariable2 which is a minimum of 100: - - - -:: - - if (inputVariable2 < 100) - { - inputVariable2 = 100; - } - - delay(inputVariable2); - - - -This example shows all three useful operations with variables. It -tests the variable ( ``if (inputVariable2 < 100)`` ), it sets the -variable if it passes the test ( ``inputVariable2 = 100`` ), and it -uses the value of the variable as an input parameter to the delay() -function (``delay(inputVariable2)`` ) - - - -**Style Note:** You should give your variables descriptive names, -so as to make your code more readable. Variable names like -**tiltSensor** or **pushButton** help you (and anyone else reading -your code) understand what the variable represents. Variable names -like **var** or **value**, on the other hand, do little to make -your code readable. - - - -You can name a variable any word that is not already one of the -`keywords `_`? `_ -in Arduino. Avoid beginning variable names with numeral -characters. - - - -Some variable types -^^^^^^^^^^^^^^^^^^^ - - -- `char `_ -- `byte `_ -- `int `_ -- `unsigned int `_ -- `long `_ -- `unsigned long `_ -- `float `_ -- `double `_ - - - -Variable Scope -^^^^^^^^^^^^^^ - - -- `Variable Scope `_ - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/void.rst b/source/arduino/void.rst deleted file mode 100644 index 82f9606..0000000 --- a/source/arduino/void.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _arduino-void: - -void -==== - -The void keyword is used only in function declarations. It -indicates that the function is expected to return no information to -the function from which it was called. - - - -Example: --------- - -:: - - // actions are performed in the functions "setup" and "loop" - // but no information is reported to the larger program - - void setup() - { - // ... - } - - void loop() - { - // ... - } - - - - -See also --------- - -`function declaration `_ - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/volatile.rst b/source/arduino/volatile.rst deleted file mode 100644 index fc02081..0000000 --- a/source/arduino/volatile.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _arduino-volatile: - -volatile keyword -================ - -volatile is a keyword known as a variable *qualifier*, it is -usually used before the datatype of a variable, to modify the way -in which the compiler and subsequent program treats the variable. - - - -Declaring a variable volatile is a directive to the compiler. The -compiler is software which translates your C/C++ code into the -machine code, which are the real instructions for the Atmega chip -in the Arduino. - - - -Specifically, it directs the compiler to load the variable from RAM -and not from a storage register, which is a temporary memory -location where program variables are stored and manipulated. Under -certain conditions, the value for a variable stored in registers -can be inaccurate. - - - -A variable should be declared volatile whenever its value can be -changed by something beyond the control of the code section in -which it appears, such as a concurrently executing thread. In the -Arduino, the only place that this is likely to occur is in sections -of code associated with interrupts, called an interrupt service -routine. - - - -Example -------- - -:: - - // toggles LED when interrupt pin changes state - - int pin = 13; - volatile int state = LOW; - - void setup() - { - pinMode(pin, OUTPUT); - attachInterrupt(0, blink, CHANGE); - } - - void loop() - { - digitalWrite(pin, state); - } - - void blink() - { - state = !state; - } - - - -See also --------- - - -- `AttachInterrupt `_ - - - - -.. include:: cc-attribution.txt diff --git a/source/arduino/while.rst b/source/arduino/while.rst deleted file mode 100644 index e8167bd..0000000 --- a/source/arduino/while.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _arduino-while: - -while Loops -=========== - -Description ------------ - -**while** loops will loop continuously, and infinitely, until the -expression inside the parenthesis, () becomes false. Something must -change the tested variable, or the **while** loop will never exit. -This could be in your code, such as an incremented variable, or an -external condition, such as testing a sensor. - - - -Syntax ------- - -:: - - while(expression){ - // statement(s) - } - - - -Parameters ----------- - -expression - a (boolean) C statement that evaluates to true or -false - - - -Example -------- - -:: - - var = 0; - while(var < 200){ - // do something repetitive 200 times - var++; - } - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/word.rst b/source/arduino/word.rst deleted file mode 100644 index 32506b8..0000000 --- a/source/arduino/word.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _arduino-word: - -word -==== - -Description ------------ - -A word stores a 16-bit unsigned number, from 0 to 65535. Same as an -unsigned int. - - - -Example -------- - -:: - - word w = 10000; - - - -See also --------- - - -- `byte `_ -- `word `_\ () - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/arduino/wordcast.rst b/source/arduino/wordcast.rst deleted file mode 100644 index 1e854ba..0000000 --- a/source/arduino/wordcast.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _arduino-wordcast: - -word() -====== - -Description ------------ - -Convert a value to the -`word `_ data type or create a -word from two bytes. - - - -Syntax ------- - -word(x) -word(h, l) - - - -Parameters ----------- - -x: a value of any type - - - -h: the high-order (leftmost) byte of the word - - - -l: the low-order (rightmost) byte of the word - - - -Returns -------- - -word - - - -See also --------- - - -- `word `_ - - - - -.. include:: cc-attribution.txt \ No newline at end of file diff --git a/source/bootloader.rst b/source/bootloader.rst index 46c2cf0..6cb9ece 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -226,12 +226,12 @@ A bootloader packet is composed of a sequence of fields, as follows. - 1 - 0--0xFF - Queries and responses must have the same sequence number; rolls - over to 0 after 0xFF. + over to 0 after 0xFF * - MESSAGE_SIZE - 2 - 0--0xFFFF - - Size of message body, currently limited to a 1024B maximum + - Size of message body, currently limited to a 1024B=1KB maximum * - TOKEN - 1 @@ -241,14 +241,32 @@ A bootloader packet is composed of a sequence of fields, as follows. * - MESSAGE_BODY - Variable, determined by MESSAGE_SIZE field - Command query or response - - See next section + - See :ref:`next section ` * - CHECKSUM - 4 - XOR of all other 32-bit words in packet - - Words are checksummed little-endian; however, like all - multi-byte fields, the CHECKSUM is transmitted between PC and - device in network (big-endian) order. + - See :ref:`below ` + +.. _bootloader-checksum: + +.. highlight:: cpp + +.. note:: When computing the checksum, the words in a packet are + interpreted big-endian (as if the packet were a sequence of 32-bit, + big-endian unsigned integers). If the end of the MESSAGE_BODY is + not aligned with a four-byte boundary, then the checksum will treat + it as if it was padded with zero bytes to a four-byte boundary. + + As a concrete example, an entire GET_INFO query (see :ref:`below + `), including the packet structure, is + comprised of the byte sequence :: + + {0x1B, 0x7F, 0x00, 0x01, 0x7F, 0x00, 0x64, 0x7F, 0x00, 0x01} + + The SEQUENCE_NUM of this query is 0x7F. + +.. highlight:: sh .. _bootloader-commands: @@ -256,15 +274,16 @@ Commands ^^^^^^^^ The packet structure overhead is for reliability. The actual queries -and responses are transacted inside of the message body. Following in -the footsteps of the STK-500 protocol, each query or response begins -with the single byte CMD field. For each query, the resultant response -must begin with the same CMD byte. For each type of CMD, the structure -of queries and responses is of fixed size. Following STK-500, fields -longer than 1 byte are transmitted MSB first (big-endian). However, -READ and WRITE commands operate byte-wise (not word-wise); it is up to -the host PC to ensure that alignment and ordering issues are handled -appropriately. +and responses are transacted inside of the message body. Following +the STK-500 protocol, each query or response begins with the single +byte command field. For each query, the resultant response must begin +with the same CMD byte. For each type of command, the structure of +queries and responses is of fixed size. + +Also following STK-500, fields longer than 1 byte are transmitted MSB +first (big-endian). However, READ and WRITE commands operate byte-wise +(not word-wise); it is up to the host PC to ensure that alignment and +ordering issues are handled appropriately. .. _bootloader-get-info: @@ -447,7 +466,7 @@ READ_BYTES query: * - LENGTH - 2 - Maximum number of bytes to read (currently, this may be at most - 512). Must be a multiple of 4. + 1024 = 1KB). Must be a multiple of 4. READ_BYTES response: diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index 39828e3..79492ef 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -76,7 +76,7 @@ The following table shows which pins can be used on which lines. .. note:: - You should set the :ref:`pin mode ` of your + You should set the :ref:`pin mode ` of your desired pin to an input mode (e.g ``INPUT`` or ``INPUT_FLOATING``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``). diff --git a/source/foo.rst b/source/foo.rst deleted file mode 100644 index 1da021c..0000000 --- a/source/foo.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. _foo: - -================================== -[temporary] Converted Arduino docs -================================== - -This is the index of the imported Arduino docs. - -Finished: - -.. toctree:: - :maxdepth: 1 - - abs() - analogRead() - pinMode() - Arithmetic - Arrays - Assignment - attachInterrupt() - bit() - bitClear() - bitRead() - bitSet() - arduino/bitshift - arduino/analogwrite - arduino/bitwisemath - arduino/bitwisecompound - bitWrite() - arduino/boolean - arduino/booleanvariables - arduino/braces - arduino/break - arduino/byte - arduino/bytecast - arduino/char - arduino/charcast - arduino/comments - arduino/const - constrain() - arduino/continue - cos() - #define - arduino/delay - arduino/delaymicroseconds - arduino/detachinterrupt - arduino/digitalread - arduino/double - arduino/doublecast - arduino/dowhile - arduino/else - arduino/float - arduino/floatcast - arduino/for - arduino/goto - arduino/highbyte - arduino/if - arduino/comparison - arduino/include - arduino/increment - arduino/arithmeticcompound - arduino/int - arduino/intcast - arduino/long - arduino/longcast - arduino/loop - arduino/max - arduino/min - arduino/modulo - arduino/pointer - arduino/pow - arduino/return - arduino/scope - arduino/semicolon - arduino/sin - arduino/sizeof - arduino/sqrt - arduino/sq - arduino/static - arduino/string - -Unfinished; straightforward to convert: - -.. toctree:: - :maxdepth: 1 - - arduino/switchcase - arduino/tan - arduino/unsignedchar - arduino/unsignedint - arduino/unsignedlong - arduino/variables - arduino/void - arduino/volatile - arduino/while - -Unfinished, requires libmaple/Arduino knowledge: - -.. toctree:: - :maxdepth: 1 - - arduino/word - arduino/wordcast - arduino/constants - arduino/digitalwrite - arduino/notone - arduino/serial - arduino/interrupts - analogWrite() - arduino/nointerrupts - arduino/pulsein - arduino/stringobject - arduino/tone - arduino/random - arduino/randomseed - arduino/setup - arduino/map - arduino/shiftout - arduino/micros - arduino/millis - arduino/lowbyte - arduino/stringclass diff --git a/source/ide.rst b/source/ide.rst index c8dbd74..00dcf03 100644 --- a/source/ide.rst +++ b/source/ide.rst @@ -5,7 +5,19 @@ Maple IDE Documentation Stub. +.. TODO stub sections for all the other buttons, etc. + .. _ide-serial-monitor: Serial Monitor -------------- + +.. _ide-verify: + +Verify +------ + +.. _ide-upload: + +Upload +------ diff --git a/source/index.rst b/source/index.rst index ac91c4f..32fa28f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,17 +3,22 @@ Maple Documentation Index ========================= -Welcome! This is the documentation index for programming your Maple. -It contains tutorials, quickstarts, and technical documentation. +Welcome! This is the Maple documentation index. It contains +tutorials, quickstarts, and technical documentation. If you just got a new Maple, you probably want to begin with the :ref:`quickstart `. You can then move on to reading about the programming language you use with the Maple at the -:ref:`language reference `. Good luck, and have fun! +:ref:`language reference `. + +If you're having problems, you might want to visit the +:ref:`troubleshooting ` and :ref:`known problems +` pages. Finally, you can always hit the `forums +`_ to ask questions to the LeafLabs team +and other Maple users. Good luck, and have fun! Table of contents: -.. TODO: be more Pythonic with a "parts of the documentation" thing .. toctree:: :maxdepth: 1 @@ -29,8 +34,7 @@ Table of contents: External Interrupts Bootloader Known Problems - [Temporary] Arduino docs TOC - [Temporary] Wirish-only docs TOC + Language Reference Index Indices and tables ================== diff --git a/source/lang/abs.rst b/source/lang/abs.rst new file mode 100644 index 0000000..ed95e6f --- /dev/null +++ b/source/lang/abs.rst @@ -0,0 +1,42 @@ +.. _lang-abs: + +abs(x) +====== + +Description +----------- + +(Macro) computes the absolute value of a number. + +Parameters +---------- + +**x**: the number. + +Returns +------- + +**x**: if **x** is greater than or equal to 0. + +**-x**: if **x** is less than 0. + +Warning +------- + +Because of the way ``abs()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + abs(a++); // avoid this - yields incorrect results + + abs(a); // use this instead - + a++; // keep other operations outside abs() + + +Arduino Compatibility +--------------------- + +Maple's implementation of ``abs()`` is compatible with Arduino. + + +.. include:: cc-attribution.txt diff --git a/source/lang/analogread.rst b/source/lang/analogread.rst new file mode 100644 index 0000000..0c93650 --- /dev/null +++ b/source/lang/analogread.rst @@ -0,0 +1,152 @@ +.. highlight:: cpp + +.. _lang-analogread: + +analogRead() +============ + +Used to perform ADC conversion. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: analogRead + +Discussion +---------- + +Reads the value from the specified analog pin. The Maple board +contains a 16-channel, 12-bit analog to digital converter. This means +that it will map input voltages between 0 and 3.3 volts into integer +values between 0 and 4095. This yields a resolution between readings +of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors +interfere with getting full accuracy and precision. For more +information, see :ref:`adc`. + +Before calling analogRead() on a pin, that pin must first be +configured for analog input, using :ref:`lang-pinMode` (you only +have to do this once, so it's usually done in :ref:`lang-setup`\ ). + +It takes about 0.8 microseconds (.0000008 seconds) to read an analog +input, so the maximum sample rate using this function is approximately +1.3 million samples per second\ [#fsamp]_. + + +Parameter Discussion +-------------------- + +The pin parameter is the number of the analog input pin to read from. +Header pins on the Maple with ADC functionality (marked as "AIN" on +the silkscreen) are: + + 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 + +Note that pins 3, 27, and 28 are not marked AIN on the silkscreen +for Maple revisions through Rev 5, however, they **do work** as +analog input pins. + +Note +---- + +If the analog input pin is not connected to anything, the value +returned by analogRead() will fluctuate based on a number of factors +(e.g. the values of the other analog inputs, how close your hand is to +the board, etc.) in a seemingly random way. + + +Example +------- + + :: + + + int analogPin = 3; // potentiometer wiper (middle terminal) connected + // to analog pin 3. outside leads to ground and +3.3V + int val = 0; // variable to store the value read + + void setup() { + pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input + SerialUSB.begin(); // set up usb virtual COM port + } + + void loop() { + val = analogRead(analogPin); // read the input pin + SerialUSB.println(val); // print the value, for debugging with + // a serial monitor + } + + +Arduino Compatibility +--------------------- + +The Arduino board contains a 6 channel (8 channels on the Mini and +Nano, 16 on the Mega), 10-bit analog to digital converter with an +input voltage range of 0V--5V. This means that it will map input +voltages between 0 and 5 volts (which is **larger** than Maple's range +of 0V-3.3V) into integer values between 0 and 1023 (which is +**smaller** than the Maple's range of 0--4095). + +This yields a theoretical resolution between readings of: 5 volts / +1024 units or .0049 volts (4.9 mV) per unit on Arduino boards, which +is larger, and thus less precise, than Maple's 0.0008 volts (0.8 mV). + +If your program expects Arduino-style 10-bit ADC, you can :ref:`right +shift ` the value of a Maple readout by 2, like so:: + + // right shift means that the result will be between 0 and 1023; + // be aware that you're losing a lot of precision if you do this + int adc_reading = analogRead(pin) >> 2; + +On the Arduino, the input range and resolution can be changed using +their implementation of `analogReference() +`_\ . Because of the +way its hardware (as of Rev 5) was designed, it's not possible to +implement analogReference on the Maple, so this function doesn't +exist. If your inputs lie in a different voltage range than 0V--3.3V, +you'll need to bring them into that range before using analogRead. +Some basic tools to accomplish this are `resistor dividers +`_ and `Zener diodes +`_\ +. However, opamps and other powered components can also be used if +greater precision is required. + +Finally, On the Arduino, it takes significantly longer to read analog +input: about 100 microseconds (0.0001 s), so the maximum reading rate +is 10,000 times a second. + + +See also +-------- + +- :ref:`ADC note ` +- `(Arduino) Tutorial: Analog Input Pins `_ + + +.. rubric:: Footnotes + +.. [#fsamp] This is based on the current configuration of a 55.5 cycle + sample time, at 72 MHz. However, the minimum sample time *possible* + is 1.5 cycles, leading to a theoretical maximum of approximately 48 + million samples per second (of course, doing anything with the + readings also consumes cycles, so this maximum can't be reached in + practice). + + See the `STM32 Reference Manual `_, §§11.12.4--5 + (pp. 225--226), for more information on the low-level bit twiddling + currently necessary to change the sample time. For examples of how + the ADCs are configured in libmaple, see `adc.h + `_ + and `adc.c + `_\ + . Be aware that changing the sample time has important + consequences related to the impedance of the device connected to + the input pin. If you want to make changes, as a minimum, you + should first read ST's application notes on `ADC modes + `_ and `ADC oversampling + `_. + + +.. include:: cc-attribution.txt diff --git a/source/lang/analogwrite.rst b/source/lang/analogwrite.rst new file mode 100644 index 0000000..d30d4d9 --- /dev/null +++ b/source/lang/analogwrite.rst @@ -0,0 +1,164 @@ +.. highlight:: cpp + +.. _lang-analogwrite: + +analogWrite() +============= + +.. note:: + + On the Maple, calling analogWrite() is the same as calling + :ref:`lang-pwmwrite`\ ; see that function's documentation for more + information. + + This is because PWM is not true analog output (i.e., is not the + output of a `DAC + `_\ ), so + the function is badly named. For instance, **analogWrite() has + absolutely nothing to do with** :ref:`lang-analogread`\ , which is + potentially confusing. + + The alias of analogWrite() to pwmWrite() is provided (sigh) for the + sake of compatibility with Arduino, but we recommend using + :ref:`lang-pwmwrite` when writing new software, for clarity. + +.. contents:: Contents + :local: + +Arduino Compatibility +--------------------- + +There are a few important differences between Arduino's `analogWrite() +`_ and Maple's +:ref:`lang-pwmwrite` that you should keep in mind. In each case, we +have some recommendations you can use to help converting from Arduino +to Maple. + +Difference 1: Duty cycle range is different +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first and most important difference is that the largest possible +value for the duty cycle is much bigger on the Maple. Using Arduino's +analogWrite(), the duty cycle ranges between 0--255 (always off -- +always on)\ [#fbytemax]_\ . Using Maple's pwmWrite(), the duty cycle +ranges from 0--65,535 by default\ [#fuint16max]_\ . + +This is a good thing! The greater range of values on the Maple gives +you much more precise control over the duty cycle of your PWM output. + +If you're porting code from the Arduino and want a quick-and-dirty +fix, one solution is to :ref:`map ` the argument to +analogWrite into the right range:: + + // Arduino code: + analogWrite(pin, duty); + + // Becomes Maple code: + analogWrite(pin, map(duty, 0, 255, 0, 65535)); + +This will convert values in the range 0-255 to values in the range +0--65,635, which is the correct default range for all of the timers +which control PWM output. See the :ref:`timers reference ` +for more information. + +Another fix is to consult the :ref:`pin mapping mega table +` to find the timer which controls PWM on the +pin you're using, then set that Timer's overflow to 255. Subsequent +calls to analogWrite() should work as on the Arduino (with the same +loss of precision). Note, however, that that affects the overflow for +the **entire timer**, so other code relying on that timer (such as any +:ref:`interrupts ` the timer controls) will +likely need to be modified as well. + +Difference 2: You must use pinMode() to set up PWM +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The second difference is that on the Maple, you **must** set up the pin +for PWM output using :ref:`lang-pinmode`\ , with argument ``PWM``. +This should just be one extra line of code in your +:ref:`lang-setup` function. Example:: + + void setup() { + // set up pin 9 for PWM + pinMode(9, PWM); + } + +This also means that you can't later call :ref:`lang-digitalread` +or :ref:`lang-digitalwrite` on that pin (unless some time in +between, you use pinMode() to reconfigure that pin for ``INPUT`` or +``OUTPUT``; see the :ref:`lang-pinmode` page for more information). + +Difference 3: No PWM on pin 10 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, +9, 11, 12, and 14, or twelve pins in total. That is at least as +*many* PWM pins as any Arduino board, but there are differences in +*which* pins support it. + +* On **most Arduino boards** (those with the ATmega168 or ATmega328; + this includes the **Arduino Uno**), this function works on pins 3, + 5, 6, 9, 10, and 11, or six pins total. Note that these boards + support PWM on pin 10, while Maple does not. + +* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins + total. Note that this board supports PWM on pins 4, 10, and 13, + while the Maple does not. Maple supports PWM on pins 0, 1, and 14, + which the Mega does not, making the total number of pins supporting + PWM equal on these boards. + +* **Older Arduino boards** with an ATmega8 only support analogWrite() on + pins 9, 10, and 11. Maple does not support PWM on pin 10. + +In all cases, Arduino boards support PWM on pin 10, unlike Maple. We +did our best to make PWM as pin-compatible as possible; however, +circuit layout constraints prevented us from achieving perfect +compatibility. + +The "safest" pins to use for PWM output are pins 9 and 11. These pins +work on any Arduino board and on Maple. The "safe" pins, which work +on most recent Arduino boards, the Arduino Mega and the Maple, are +pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as +portable as possible between Maple and Arduino, we recommend using the +"safest" pins first, then the "safe" pins, as necessary. + +Difference 4: PWM frequency +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The frequency of the PWM signal (i.e., the frequency of a complete +on/off cycle) on the Arduino is approximately 490 Hz. + +On the Maple, the frequency is configurable, defaulting to about 1100 +Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of +the timer which controls PWM output on the particular pin (\ +:ref:`the PWM tutorial has the details `\ ). + +If your application absolutely requires Arduino's PWM frequency (it +probably doesn't), then the steps are: + +1. Figure out which timer controls PWM output on your pin (\ :ref:`this table ` is your friend here). Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4. + +2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of approximately 490 Hz. + +Be aware that this will change the period for the **entire timer**\ , +and will affect anything else in your program that depends on that +timer. One example is :ref:`interrupts `\ . +You've been :ref:`warned `\ . + +See also +-------- + +- :ref:`Maple PWM tutorial ` + +.. rubric:: Footnotes + +.. [#fbytemax] This is because the value for the duty cycle on Arduino + must fit in 1 byte of memory, and an unsigned (i.e., nonnegative) + integer with size 1 byte can hold the values between 0 and 255. + +.. [#fuint16max] This is because the value for the duty cycle on the + Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) + integer with size 2 bytes can hold the values between 0 and 65,535. + + +.. include:: cc-attribution.txt diff --git a/source/lang/arithmetic.rst b/source/lang/arithmetic.rst new file mode 100644 index 0000000..9f21627 --- /dev/null +++ b/source/lang/arithmetic.rst @@ -0,0 +1,129 @@ +.. highlight:: cpp + +.. _lang-arithmetic: + +Addition, Subtraction, Multiplication, & Division +================================================= + +.. contents:: Contents + :local: + +Description +----------- + +These operators return the sum, difference, product, or quotient +(respectively) of the two operands. The operation is conducted using +the data type of the operands, so, for example, ``9 / 4`` gives ``2`` +since 9 and 4 are :ref:`int variables `. + +This also means that the operation can overflow if the result is +larger than that which can be stored in the data type (e.g. adding 1 +to an :ref:`lang-int` with the value 2147483647 gives +-2147483648). If the operands are of different types, the "larger" +type is used for the calculation. + +.. _lang-arithmetic-typeconversion: + +.. note:: The specifics of these rules are beyond the scope of this + documentation; for more information, see `The C++ Programming + Language `_\ , by Bjarne + Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks + entry on C++ type conversion + `_. + +.. note:: For more information on how computers represent integers, + see the Wikipedia page on `two's complement + `_. + +If one of the numbers (operands) are of the type **float** or of type +**double**, floating point math will be used for the +calculation. + +Examples +-------- + + :: + + y = y + 3; + x = x - 7; + i = j * 6; + r = r / 5; + + +Syntax +------ + + :: + + result = value1 + value2; + result = value1 - value2; + result = value1 * value2; + result = value1 / value2; + + +Parameters +---------- + +**value1**: any numeric variable or constant + +**value2**: any numeric variable or constant + +Programming Tips +---------------- + +- Know that :ref:`integer constants ` + default to :ref:`int `, so some constant calculations + may overflow (e.g., 200000 * 5000000 will yield a negative result). + +- Choose variable sizes that are large enough to hold the largest + results from your calculations. + +- Know at what point your variable will "roll over" and also what + happens in the other direction e.g. (0 - 1) for unsigned arithmetic, + or (0 - -2,147,483,648) for signed arithmetic. + +- For math that requires fractions, float variables may be used, but + be aware of their drawbacks: large size and slow computation speeds + (the STM32 has no floating point hardware, so all floating point + calculations have to be done in software). + +- Use cast operator, e.g. ``(int)myFloat`` to convert one variable type + to another on the fly. + +Arduino Compatibility +--------------------- + +Since the STM32 processor on the Maple is a 32-bit machine, the int +type overflows at a much higher value on Maple than on Arduino. In +particular, on Maple, ints do not overflow (become negative) until +they reach 2,147,483,648; on the Arduino, they overflow at 32,767. +Because of this, programs running on Maple are much less likely to run +into overflow issues. The following table summarizes the sizes and +ranges of integer datatypes on the Maple (the ranges of long long +types are approximate): + +.. _lang-arithmetic-int-sizes: + +.. csv-table:: + :header: Datatype, Unsigned range, Signed range, Size (bytes) + :widths: 8, 12, 17, 8 + + ``char``, 0 --- 255, -128 --- 127, 1 + ``short``, "0 --- 65,535", "-32,768 --- 32,767", 2 + ``int``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 + ``long``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 + ``long long``, "0 --- 1.8*10\ :sup:`19`\ " (approx.), "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 + + +See Also +-------- + +- The individual sizes (in bits) of various available types are + defined in `libmaple_types.h + `_\ + . + +- :ref:`sizeof `\ () + + +.. include:: cc-attribution.txt diff --git a/source/lang/arithmeticcompound.rst b/source/lang/arithmeticcompound.rst new file mode 100644 index 0000000..aa0dc18 --- /dev/null +++ b/source/lang/arithmeticcompound.rst @@ -0,0 +1,46 @@ +.. highlight:: cpp + +.. _lang-arithmeticcompound: + +Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) +=============================================================== + +Description +----------- + +Perform a mathematical operation on a variable with another constant +or variable. These operators are just a convenient shorthand:: + + x += y; // equivalent to the expression x = x + y; + x -= y; // equivalent to the expression x = x - y; + x *= y; // equivalent to the expression x = x * y; + x /= y; // equivalent to the expression x = x / y; + +Here is an example:: + + int x = 2; + int y = 10; + + x += 4; // x now contains 6 + x -= 3; // x now contains 3 + x *= y; // x now contains 30 + x /= 2; // x now contains 15 + x += max(20, 6); // x now contains 35 + x -= sq(5); // x now contains 15 + +Parameters +---------- + +**x**: a numeric variable + +**y**: a numeric variable, number constant, or any other expression +that evaluates to a number (e.g. call to a function that returns a +number). + +See Also +-------- + +- :ref:`Arithmetic operators ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/array.rst b/source/lang/array.rst new file mode 100644 index 0000000..30a818f --- /dev/null +++ b/source/lang/array.rst @@ -0,0 +1,123 @@ +.. highlight:: cpp + +.. _lang-array: + +Arrays +====== + +An array is a collection of variables that are accessed with an index +number. Arrays in the C++ programming language, in which the Maple is +programmed, can be complicated, but using simple arrays is relatively +straightforward. + +.. contents:: Contents + :local: + +Creating (Declaring) an Array +----------------------------- + +All of the methods below are valid ways to create (declare) an +array. :: + + int myInts[6]; + int myPins[] = {2, 4, 8, 3, 6}; + int mySensVals[6] = {2, 4, -8, 3, 2}; + char message[6] = "hello"; + +You can declare an array without initializing it, as with myInts. In +the line referring to myPins, we declare an array without explicitly +choosing a size. The compiler counts the elements and creates an +array of the appropriate size. + +Finally, you can both initialize and size your array, as in +mySensVals. Note that when declaring an array with elements of type +char, one more element than your initialization is required, to hold +the required `null character `_. + + +Accessing an Array +------------------ + + +.. compound:: + + Arrays are **zero indexed**; that is, referring to the array + initialization above, the first element of the array is at index 0, + hence :: + + mySensVals[0] == 2; + mySensVals[1] == 4 + + and so forth. + +It also means that in an array with ten elements, index nine is the +last element. Hence:: + + int myArray[10]={9,3,2,4,3,2,7,8,9,11}; + // myArray[9] contains 11 + // myArray[10] is invalid and contains random information (other memory address) + +For this reason, you should be careful in accessing arrays. Accessing +past the end of an array (using an index number greater than your +declared array size - 1) is reading from memory that is in use for +other purposes. Reading from these locations is probably not going to +do much except yield invalid data. Writing to random memory locations +is definitely a bad idea, and can often lead to unhappy results such +as crashes or program malfunction. This can also be a difficult bug to +track down. + +Unlike Basic or Java, the C compiler does no checking to see if array +access is within legal bounds of the array size that you have +declared. + + +To assign a value to an array +----------------------------- + :: + + mySensVals[0] = 10; + + +To retrieve a value from an array +--------------------------------- + + :: + + x = mySensVals[4]; + + +Arrays and ``for`` Loops +------------------------ + +Arrays are often manipulated inside :ref:`for loops `, where +the loop counter is used as the index for each array element. For +example, to print the elements of an array over the serial port, you +could do something like this:: + + int i; + for (i = 0; i < 5; i = i + 1) { + SerialUSB.println(myPins[i]); + } + + +Example +------- + +For a complete program that demonstrates the use of arrays, see the +Arduino `Knight Rider example +`_\ (which will run +unmodified on the Maple). + +Arduino Compatibility +--------------------- + +Arrays on Maple are identical those on Arduino. + +See also +-------- + +- :ref:`Storing arrays in FLASH memory ` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/assignment.rst b/source/lang/assignment.rst new file mode 100644 index 0000000..16f0bf4 --- /dev/null +++ b/source/lang/assignment.rst @@ -0,0 +1,70 @@ +.. highlight:: cpp + +.. _lang-assignment: + += assignment operator (single equal sign) +========================================= + +Stores the value to the right of the equal sign in the variable to +the left of the equal sign. + +The single equal sign in the C++ programming language is called the +assignment operator. It has a different meaning than in algebra +class, where it indicated an equation or equality. The assignment +operator tells the microcontroller to evaluate whatever value or +expression is on the right side of the equal sign, and store it in +the variable to the left of the equal sign [#fgross]_. + + + +Example +------- + +:: + + int sensVal; // declare an integer variable named sensVal + senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal + + + +Programming Tips +---------------- + +The variable on the left side of the assignment operator ( = sign ) +needs to be able to hold the value stored in it. If it is not large +enough to hold a value, the value stored in the variable will be +incorrect. + +Don't confuse the assignment operator [ = ] (single equal sign) +with the comparison operator [ == ] (double equal signs), which +evaluates whether two expressions are equal. + + +Arduino Compatibility +--------------------- + +Assignments on the Maple are identical to those on Arduino. + + + +See Also +-------- + + +- `if (comparison operators) `_ +- `char `_ +- `int `_ +- `long `_ + + +.. rubric:: Footnotes + +.. [#fgross] Experienced C++ programmers know this to be an + oversimplification of what happens when the variable on the left + hand side is an object. See Richard Gillam's wonderful and scary + `The Anatomy of the Assignment Operator + `_ + for more information. + + +.. include:: cc-attribution.txt diff --git a/source/lang/attachinterrupt.rst b/source/lang/attachinterrupt.rst new file mode 100644 index 0000000..0b8907f --- /dev/null +++ b/source/lang/attachinterrupt.rst @@ -0,0 +1,102 @@ +.. highlight:: cpp + +.. _lang-attachinterrupt: + +attachInterrupt() +================= + +Used to specify a function to call when an external interrupt (like an +GPIO changing from LOW to HIGH, a button getting pressed, etc.) +occurs. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: attachInterrupt + +.. doxygenenum:: ExtIntTriggerMode + +.. doxygentypedef:: voidFuncPtr + +Discussion +---------- + +Because the function will run in interrupt context, inside of it, +:ref:`lang-delay` won't work, and the value returned by +:ref:`lang-millis` will not increment. Serial data received while +in the function may be lost. You should declare as ``volatile`` any +global variables that you modify within the attached function. + +There are a few constraints you should be aware of if you're using +more than one interrupt at a time; the :ref:`external-interrupts` page +has the details. + + +Using Interrupts +---------------- + +Interrupts are useful for making things happen automatically in +microcontroller programs, and can help solve timing problems. A +good task for using an interrupt might be reading a rotary encoder, +or monitoring user input. + + +If you wanted to insure that a program always caught the pulses +from a rotary encoder, never missing a pulse, it would make it very +tricky to write a program to do anything else, because the program +would need to constantly poll the sensor lines for the encoder, in +order to catch pulses when they occurred. Other sensors have a +similar interface dynamic too, such as trying to read a sound +sensor that is trying to catch a click, or an infrared slot sensor +(photo-interrupter) trying to catch a coin drop. In all of these +situations, using an interrupt can free the microcontroller to get +some other work done while not missing the doorbell. + + +Example +------- + +:: + + int maple_led_pin = 13; + volatile int state = LOW; // must declare volatile, since it's + // modified within the blink handler + + void setup() { + pinMode(maple_led_pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() { + digitalWrite(maple_led_pin, state); + } + + void blink() { + state = !state; + } + + +Arduino Compatibility +--------------------- + +Most Arduino boards have two external interrupts: numbers 0 (on +digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an +additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 +(pin 18). On the Maple, you don't have to remember which interrupt +number goes with which pin -- just tell ``attachInterrupt()`` the pin +you want. + + +See also +-------- + + +- :ref:`detachInterrupt ` +- :ref:`external-interrupts` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/bit.rst b/source/lang/bit.rst new file mode 100644 index 0000000..c342fdd --- /dev/null +++ b/source/lang/bit.rst @@ -0,0 +1,48 @@ +.. _lang-bit: + +bit() +===== + +Description +----------- + +(Macro) Computes the value of an (unsigned) integer with the specified +bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8, +16, 32, etc.). + + +Syntax +------ + +``bit(n)`` + + +Parameters +---------- + +* **n** the bit to set. + + +Value +----- + +The value of an integer with the given bit set. + + +Arduino Compatibility +--------------------- + +The Maple implementation of bit is compatible with Arduino. + + +See also +-------- + + +- :ref:`lang-bitread` +- :ref:`lang-bitwrite` +- :ref:`lang-bitset` +- :ref:`lang-bitclear` + + +.. include:: cc-attribution.txt diff --git a/source/lang/bitclear.rst b/source/lang/bitclear.rst new file mode 100644 index 0000000..5d1eb95 --- /dev/null +++ b/source/lang/bitclear.rst @@ -0,0 +1,47 @@ +.. _lang-bitclear: + +bitClear() +========== + +Description +----------- + +(Macro) Clears (writes a 0 to) a bit of a numeric variable. + +Syntax +------ + +``bitClear(x, n)`` + + +Parameters +---------- + +* **x** the numeric variable whose bit to clear + +* **n** which bit to clear, starting at 0 for the least-significant + (rightmost) bit + + +Returns +------- + +None. + + +Arduino Compatibility +--------------------- + +This implementation is compatible with that of Arduino. + + +See also +-------- + +- :ref:`bit `\ () +- :ref:`bitRead `\ () +- :ref:`bitWrite `\ () +- :ref:`bitSet `\ () + + +.. include:: cc-attribution.txt diff --git a/source/lang/bitread.rst b/source/lang/bitread.rst new file mode 100644 index 0000000..9f885cf --- /dev/null +++ b/source/lang/bitread.rst @@ -0,0 +1,49 @@ +.. _lang-bitread: + +bitRead() +========= + +Description +----------- + +(Macro) Gets the value of a bit in a number. + + +Syntax +------ + +``bitRead(x, n)`` + + +Parameters +---------- + +* **x** the number from which to read the bit. + +* **n** which bit to read, starting at 0 for the least-significant + (rightmost) bit + + +Value +----- + +The value of the bit (0 or 1). + + +Arduino Compatibility +--------------------- + +The Maple implementation of ``bitRead`` is compatible with Arduino. + + +See also +-------- + + +- :ref:`lang-bit` +- :ref:`lang-bitwrite` +- :ref:`lang-bitset` +- :ref:`lang-bitclear` + + +.. include:: cc-attribution.txt diff --git a/source/lang/bitset.rst b/source/lang/bitset.rst new file mode 100644 index 0000000..502c1b6 --- /dev/null +++ b/source/lang/bitset.rst @@ -0,0 +1,49 @@ +.. _lang-bitset: + +bitSet() +======== + +Description +----------- + +(Macro) Sets (writes a 1 to) a bit of a numeric variable. + + +Syntax +------ + +``bitSet(x, n)`` + + +Parameters +---------- + +* **x** the numeric variable whose bit to set + +* **n** which bit to set, starting at 0 for the least-significant + (rightmost) bit + + +Value +----- + +None. + + +Arduino Compatibility +--------------------- + +The Maple implementation of bitSet is compatible with Arduino. + + +See Also +-------- + +- :ref:`lang-bit` +- :ref:`lang-bitread` +- :ref:`lang-bitwrite` +- :ref:`lang-bitclear` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/bitshift.rst b/source/lang/bitshift.rst new file mode 100644 index 0000000..f05d49e --- /dev/null +++ b/source/lang/bitshift.rst @@ -0,0 +1,148 @@ +.. highlight:: cpp + +.. _lang-bitshift: + +Bit shift left (``<<``), bit shift right (``>>``) +================================================= + +Description +----------- + +(Adapted from `The Bit Math Tutorial +`_ in `The Arduino +Playground `_\ ) + + +There are two bit shift operators in C++: the left shift operator +``<<`` and the right shift operator ``>>``. These operators cause the +bits in the left operand to be shifted left or right by the number of +positions specified by the right operand. + +More information on bitwise math can be obtained in the Wikipedia +article on `bitwise operations +`_\ , especially the +section on shifts in `C, C++, and Java +`_\ . + + +Syntax +------ + +``some_int << number_of_bits`` + +``some_int >> number_of_bits`` + + +Parameters +---------- + +* **some_int** An integer value or variable. + +* **number_of_bits** integer whose value is at most ``8 * + sizeof(variable)`` (so ``number_of_bits`` can be at most 32 for + ``int`` values, at most ``8`` for ``char`` values, etc.; the various + integer sizes are summarized :ref:`in this table + `\ ). + + + +Example: +-------- + +Here are some examples of bit shifting, with the binary representation of the number in comments:: + + int a = 5; // binary: 101 + int b = a << 3; // binary: 101000, or 40 in decimal + int c = b >> 3; // binary: 101, or back to 5 like we started with + + +When you left shift a value x by y bits (x << y), the leftmost y bits +in x are lost, literally shifted out of existence. We'll do this +example with ``char`` values (which are integers in the range 0-255, +and take up 8 bits of memory):: + + char a = 5; // binary (all 8 bits): 00000101 + char b = a << 7; // binary: 10000000 - the first 1 in 101 was discarded + + +If you are certain that none of the ones in a value are being shifted +into oblivion, a simple way to think of the left-shift operator is +that it multiplies the left operand by 2 raised to the right operand +power (in math notation, ``x << y`` equals x * 2\ :sup:`y`\ , as long +as none of the bits of x get shifted out). For example, to generate +powers of 2, the following expressions can be employed:: + + 1 << 0 == 1 + 1 << 1 == 2 + 1 << 2 == 4 + 1 << 3 == 8 + ... + 1 << 8 == 256 + 1 << 9 == 512 + 1 << 10 == 1024 + ... + +.. _lang-bitshift-signbit-gotcha: + +When you shift x right by y bits (``x >> y``), and the highest bit in +x is a 1, the behavior depends on the exact data type of x. If x is of +type ``int``, the highest bit is special, and determines whether x is +negative or not; the details are too complicated to explain here, but +they are thoroughly explained in the Wikipedia article on `two's +complement arithmetic +`_\ , which the +system most computers use to store integers. In that case, the sign +bit is copied into lower bits, for esoteric historical reasons:: + + int x = -16; // binary (all 32 bits): 11111111111111111111111111110000 + int y = x >> 3; // binary: 11111111111111111111111111111110 + + + +This behavior, called "sign extension", is often not what you +want. You probably wish zeros to be shifted in from the left. It +turns out that the right shift rules are different for ``unsigned +int`` values, so you can use a type cast to suppress ones being copied +from the left:: + + int x = -16; // binary: 11111111111111111111111111110000 + int y = (unsigned int)x >> 3; // binary: 00011111111111111111111111111110 + + + +If you are careful to avoid sign extension, you can use the +right-shift operator, ``>>``, as a way to divide by powers of 2. For +example:: + + int x = 1000; + int y = x >> 3; // integer division of 1000 by 8, causing y = 125. + + +Arduino Compatibility +--------------------- + +Since it's part of the C++ language, bit shifting on the Maple is +compatible with the Arduino; however, you should keep in mind that the +Maple has bigger integer types (as in, more bits) than the Arduino. + +Since the STM32 is a 32-bit processor, the ``int`` type takes up 32 +bits instead of 16, like on Arduino's 16-bit microcontroller. This +means that you can shift left, like ``x << y``, with bigger values of +``y`` on the Maple before ones in ``x`` start to get shifted out. + +To calculate the number of bits of an integer type on the Maple, +multiply its size in bytes (see :ref:`this table +` for these) by 8, since there are 8 +bits in 1 byte. For example, a ``short`` takes up 2 bytes of memory, +or 2 * 8 = 16 bits. + +See Also +-------- + +- :ref:`lang-bit` +- :ref:`lang-bitread` +- :ref:`lang-bitwrite` +- :ref:`lang-bitclear` + + +.. include:: cc-attribution.txt diff --git a/source/lang/bitwisecompound.rst b/source/lang/bitwisecompound.rst new file mode 100644 index 0000000..2b0fe2f --- /dev/null +++ b/source/lang/bitwisecompound.rst @@ -0,0 +1,231 @@ +.. highlight:: cpp + +.. _lang-bitwisecompound: + +Compound bitwise and (&=), or (\|=), XOR (^=) +============================================= + +The compound bitwise operators perform their calculations at the +bit level of variables. They are often used to clear and set +specific bits of a variable. + +See the :ref:`bitwise math tutorial ` for more +information on bitwise operators. + +.. contents:: Contents + :local: + +.. _lang-bitwisecompound-and: + +Compound bitwise AND (&=) +------------------------- + +The compound bitwise AND operator ``&=`` is often used with a variable +and a constant to force particular bits in a variable to be zero. This +is often referred to in programming guides as "clearing" or +"resetting" bits. In a program, writing the line ``x &= y;`` is +equivalent to writing ``x = x & y;``. That is, the value of ``x`` +after the line will be equal to its old value bitwise ANDed with the +value of ``y``:: + + x &= y; // equivalent to x = x & y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any :ref:`integer value +` (like ``3`` or ``0x20``) for ``y``. + +Before doing an example of ``&=``, let's first review the Bitwise AND +(``&``) operator:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) = result + +As shown above, bits that are "bitwise ANDed" with 0 become 0, while +bits that are "bitwise ANDed" with 1 are left unchanged. So, if ``b`` +is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b & +B11111111`` equals ``b``. + +.. _lang-bitwisecompound-binconst: + +.. note:: The above uses :ref:`binary constants + `\ . The numbers are still the same + value in other representations, they just might not be as easy to + understand. + + Normally, in C and C++ code, :ref:`hexadecimal + ` or :ref:`octal + ` are used when we're interested in + an integer's bits, rather than its value as a number. + + While hexadecimal and octal literals might be harder to understand + at first, you should really take the time to learn them. They're + part of C, C++, and many other programming languages, while binary + constants are available only for compatibility with Arduino. + + Also, ``B00000000`` is shown for clarity, but zero in any number + format is zero. + +So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while +leaving the rest of the variable's bits unchanged, use the compound +bitwise AND operator ``&=`` with the constant ``B11111100`` +(hexadecimal ``0xFC``\ ):: + + 1 0 1 0 1 0 1 0 variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + 1 0 1 0 1 0 0 0 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared + + +Here is the same representation with the variable's bits replaced +with the symbol ``x``\ :: + + x x x x x x x x variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + x x x x x x 0 0 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared + + +So, using a byte variable ``b``\ , if we say:: + + b = B10101010; // B10101010 == 0xAA + b &= B11111100; // B11111100 == 0xFC + +then we will have :: + + b == B10101000; // B10101000 == 0xA8 + +.. _lang-bitwisecompound-or: + +Compound bitwise OR (\|=) +------------------------- + +The compound bitwise OR operator ``|=`` is often used with a variable +and a constant to "set" (set to 1) particular bits in a variable. In +a program, writing the line ``x |= y;`` is equivalent to writing ``x = +x | y;``. That is, the value of ``x`` after the line will be equal to +its old value bitwise ORed with the value of ``y``:: + + x |= y; // equivalent to x = x | y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`compound bitwise AND +`\ , ``&=``). + +Before doing an example of ``|=``, let's first review the Bitwise OR +(``|``) operator:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) = result + +Bits that are "bitwise ORed" with 0 are unchanged, while bits that are +"bitwise ORed" with 1 are set to 1. So if ``b`` is a ``byte`` +variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111`` +equals ``B11111111`` (here we've used binary constants; see the +:ref:`note ` above). + +So, to set bits 0 and 1 of a one-byte variable, while leaving the rest +of the variable unchanged, use the compound bitwise OR operator +(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``):: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set + +Here is the same representation with the variable's bits replaced with +the symbol ``x``:: + + x x x x x x x x variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + x x x x x x 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set + +So, using a byte variable ``b``, if we say:: + + b = B10101010; // B10101010 == 0xAA + b |= B00000011; // B00000011 == 0x3 + +then we will have :: + + b == B10101011; // B10101011 == 0xAB + +.. _lang-bitwisecompound-xor: + +Compound bitwise XOR (\^=) +-------------------------- + +The compound bitwise XOR operator ``^=`` is used with a variable and a +constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a +variable. In a program, writing the line ``x ^= y;`` is equivalent to +writing ``x = x ^ y;``. That is, the value of ``x`` after the line +will be equal to its old value bitwise XORed with the value of ``y``:: + + x ^= y; // equivalent to x = x ^ y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`&= +` and :ref:`\|= +`; in fact, these three operators all +work the same in this way). + +Before doing an example of ``^=``, let's first review the Bitwise +XOR operator, ``^``:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) = result + +One way to look at bitwise XOR is that each bit in the result is a 1 +if the input bits are different, or 0 if they are the same. Another +way to think about it is that the result bit will be 1 when *exactly* +one (no more, no less) of the input bits is 1; otherwise, it will be +zero. This means that if you XOR a bit with 1, it will change (or +toggle) its value, while if you XOR a bit with 0, it stays the same. + +So, to toggle bits 0 and 1 of a one-byte variable, while leaving the +rest of the variable unchanged, use the compound bitwise XOR operator +``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see +:ref:`note ` above):: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged toggled + +So, using a byte variable ``b``, if we say:: + + b = B10101010; // B10101010 == 0xAA + b ^= B00000011; // B00000011 == 0x3 + +then we will have :: + + b == B10101001; // B10101001 == 0xA9 + +See Also +-------- + +- :ref:`Boolean operations ` (``&&``, ``||``) +- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) + + +.. include:: cc-attribution.txt diff --git a/source/lang/bitwisemath.rst b/source/lang/bitwisemath.rst new file mode 100644 index 0000000..30e8873 --- /dev/null +++ b/source/lang/bitwisemath.rst @@ -0,0 +1,186 @@ +.. highlight:: cpp + +.. _lang-bitwisemath: + +Bitwise AND (&), OR (\|), XOR (^), NOT (~) +========================================== + +The bitwise operators perform their calculations at the bit level of +variables. They help solve a wide range of common programming +problems. + +Much of the material here is adapted for Maple from an (Arduino) +`tutorial on bitwise math +`_\ . Another great +resource is the Wikipedia article on `bitwise operations +`_\ . + +Below are descriptions and syntax for all of the operators. + +.. contents:: Contents + :local: + +.. _lang-bitwisemath-and: + +Bitwise AND (&) +--------------- + +The bitwise AND operator in C++ is a single ampersand, ``&``, used +between two other integer expressions. Bitwise AND operates on each +bit position of the surrounding expressions independently, according +to this rule: if both input bits are 1, the resulting output is 1, +otherwise the output is 0. Another way of expressing this is:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) = result + + +On the Maple, the type ``int`` is a 32-bit value, so using ``&`` +between two ``int`` expressions causes 32 simultaneous AND operations +to occur. In a code fragment like:: + + int a = 92; // in binary: 00000000000000000000000001011100 + int b = 101; // in binary: 00000000000000000000000001100101 + int c = a & b; // result: 00000000000000000000000001000100, + // (or 68 in decimal). + + +Each of the 32 bits in ``a`` and ``b`` are processed using bitwise +AND, and all 32 resulting bits are stored in ``c``, resulting in the +value 1000100 in binary, which is 68 in decimal. + + +.. _lang-bitwisemath-or: + +Bitwise OR (\|) +--------------- + +The bitwise OR operator in C++ is the vertical bar symbol, ``|``. Like +the ``&`` operator, ``|`` operates independently on each bit in its +two surrounding integer expressions, but what it does is +different. The bitwise OR of two bits is 1 if either or both of the +input bits is 1, otherwise it is 0. For example:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) = result + +Here is an example of bitwise OR used in a snippet of C++ code (using +``char``, which takes up 8 bits of memory, instead of ``int``, which +uses 32):: + + char a = 92; // in binary: 01011100 + char b = 101; // in binary: 01100101 + char c = a | b; // result: 01111101, or 125 in decimal. + +.. _lang-bitwisemath-xor: + +Bitwise XOR (^) +--------------- + +There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE +OR, also known as bitwise XOR. (In English, this is usually pronounced +"zor" or "ex-or"). The bitwise XOR operator is written using the caret +symbol, ``^``. This operator is very similar to the bitwise OR +operator ``|``, except it evaluates to 0 for a given bit position when +both of the input bits for that position are 1:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) = result + + +Another way to look at bitwise XOR is that each bit in the result +is a 1 if the input bits are different, or 0 if they are the same. + +Here is a simple example:: + + int x = 12; // binary (ignoring extra bits): 1100 + int y = 10; // binary: 1010 + int z = x ^ y; // binary: 0110, or decimal 6 + + + +The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 +to 0) some of the bits in an integer expression. In a bitwise OR +operation if there is a 1 in the mask bit, that bit is inverted; if +there is a 0, the bit is not inverted and stays the same. Below is a +program to blink digital pin 13 (the LED pin on Maple):: + + // Blink Maple LED pin + + int led_pin = 13; + int toggle = 0; + + // demo for Exclusive OR + void setup(){ + pinMode(led_pin, OUTPUT); + } + + void loop(){ + toggle = toggle ^ 1; + digitalWrite(led_pin, toggle); + delay(100); + } + +.. _lang-bitwisemath-not: + +Bitwise NOT (~) +--------------- + +The bitwise NOT operator in C++ is the tilde character ``~``. Unlike +``&`` and ``|``, the bitwise NOT operator is applied to a single +operand to its right. Bitwise NOT changes each bit to its opposite: 0 +becomes 1, and 1 becomes 0. For example:: + + 0 1 operand1 + ---- + 1 0 ~operand1 = result + +Another example:: + + char a = 103; // binary: 01100111 + char b = ~a; // binary: 10011000 = -104 + +You might be surprised to see a negative number like -104 as the +result of this operation. This is because the highest bit in an int +variable is the so-called "sign bit". If the highest bit is 1, the +number is interpreted as negative. This encoding of positive and +negative numbers is referred to as *two's complement*. For more +information, see the Wikipedia article on `two's +complement. `_ + +As an aside, it is interesting to note that (under two's complement +arithmetic) for any integer ``x``, ``~x`` is the same as ``-x-1``. + +At times, the sign bit in a signed integer expression can cause +some unwanted surprises. + + +Uses +---- + +One of the most common uses of bitwise operations is to select or +manipulate a particular bit (or bits) from an integer value, often +called `bit masking +`_\ . See the +linked Wikipedia article for more information and examples. + +If you really want to see bit-twiddling techniques in their full +glory, you could do much worse than to get yourself a copy of +`Hacker's Delight `_\ . + + +See Also +-------- + +- :ref:`Boolean operations ` (``&&``, ``||``) +- :ref:`Compound bitwise operations ` (``&=``, + ``|=``, ``^=``). + + +.. include:: cc-attribution.txt diff --git a/source/lang/bitwrite.rst b/source/lang/bitwrite.rst new file mode 100644 index 0000000..86df26e --- /dev/null +++ b/source/lang/bitwrite.rst @@ -0,0 +1,40 @@ +.. _lang-bitwrite: + +bitWrite(x, n, b) +================= + +Description +----------- + +(Macro) Writes a bit of a numeric variable. + +Parameters +---------- + +**x**: the numeric variable whose bit to write. + +**n**: which bit of the number to write, starting at 0 for the +least-significant (rightmost) bit. + +**b**: the value to write to the bit (0 or 1). + +Returns +------- + +Nothing. + +Arduino Compatibility +--------------------- + +Maple's version of ``bitWrite()`` is compatible with Arduino. + +See also +-------- + +- :ref:`bit() ` +- :ref:`bitRead() ` +- :ref:`bitSet() ` +- :ref:`bitClear() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/boolean.rst b/source/lang/boolean.rst new file mode 100644 index 0000000..6ff4097 --- /dev/null +++ b/source/lang/boolean.rst @@ -0,0 +1,91 @@ +.. highlight:: cpp + +.. _lang-boolean: + +Boolean Operators +================= + +These can be used inside the condition of an :ref:`if ` +statement. Evaluate to :ref:`true ` or +:ref:`false `. + +.. contents:: Contents + :local: + +.. _lang-boolean-and: + +&& (logical and) +---------------- + +True only if both operands are true. For example:: + + if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches + // ... + } + +is true only if both inputs are high. Another example:: + + if (a >= 10 && a <= 20){} // true if a is between 10 and 20 + +**Be careful** not to say ``10 <= a <= 20``! This won't work the way +you want. You have to separately test whether ``a`` is at least 10 +using ``a >= 10``, then test whether ``a`` is at most 20 using ``a <= +20``, then combine the results using ``&&``. + + +.. _lang-boolean-or: + +\|\| (logical or) +----------------- + +True if either operand is true. For example:: + + if (x > 0 || y > 0) { + // ... + } + +is true if either ``x`` or ``y`` is greater than 0. + +.. _lang-boolean-not: + +! (logical not) +--------------- + +True if the operand is false. For example:: + + if (!x) { + // ... + } + +is true if ``x`` is false (i.e. if ``x`` is zero). + +Some Advice +----------- + +.. warning:: + + Make sure you don't mistake the boolean AND operator ``&&`` + (double ampersand) for the :ref:`bitwise AND operator + ` ``&`` (single ampersand). They are + entirely different beasts. + + Similarly, do not confuse the boolean OR operator ``||`` (double + pipe) with the :ref:`bitwise OR operator ` + ``|`` (single pipe). + + The :ref:`bitwise NOT operator ` ``~`` + (tilde) looks much different than the boolean not operator ``!`` + (exclamation point, or "bang", as some programmers say), but you + still have to be sure which one you want. + + +See Also +-------- + +- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) +- :ref:`Compound bitwise operators ` (``&=``, + ``|=``, ``^=``). +- :ref:`if statement ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/booleanvariables.rst b/source/lang/booleanvariables.rst new file mode 100644 index 0000000..9d0e992 --- /dev/null +++ b/source/lang/booleanvariables.rst @@ -0,0 +1,55 @@ +.. highlight:: cpp + +.. _lang-booleanvariables: + +Booleans +======== + +A **boolean** holds one of two values, :ref:`true +` or :ref:`false `. +On a Maple, each boolean variable occupies one byte of memory, and has +type ``bool``. + +.. warning:: + + On an Arduino, the type ``boolean`` is also provided. While the + Maple also has this type for compatibility, **its use is strongly + discouraged**. The ``bool`` type is a standard part of C++, while + ``boolean`` is a non-standard extension that serves no purpose. + +Example +------- + +:: + + int ledPin = 13; // LED on pin 13 + int switchPin = 12; // momentary switch on 12, other side connected to ground + + // running is a boolean variable: + bool running = false; + + void setup() { + pinMode(ledPin, OUTPUT); + pinMode(switchPin, INPUT); + digitalWrite(switchPin, HIGH); // turn on pullup resistor + } + + void loop() { + if (digitalRead(switchPin) == LOW) { + // switch is pressed - pullup keeps pin high normally + delay(100); // delay to debounce switch + running = !running; // toggle running variable + digitalWrite(ledPin, running) // indicate via LED + } + } + +See also +-------- + + +- :ref:`Boolean constants ` +- :ref:`Boolean operators ` +- :ref:`Variables ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/braces.rst b/source/lang/braces.rst new file mode 100644 index 0000000..229ad8c --- /dev/null +++ b/source/lang/braces.rst @@ -0,0 +1,109 @@ +.. highlight:: cpp + +.. _lang-braces: + +Curly Braces ({}) +================= + +.. contents:: Contents + :local: + +Introduction +------------ + +Curly braces (also referred to as just "braces" or as "curly +brackets") are a major part of the C and C++ programming +languages. They are used in several different constructs, outlined +below, and this can sometimes be confusing for beginners. + +An opening curly brace, ``{`` must always be followed by a closing +curly brace ``}``. This is a condition that is often referred to as +the braces being *balanced*. The Maple IDE (integrated development +environment) includes a convenient feature to check the balance of +curly braces. Just select a brace, or even click the insertion point +immediately following a brace, and its companion will be highlighted\ +[#fbug]_\ . + +Beginning programmers, and programmers coming to C++ from languages +without braces, often find using them confusing or daunting. + +Because the use of the curly brace is so varied, it is good +programming practice to type the closing brace immediately after +typing the opening brace when inserting a construct which requires +curly braces. Then insert some blank lines between your braces and +begin inserting statements. Your braces, and your attitude, will never +become unbalanced. + +Unbalanced braces can often lead to cryptic, impenetrable compiler +errors that can sometimes be hard to track down in a large program. +Because of their varied usages, braces are also incredibly important +to the syntax of a program and moving a brace one or two lines will +usually dramatically affect the meaning of a program. + +The main uses of curly braces +----------------------------- + +**Functions**:: + + // a function body needs braces around it + void myFunction(datatype argument) { + // ... function body goes in here ... + } + +**Loops** (see the :ref:`while `\ , :ref:`for +`\ , and :ref:`do/while ` loop reference +pages for more information):: + + // you should put braces around the body of a loop: + + while (boolean expression) { + // code inside the loop goes here + } + + for (initialisation; termination condition; incrementing expr) { + // code inside the loop goes here + } + + do { + // code inside the loop goes here + } while (boolean expression); + + +**Conditional statements** (see the :ref:`if statement ` +reference page for more information):: + + // you should put braces around the body of an "if", "else if", + // or "else": + + if (boolean expression) { + // code inside the "if" + } + else if (boolean expression) { + // code inside the "else if" + } + else { + // code inside the "else" + } + +**Switch statements** (see the :ref:`switch statement +` reference page for more information):: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + +.. rubric:: Footnotes + +.. TODO remove this once IDE 0.1.0 released + +.. [#fbug] At present this feature is slightly buggy as the IDE will + often find (incorrectly) a brace in text that has been commented + out. + + +.. include:: cc-attribution.txt diff --git a/source/lang/break.rst b/source/lang/break.rst new file mode 100644 index 0000000..dc50b5f --- /dev/null +++ b/source/lang/break.rst @@ -0,0 +1,35 @@ +.. highlight:: cpp + +.. _lang-break: + +break +===== + +``break`` is used to exit from a :ref:`while `\ , +:ref:`for `\ , or :ref:`do/while ` loop, +bypassing the normal loop condition. It is also used to exit from a +:ref:`switch ` statement. + + +Example +------- + +:: + + for (x = 0; x < 255; x ++) + { + digitalWrite(PWMpin, x); + sens = analogRead(sensorPin); + if (sens > threshold){ // bail out on sensor detect + x = 0; + // this line of code means that we'll immediately exit + // from the "for" loop: + break; + } + delay(50); + } + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/byte.rst b/source/lang/byte.rst new file mode 100644 index 0000000..45c9d5f --- /dev/null +++ b/source/lang/byte.rst @@ -0,0 +1,34 @@ +.. highlight:: cpp + +.. _lang-byte: + +byte +==== + +The ``byte`` type stores a 1-byte (8-bit) unsigned integer number, +from 0 to 255. + +.. warning:: + + The ``byte`` type is provided for compatibility with Arduino. + However, it is a non-standard extension. The standard C++ type for + storing an 8-bit unsigned integer is ``unsigned char``; we + recommend using that instead. (Your code will still work on an + Arduino). + + +Example +------- + +:: + + byte b = 134; + +See Also +-------- + +- :ref:`byte() ` (casting a value to a byte) +- :ref:`Variables ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/bytecast.rst b/source/lang/bytecast.rst new file mode 100644 index 0000000..4ad2a89 --- /dev/null +++ b/source/lang/bytecast.rst @@ -0,0 +1,53 @@ +.. highlight:: cpp + +.. _lang-bytecast: + +byte() (cast) +============= + +Description +----------- + +Converts a value to the :ref:`byte ` data type. + +.. note:: + + Casting to the byte type is provided for compatibility with + Arduino. However, the recommended Maple type for storing an 8-bit + unsigned integer is ``uint8``. (C and C++ programmers: ``stdint.h`` + is also available). + + In order to cast a variable ``x`` to a ``uint8``, the + following syntax can be used:: + + uint8(x); + +Syntax +------ + +``byte(x)`` + + +Parameters +---------- + +**x**: a value of any integer type + + +Returns +------- + +The value, converted to a ``byte``. Note, however, that if the value +is larger than the maximum value you can store in a byte (255), then +the results might be strange and unexpected. + + +See Also +-------- + +- :ref:`lang-byte` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cc-attribution.txt b/source/lang/cc-attribution.txt new file mode 100644 index 0000000..e100140 --- /dev/null +++ b/source/lang/cc-attribution.txt @@ -0,0 +1,9 @@ +.. Included in all this directory's files in order to satisfy the +.. Arduino CC Attribution-ShareAlike 3.0 License + +.. admonition:: License and Attribution + + This documentation page was adapted from the `Arduino Reference + Documentation `_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License `_. diff --git a/source/lang/char.rst b/source/lang/char.rst new file mode 100644 index 0000000..8c6dadf --- /dev/null +++ b/source/lang/char.rst @@ -0,0 +1,53 @@ +.. highlight:: cpp + +.. _lang-char: + +char +==== + +Description +----------- + +The ``char`` type stores a 1-byte character value (or integer with +value from -128 to 127). Character literals are written in single +quotes, like this: ``'A'`` (for multiple characters - strings - use +double quotes: ``"ABC"``). + + +Just like everything else on a computer, characters are stored as +numbers. You can see the specific encoding in the `ASCII chart +`_\ +. This means that it is possible to do arithmetic on characters, in +which the ASCII value of the character is used (e.g. ``'A' + 1`` has the +decimal value 66, since the ASCII value of the capital letter A in +decimal is 65). See the :ref:`Serial.println() +` documentation for more information about how +characters are converted into numbers. + +The ``char`` datatype is a signed type, meaning that it encodes +numbers from -128 to 127. For an unsigned type, which stores values +from 0 to 255, just use the type ``unsigned char`` (two words). + + +Example +------- + +:: + + // the following two lines are equivalent, using the ASCII + // character encoding: + char c = 'A'; + char c = 65; + + +See also +-------- + + +- :ref:`lang-int` +- :ref:`lang-array` (a string is just an array of ``char``\ s) +- :ref:`Serial.println() ` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/charcast.rst b/source/lang/charcast.rst new file mode 100644 index 0000000..844dd58 --- /dev/null +++ b/source/lang/charcast.rst @@ -0,0 +1,39 @@ +.. highlight:: cpp + +.. _lang-charcast: + +char() (cast) +============= + +Description +----------- + +Converts a value to the :ref:`char ` data type. + +Syntax +------ + +``char(x)`` + + +Parameters +---------- + +**x**: a value of any type + + +Returns +------- + +The value, converted to a ``char``. Note, however, that if the value +is outside the range of a ``char`` (-128 to 127), then the results +might be strange and unexpected. + + +See Also +-------- + +- :ref:`char ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/comments.rst b/source/lang/comments.rst new file mode 100644 index 0000000..c5f118a --- /dev/null +++ b/source/lang/comments.rst @@ -0,0 +1,67 @@ +.. highlight:: cpp + +.. _lang-comments: + +Comments +======== + +Comments are lines in the program that are used to inform yourself or +others about the way the program works. They are ignored by the +compiler, and not exported to the processor, so they don't take up any +space in RAM or Flash. + +One use for comments is to help you understand (or remember) how your +program works, or to inform others how your program works. There are +two different ways of making comments. + +.. _lang-comments-singleline: + +**Single line comment**: Anything following two slashes, ``//``, until +the end of the line, is a comment:: + + x = 5; // the rest of this line is a comment + +.. _lang-comments-multiline: + +**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` +is a comment:: + + /* <-- a slash-star begins a multi-line comment + + all of this in the multi-line comment - you can use it to comment + out whole blocks of code + + if (gwb == 0){ // single line comment is OK inside a multi-line comment + x = 3; + } + + // don't forget the "closing" star-slash - they have to be balanced: + */ + +Note that it's okay to use single-line comments within a multi-line +comment, but you can't use multi-line comments within a multi-line +comment. Here's an example:: + + /* ok, i started a multi-line comment + + x = 3; /* this next star-slash ENDS the multi-line comment: */ + + x = 4; // this line is outside of the multi-line comment + + // next line is also outside of the comment, and causes a compile error: + */ + +Programming Tip +--------------- + +When experimenting with code, "commenting out" parts of your program +is a convenient way to remove lines that may be buggy. This leaves +the lines in the code, but turns them into comments, so the compiler +just ignores them. This can be especially useful when trying to locate +a problem, or when a program refuses to compile and the compiler error +is cryptic or unhelpful. + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/comparison.rst b/source/lang/comparison.rst new file mode 100644 index 0000000..8873256 --- /dev/null +++ b/source/lang/comparison.rst @@ -0,0 +1,87 @@ +.. highlight:: cpp + +.. _lang-comparison: + +Comparison Operators +==================== + +The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and +``>=`` are used to compare two numbers. They are :ref:`true +` when the comparison is true, and :ref:`false +` otherwise. They are based on the symbols +=, ≠, <, >, ≤, and ≥ from mathematics. + +Here are some examples, with their meaning in comments:: + + // "eq" is true when x is equal to y + bool eq = (x == y); + + // "neq" is true when x is different than y + bool neq = (x != y); + + // "lt" is true when x is less than, but NOT equal to, y + bool lt = (x < y); + + // "gt" is true when x is greater than, but NOT equal to, y + bool gt = (x > y); + + // "lte" is true when x is less than or equal to y + bool lte = (x <= y); + + // "gte" is true when x is greater than or equal to y + bool gte = (x >= y); + +The parentheses are optional; they are present only for clarity. For +example, the following two lines are the same:: + + bool eq = x == y; + + bool eq = (x == y); + +Uses +---- + +Comparison operators, along with :ref:`boolean operators +`, are useful inside the conditionals of :ref:`if +` statements. Here's one example:: + + if (x < 50) { + // only execute these lines if x is less than 50 + SerialUSB.println("delaying:"); + SerialUSB.println(x); + delay(x); + } + +.. warning:: + Beware of accidentally using the single equal sign (``=``) when you + meant to test if two numbers are equal (``==``). This is a common + mistake inside of ``if`` statement conditionals, e.g.:: + + // DON'T MAKE THIS MISTAKE + if (x = 10) { + // body + } + + The single equal sign is the assignment operator, and sets x to 10 + (puts the value 10 into the variable x). Instead use the double equal + sign (e.g. ``if (x == 10)``), which is the comparison operator, and + tests *whether* x is equal to 10 or not. The latter statement is only + true if x equals 10, but the former statement will always be true. + + This is because C evaluates the statement ``if (x=10)`` as follows: 10 + is assigned to x (remember that the single equal sign is the + :ref:`assignment operator `), so x now + contains 10. Then the 'if' conditional evaluates 10, which evaluates + to :ref:`true `, since any non-zero number + evaluates to ``true``. + + Consequently, the conditional of an ``if`` statement like ``if (x = + 10) {...}`` will always evaluate to ``true``, and the variable x + will be set to 10, which is probably not what you meant. + + (This sometimes has uses, though, so just because an assignment + appears within a conditional doesn't mean it's automatically wrong. + Be careful to know what you mean.) + + +.. include:: cc-attribution.txt diff --git a/source/lang/const.rst b/source/lang/const.rst new file mode 100644 index 0000000..1658e6d --- /dev/null +++ b/source/lang/const.rst @@ -0,0 +1,52 @@ +.. highlight:: cpp + +.. _lang-const: + +const Keyword +============= + +The ``const`` keyword stands for "constant". It is a variable +*qualifier* that modifies the behavior of the variable, making a +variable "*read-only*". This means that the variable can be used just +as any other variable of its type, but its value cannot be +changed. You will get a compiler error if you try to assign a value to +a ``const`` variable. + +Constants defined with the ``const`` keyword obey the same rules of +:ref:`variable scoping ` that govern other +variables. This, and the pitfalls of using :ref:`#define +`, often makes using the ``const`` keyword a superior +method for defining constants than ``#define``. + +Example +------- + +:: + + // this defines a variable called "pi", which cannot be changed: + const float pi = 3.14; + float x; + + // .... + + x = pi * 2; // it's fine to find the value of a const variable + + pi = 7; // illegal - you can't write to (modify) a constant + + +**#define** or **const** +------------------------ + +You can use either ``const`` or ``#define`` for creating numeric or +string constants. For :ref:`arrays `\ , you will need +to use ``const``. In general, ``const`` is preferred over ``#define`` +for defining constants. + +See Also +-------- + +- :ref:`#define ` +- :ref:`volatile ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/constants.rst b/source/lang/constants.rst new file mode 100644 index 0000000..b7521ed --- /dev/null +++ b/source/lang/constants.rst @@ -0,0 +1,302 @@ +.. _lang-constants: + +constants +========= + +Constants are predefined variables in the Arduino language. They +are used to make the programs easier to read. We classify constants +in groups. + +.. contents:: Contents + :local: + +.. _lang-constants-bool: + +Boolean Constants +----------------- + +There are two constants used to represent truth and falsity in the +Arduino language: **true**, and **false**. + +.. _lang-constants-false: + +false +^^^^^ + +false is the easier of the two to define. false is defined as 0 +(zero). + +.. _lang-constants-true: + +true +^^^^ + +true is often said to be defined as 1, which is correct, but true +has a wider definition. Any integer which is *non-zero* is TRUE, in +a Boolean sense. So -1, 2 and -200 are all defined as true, too, in +a Boolean sense. + + +Note that the *true* and *false* constants are typed in lowercase +unlike HIGH, LOW, INPUT, & OUTPUT. + + +Defining Pin Levels, HIGH and LOW +--------------------------------- + +When reading or writing to a digital pin there are only two +possible values a pin can take/be-set-to: **HIGH** and **LOW**. + +.. _lang-constants-high: + +**HIGH** + + + +The meaning of HIGH (in reference to a pin) is somewhat different +depending on whether a pin is set to an INPUT or OUTPUT. When a pin +is configured as an INPUT with pinMode, and read with digitalRead, +the microcontroller will report HIGH if a voltage of 3 volts or +more is present at the pin. + + + +A pin may also be configured as an INPUT with pinMode, and +subsequently made HIGH with digitalWrite, this will set the +internal 20K pullup resistors, which will *steer* the input pin to +a HIGH reading unless it is pulled LOW by external circuitry. + + + +When a pin is configured to OUTPUT with pinMode, and set to HIGH +with digitalWrite, the pin is at 5 volts. In this state it can +*source* current, e.g. light an LED that is connected through a +series resistor to ground, or to another pin configured as an +output, and set to LOW. + +.. _lang-constants-low: + +**LOW** + + + +The meaning of LOW also has a different meaning depending on +whether a pin is set to INPUT or OUTPUT. When a pin is configured +as an INPUT with pinMode, and read with digitalRead, the +microcontroller will report LOW if a voltage of 2 volts or less is +present at the pin. + + + +When a pin is configured to OUTPUT with pinMode, and set to LOW +with digitalWrite, the pin is at 0 volts. In this state it can +*sink* current, e.g. light an LED that is connected through a +series resistor to, +5 volts, or to another pin configured as an +output, and set to HIGH. + + + +Defining Digital Pins, INPUT and OUTPUT +--------------------------------------- + +Digital pins can be used either as **INPUT** or **OUTPUT**. +Changing a pin from INPUT TO OUTPUT with pinMode() drastically +changes the electrical behavior of the pin. + +.. _lang-constants-input: + +Pins Configured as Inputs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Arduino (Atmega) pins configured as **INPUT** with pinMode() are +said to be in a high-impedance state. One way of explaining this is +that pins configured as INPUT make extremely small demands on the +circuit that they are sampling, say equivalent to a series resistor +of 100 Megohms in front of the pin. This makes them useful for +reading a sensor, but not powering an LED. + +.. _lang-constants-output: + +Pins Configured as Outputs +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pins configured as **OUTPUT** with pinMode() are said to be in a +low-impedance state. This means that they can provide a substantial +amount of current to other circuits. Atmega pins can source +(provide positive current) or sink (provide negative current) up to +40 mA (milliamps) of current to other devices/circuits. This makes +them useful for powering LED's but useless for reading sensors. +Pins configured as outputs can also be damaged or destroyed if +short circuited to either ground or 5 volt power rails. The amount +of current provided by an Atmega pin is also not enough to power +most relays or motors, and some interface circuitry will be +required. + +.. _lang-constants-fp: + +Floating-Point Constants +------------------------ + +Similar to integer constants, floating point constants are used to +make code more readable. Floating point constants are swapped at +compile time for the value to which the expression evaluates. + +.. TODO explain that floating point literals are doubles + +.. _lang-constants-fp-f: + +.. TODO f modifiers + +Examples: + +``n = .005;`` + +Floating point constants can also be expressed in a variety of +scientific notation. 'E' and 'e' are both accepted as valid +exponent indicators. + +:: + + + floating-point evaluates to: also evaluates to: + constant + + 10.0 10 + 2.34E5 2.34 * 10^5 234000 + 67e-12 67.0 * 10^-12 .000000000067 + +.. _lang-constants-integers: + +Integer Constants +----------------- + +Integer constants are numbers used directly in a sketch, like +``123``. By default, these numbers are treated as +`int `_'s but you can change +this with the U and L modifiers (see below). + + + +Normally, integer constants are treated as base 10 (decimal) +integers, but special notation (formatters) may be used to enter +numbers in other bases. + + + +:: + + Base Example Formatter Comment + + 10 (decimal) 123 none + + 2 (binary) B1111011 leading 'B' only works with 8 bit values (0 to 255) + characters 0-1 valid + + 8 (octal) 0173 leading "0" characters 0-7 valid + + 16 (hexadecimal) 0x7B leading "0x" characters 0-9, A-F, a-f valid + +.. _lang-constants-integers-dec: + +**Decimal** is base 10. This is the common-sense math with which +you are acquainted. Constants without other prefixes are assumed to +be in decimal format. + + + +Example: +:: + + 101 // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) + +.. _lang-constants-integers-bin: + +**Binary** is base two. Only characters 0 and 1 are valid. + + + +Example: +:: + + B101 // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) + +The binary formatter only works on bytes (8 bits) between 0 (B0) +and 255 (B11111111). If it is convenient to input an int (16 bits) +in binary form you can do it a two-step procedure such as: + + + +:: + + myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte + +.. _lang-constants-integers-oct: + +**Octal** is base eight. Only characters 0 through 7 are valid. Octal +values are indicated by the prefix "0". + +Example: + +:: + + 0101 // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) + +Warning +It is possible to generate a hard-to-find bug by (unintentionally) +including a leading zero before a constant and having the compiler +unintentionally interpret your constant as octal. + +.. _lang-constants-integers-hex: + +**Hexadecimal (or hex)** is base sixteen. Valid characters are 0 +through 9 and letters A through F; A has the value 10, B is 11, up +to F, which is 15. Hex values are indicated by the prefix "0x". +Note that A-F may be syted in upper or lower case (a-f). + + + +Example: + +:: + + 0x101 // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) + +.. _lang-constants-integers-u-l: + +U & L formatters +^^^^^^^^^^^^^^^^ + +By default, an integer constant is treated as an +`int `_ with the attendant +limitations in values. To specify an integer constant with another +data type, follow it with: + + + + +- a 'u' or 'U' to force the constant into an unsigned data format. + Example: ``33u`` +- a 'l' or 'L' to force the constant into a long data format. + Example: ``100000L`` +- a 'ul' or 'UL' to force the constant into an unsigned long + constant. Example: ``32767ul`` + + + + +See also +-------- + + +- `pinMode() `_ +- `Integer Constants `_ +- `boolean variables `_ +- `#define `_ +- `byte `_ +- `int `_ +- `unsigned int `_ +- `long `_ +- `unsigned long `_ + + +.. include:: cc-attribution.txt diff --git a/source/lang/constrain.rst b/source/lang/constrain.rst new file mode 100644 index 0000000..297a2d4 --- /dev/null +++ b/source/lang/constrain.rst @@ -0,0 +1,65 @@ +.. highlight:: cpp + +.. _lang-constrain: + +constrain(x, a, b) +================== + +Description +----------- + +(Macro) Constrains a number to be within a range. + + +Parameters +---------- + +**x**: the number to constrain + +**a**: the lower end of the range + +**b**: the upper end of the range + +Returns +------- + +**x**: if **x** is between **a** and **b** + +**a**: if **x** is less than **a** + +**b**: if **x** is greater than **b** + +Example +------- + +:: + + // limits range of sensor values to between 10 and 150: + sensVal = constrain(sensVal, 10, 150); + + +Warning +------- + +Because of the way ``constrain()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + constrain(x,a++,b); // avoid this - yields incorrect results + + constrain(x,a,b); // use this instead- + a++; // keep other math outside constrain() + +Arduino Compatibility +--------------------- + +Maple's implementation of ``constrain()`` is compatible with Arduino. + +See also +-------- + +- :ref:`min() ` +- :ref:`max() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/continue.rst b/source/lang/continue.rst new file mode 100644 index 0000000..21b3984 --- /dev/null +++ b/source/lang/continue.rst @@ -0,0 +1,34 @@ +.. highlight:: cpp + +.. _lang-continue: + +========== + continue +========== + +The ``continue`` keyword skips the rest of the current iteration of a +:ref:`while `\ , :ref:`for `\ , or +:ref:`do/while ` loop. It continues by checking the +conditional expression of the loop, and proceeding with any subsequent +iterations. + + +Example +======= + +:: + + + for (x = 0; x < 255; x ++) { + if (x > 40 && x < 120) { // create jump in values + continue; // skips the next two lines and goes to the + // beginning of the loop, with the next value of x + } + + digitalWrite(PWMpin, x); + delay(50); + } + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cos.rst b/source/lang/cos.rst new file mode 100644 index 0000000..3fbb0af --- /dev/null +++ b/source/lang/cos.rst @@ -0,0 +1,32 @@ +.. _lang-cos: + +cos() +===== + +Calculates the cosine of an angle. + +Library Documentation +--------------------- + +.. doxygenfunction:: cos + +Arduino Compatibility +--------------------- + +The Maple ``cos()`` implementation is compatible with Arduino. + +Note that the Maple implementation comes from `newlib +`_\ , while Arduino's is that of +`avr-libc `_\ . + +See also +-------- + + +- :ref:`sin() ` +- :ref:`tan() ` +- :ref:`float ` +- :ref:`double ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/define.rst b/source/lang/define.rst new file mode 100644 index 0000000..30738ec --- /dev/null +++ b/source/lang/define.rst @@ -0,0 +1,56 @@ +.. highlight:: cpp + +.. _lang-define: + +#define +======= + +``#define`` is a useful C and C++ feature that allows the programmer +to give a name to a constant value before the program is compiled. +The compiler will replace references to these constants with the +defined value at compile time. + +This can have some unwanted side effects. In general, the :ref:`const +` keyword is preferred for defining constants. + + +Syntax +------ + +The following line would define the name ``MY_CONSTANT`` to have value +``value``:: + + #define MY_CONSTANT value + +Note that the ``#`` is necessary. It is usually good style for the +name to be capitalized, although this is not required. + +There is no semicolon after the #define statement. If you include one, +the compiler will likely throw cryptic errors in unrelated places. +That is, **don't do this**:: + + // DON'T DO THIS! THE SEMICOLON SHOULDN'T BE THERE! + #define NAME value; + +Similarly, including an equal sign after the ``#define`` line will +also generate a cryptic compiler error further down the page. That +is, **don't do this, either**:: + + // DON'T DO THIS, EITHER! THE EQUALS SIGN SHOULDN'T BE THERE! + #define NAME = value + +Example +------- + +:: + + #define LED_PIN 13 + // The compiler will replace any mention of LED_PIN with + // the value 3 at compile time. + +See Also +-------- +- :ref:`const ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/delay.rst b/source/lang/delay.rst new file mode 100644 index 0000000..90ca268 --- /dev/null +++ b/source/lang/delay.rst @@ -0,0 +1,72 @@ +.. highlight:: cpp + +.. _lang-delay: + +delay() +======= + +Pauses the program for at least a given number of milliseconds. (There +are 1000 milliseconds in a second.) + +Library Documentation +--------------------- + +.. doxygenfunction:: delay + + +Discussion +---------- + +While it is easy to create a blinking LED with the ``delay()`` +function, and many sketches use short delays for such tasks as switch +debouncing, the use of ``delay()`` in a sketch has significant +drawbacks. No other reading of sensors, mathematical calculations, or +pin manipulation can go on during the delay function, so in effect, it +brings most other activity to a halt. For alternative approaches to +controlling timing see the :ref:`millis() ` function +and the "Blink Without Delay" sketch cited :ref:`below +`\ . More knowledgeable programmers usually +avoid the use of ``delay()`` for timing of events longer than tens of +milliseconds, unless the sketch is very simple. + +Certain things *do* go on while the ``delay()`` function is +controlling the STM32 chip, however, because the delay function does +not disable interrupts. Serial communication that appears at the RX +pin is recorded, PWM (see :ref:`pwmWrite() `\ ) values +and pin states are maintained, and :ref:`interrupts +` will work as they should. + + +Example +------- + +:: + + int ledPin = 13; // LED connected to pin 13 + + void setup() { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + +.. _lang-delay-seealso: + +See also +-------- + + +- :ref:`millis() ` +- :ref:`micros() ` +- :ref:`delayMicroseconds() ` +- (Arduino) `Blink Without Delay + `_ example (works + unmodified on Maple) + + +.. include:: cc-attribution.txt diff --git a/source/lang/delaymicroseconds.rst b/source/lang/delaymicroseconds.rst new file mode 100644 index 0000000..24a8286 --- /dev/null +++ b/source/lang/delaymicroseconds.rst @@ -0,0 +1,65 @@ +.. highlight:: cpp + +.. _lang-delaymicroseconds: + +delayMicroseconds() +=================== + +Pauses the program for the amount of time (in microseconds) +specified as parameter. There are a thousand microseconds in a +millisecond, and a million microseconds in a second. + +Library Documentation +--------------------- + +.. doxygenfunction:: delayMicroseconds + + +Example +------- + +The following example configures pin number 8 to work as an output +pin, and sends a train of pulses with a period of roughly 100 +microseconds:: + + int outPin = 8; + + void setup() { + pinMode(outPin, OUTPUT); // sets the digital pin as output + } + + void loop() { + digitalWrite(outPin, HIGH); // sets the pin on + delayMicroseconds(50); // pauses for 50 microseconds + digitalWrite(outPin, LOW); // sets the pin off + delayMicroseconds(50); // pauses for 50 microseconds + } + + +Caveats and Known Issues +------------------------ + +The longest time ``delayMicroseconds()`` can delay is bounded by its +argument type and the STM32 clock rate to be (2^32 - 1) / 12 +microseconds, or less than 6 minutes. For longer pauses, use of +:ref:`lang-delay` is possible. + +Arduino Compatibility +--------------------- + +While we have made every effort we could to ensure that the timing of +delayMicroseconds is as accurate as possible, we cannot guarantee it +will behave as the Arduino implementation down to the microsecond, +especially for smaller values of ``us``. + +See Also +-------- + +- :ref:`millis ` +- :ref:`micros ` +- :ref:`delay ` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/detachinterrupt.rst b/source/lang/detachinterrupt.rst new file mode 100644 index 0000000..adb2439 --- /dev/null +++ b/source/lang/detachinterrupt.rst @@ -0,0 +1,37 @@ +.. _lang-detachinterrupt: + +detachInterrupt() +================= + +Used to disable an interrupt specified with +:ref:`lang-attachinterrupt`\ . + + +Library Documentation +--------------------- + +.. doxygenfunction:: detachInterrupt + +Arduino Compatibility +--------------------- + +There is one important difference between the Maple version of +detachInterrupt and the Arduino version. On the Maple, the argument +to ``detachInterrupt()`` is the *pin* on which the interrupt is +attached, while on the Arduino, the argument is the *interrupt +number*, which is different from the pin the interrupt is enabled on. + +If you're calling this function, you've already called +:ref:`lang-attachinterrupt` to set up your interrupt handler, so +just call ``detachInterrupt()`` with the same pin argument you gave to +``attachInterrupt()``. + +See Also +-------- + +- :ref:`attachInterrupt() ` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/digitalread.rst b/source/lang/digitalread.rst new file mode 100644 index 0000000..71583ca --- /dev/null +++ b/source/lang/digitalread.rst @@ -0,0 +1,61 @@ +.. highlight:: cpp + +.. _lang-digitalread: + +digitalRead() +============= + +Description +----------- + +Reads the value from a specified digital pin, either :ref:`HIGH +` or :ref:`LOW `. + + +Library Documentation +--------------------- + +.. doxygenfunction:: digitalRead + + +Example +------- + +The following example turns the LED on when the button is pressed:: + + int ledPin = 13; // LED connected to Maple pin 13 + int buttonPin = 38; // BUT connected to Maple pin 38 + + void setup() { + pinMode(ledPin, OUTPUT); + pinMode(buttonPin, INPUT); + } + + void loop() { + int val = digitalRead(buttonPin); // reads the input pin + digitalWrite(ledPin, val); + } + +Note +---- + +If the pin isn't connected to anything, ``digitalRead()`` can return +either HIGH or LOW (and this can change in a way that seems random). + +Arduino Compatibility +--------------------- + +The Maple version of ``digitalRead()`` is compatible with Arduino. + + +See Also +-------- + +- :ref:`pinMode ` +- :ref:`digitalWrite ` + + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/digitalwrite.rst b/source/lang/digitalwrite.rst new file mode 100644 index 0000000..419ef3a --- /dev/null +++ b/source/lang/digitalwrite.rst @@ -0,0 +1,116 @@ +.. _lang-digitalwrite: + +digitalWrite() +============== + +Description +----------- + +Write a `HIGH `_ or a +`LOW `_ value to a +digital pin. + + + +If the pin has been configured as an OUTPUT with +`pinMode `_\ (), its voltage +will be set to the corresponding value: 5V (or 3.3V on 3.3V boards) +for HIGH, 0V (ground) for LOW. + + + +If the pin is configured as an INPUT, writing a HIGH value with +digitalWrite() will enable an internal 20K pullup resistor (see the +`tutorial on digital pins `_). +Writing LOW will disable the pullup. The pullup resistor is enough +to light an LED dimly, so if LEDs appear to work, but very dimly, +this is a likely cause. The remedy is to set the pin to an output +with the pinMode() function. + + + +**NOTE:** Digital pin 13 is harder to use as a digital input than +the other digital pins because it has an LED and resistor attached +to it that's soldered to the board on most boards. If you enable +its internal 20k pull-up resistor, it will hang at around 1.7 V +instead of the expected 5V because the onboard LED and series +resistor pull the voltage level down, meaning it always returns +LOW. If you must use pin 13 as a digital input, use an external +pull down resistor. + + + +Syntax +------ + +digitalWrite(pin, value) + + + +Parameters +---------- + +pin: the pin number + + + +value: `HIGH `_ or +`LOW `_ + + + +Returns +------- + +none + + + +Example +------- + +:: + + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Sets pin 13 to HIGH, makes a one-second-long delay, and sets the +pin back to LOW. + + + +Note +---- + +The analog input pins can be used as digital pins, referred to as +A0, A1, etc. + + + +See also +-------- + + +- `pinMode `_\ () +- `digitalRead `_\ () +- `Tutorial: Digital Pins `_ + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/double.rst b/source/lang/double.rst new file mode 100644 index 0000000..b4a1219 --- /dev/null +++ b/source/lang/double.rst @@ -0,0 +1,51 @@ +.. _lang-double: + +double +====== + +Description +----------- + +Double precision floating point number. Occupies 8 bytes. On Maple, +the ``double`` type has a range of approximately -1.79769×10^308 to +1.79769×10^308; the ``double`` type subject to the same :ref:`overflow +issues ` as any numeric data type. + +Floating point numbers are not exact, and may yield strange results +when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You +should instead check that the absolute value of the difference between +the numbers is less than some small number. + +Floating point math is also much slower than integer math in +performing calculations, so should be avoided if, for example, a loop +has to run at top speed for a critical timing function. Programmers +often go to some lengths to convert floating point calculations to +integer math to increase speed. + +For more information, see the `Wikipedia article on floating point +math `_\ . + +Floating-point numbers represent numbers with "decimal point", unlike +integral types, which always represent whole numbers. Floating-point +numbers are often used to approximate analog and continuous values +because they have greater resolution than integers. + +The double implementation on the Maple uses twice the number of bytes +as a :ref:`float `, with the corresponding gains in +precision. + +Tip +--- + +Users who borrow code from other sources that includes ``double`` +variables may wish to examine the code to see if the implied range and +precision are different from that actually achieved on the Maple. + +See Also +-------- + +- :ref:`float ` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/doublecast.rst b/source/lang/doublecast.rst new file mode 100644 index 0000000..4ea1776 --- /dev/null +++ b/source/lang/doublecast.rst @@ -0,0 +1,30 @@ +.. highlight:: cpp + +.. _lang-doublecast: + +double() (cast) +=============== + +Description +----------- + +Converts a value to the :ref:`double ` floating point +data type. Here is an example:: + + int x = 2; + double d = double(x); // d now holds 2.0, a double value + +The value ``x`` can be of any type. However, if ``x`` is not a number +(like an ``int`` or ``long``), you will get strange results. + +See the :ref:`double ` reference for details about the +precision and limitations of ``double`` values on the Maple. + +See Also +-------- + +- :ref:`double ` +- :ref:`float ` +- :ref:`float() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/dowhile.rst b/source/lang/dowhile.rst new file mode 100644 index 0000000..77e02a3 --- /dev/null +++ b/source/lang/dowhile.rst @@ -0,0 +1,27 @@ +.. highlight:: cpp + +.. _lang-dowhile: + +do/while Loop +============= + +A ``do`` loop works in the same manner as a :ref:`while +` loop, with the exception that the condition is tested +at the end of the loop, so the ``do`` loop will *always* run at least +once. + +This is the basic syntax:: + + do { + // statement block + } while (test condition); + +Example:: + + do { + delay(50); // wait for sensors to stabilize + x = readSensors(); // check the sensors + } while (x < 100); + + +.. include:: cc-attribution.txt diff --git a/source/lang/else.rst b/source/lang/else.rst new file mode 100644 index 0000000..863f21b --- /dev/null +++ b/source/lang/else.rst @@ -0,0 +1,54 @@ +.. highlight:: cpp + +.. _lang-else: + +if/else +======= + +``if``/\ ``else`` allows greater control over the flow of code than +the basic :ref:`if ` statement, by allowing multiple tests +to be grouped together. For example, an :ref:`analog input +` could be tested, with one action taken if the +input was less than 500, and another action taken if the input was 500 +or greater. The code would look like this:: + + if (pinFiveInput < 500) { + // action A + } else { + // action B + } + +``else`` can precede another ``if`` test, so that multiple, mutually +exclusive tests can be run at the same time. + +Each test will proceed to the next one until a true test is +encountered. When a true test is found, its associated block of code +is run, and the program then skips to the line following the entire +if/else construction. If no test proves to be true, the default +``else`` block is executed, if one is present, and sets the default +behavior. + + +Note that an ``else if`` block may be used with or without a +terminating ``else`` block, and vice-versa. An unlimited number of +such ``else if`` branches is allowed. Here is a code example:: + + if (pinFiveInput < 500) { + // do Thing A + } else if (pinFiveInput >= 1000) { + // do Thing B + } else { + // do Thing C + } + +Another way to express branching, mutually exclusive tests, is with a +:ref:`switch/case ` statement. + +See Also +-------- + +- :ref:`if ` +- :ref:`switch/case ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/enum.rst b/source/lang/enum.rst new file mode 100644 index 0000000..5ecd99c --- /dev/null +++ b/source/lang/enum.rst @@ -0,0 +1,8 @@ +.. _lang-enum: + +enum +==== + +Stub. + +Reference this from language.rst diff --git a/source/lang/float.rst b/source/lang/float.rst new file mode 100644 index 0000000..ef1a339 --- /dev/null +++ b/source/lang/float.rst @@ -0,0 +1,53 @@ +.. highlight:: cpp + +.. _lang-float: + +float +===== + +Description +----------- + +Single-precision floating point number. Occupies 4 bytes. On Maple, +the ``float`` type has a range of approximately -3.40282×10^38 to +3.40282×10^38; the ``float`` type is subject to the same +:ref:`overflow issues ` as any numeric data +type. + +``float``\ s have only 6-7 decimal digits of precision. That means the +total number of digits, not the number to the right of the decimal +point. You can get more precision by using a :ref:`double +` (which has a precision of about 16 decimal digits). + +The following example declares a ``float`` value named ``myfloat``:: + + float myfloat; + +This example declares a ``float`` value named ``sensorCalibrate``, +with value 1.117:: + + float sensorCalibrate = 1.117; + +The general syntax for declaring a float named ``var`` with value +``val`` is:: + + float var = val; + +Here is a more extended example involving a :ref:`float cast +`:: + + int x; + int y; + float z; + + x = 1; + y = x / 2; // y now contains 0, ints can't hold fractions + z = float(x) / 2; // z now contains .5 + +See Also +-------- + +- :ref:`double ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/floatcast.rst b/source/lang/floatcast.rst new file mode 100644 index 0000000..7476188 --- /dev/null +++ b/source/lang/floatcast.rst @@ -0,0 +1,31 @@ +.. highlight:: cpp + +.. _lang-floatcast: + +float() (cast) +============== + +Description +----------- + +Converts a value to the :ref:`float ` data type. Here +is an example (see the :ref:`constants reference +` for an explanation of the "2.0f"):: + + int x = 2; + float f = float(x); // f now holds 2.0f, a float value + +The value ``x`` can be of any type. However, if ``x`` is not a number +(like an ``int``), you will get strange results. + +See the :ref:`float ` reference for details about the +precision and limitations of ``float`` values on the Maple. + +See Also +-------- + +- :ref:`float ` +- :ref:`double ` +- :ref:`double() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/for.rst b/source/lang/for.rst new file mode 100644 index 0000000..6b00d7a --- /dev/null +++ b/source/lang/for.rst @@ -0,0 +1,142 @@ +.. highlight:: cpp + +.. _lang-for: + +for Loops +========= + +.. contents:: Contents + :local: + +Description +----------- + +A ``for`` loop is used to repeat a block of statements enclosed in +curly braces. ``for`` loops are useful for performing repetitive +operations, and are often used in combination with :ref:`arrays +` to operate on collections of data or multiple +:ref:`pins `. A ``for`` loop is composed of two parts: first, a +*header*, which sets up the for loop, and then a *body*, which is made +up of lines of code enclosed in curly braces. + +There are three parts to the ``for`` loop header: an *initialization* +expression, *loop condition* expression, and a *post-loop* +expression. The general syntax looks like this:: + + for (initialization; condition; post-loop) { + // all of these lines inside the curly braces are part + // of the loop body. + statement 1; + statement 2; + ... + } + +(Note that there is no semicolon after the post-loop). The +initialization happens first and exactly once, before the loop begins. +Each time through the loop, the condition is tested. The condition is +a :ref:`boolean ` expression. If it is true, then the +list of statements inside the curly braces are executed. Next, the +post-loop is executed. The loop then begins again by evaluating the +condition again, entering the loop body if it is true. This proceeds +until the condition becomes false. + +Examples +-------- + +Here's an example:: + + // Dim an LED using a PWM pin + int pwmPin = 9; // LED in series with 470 ohm resistor on pin 9 + + void setup() { + pinMode(pwmPin, PWM); + } + + void loop() { + for (int i=0; i <= 65535; i++) { + pwmWrite(pwmPin, i); + delay(1); + } + } + +There is a ``for`` loop In the :ref:`loop() ` function of +the above example. This loop starts by declaring an ``int`` variable +named ``i``, whose value starts out at zero. The loop proceeds by +checking if ``i`` is less than or equal to 65535. Since ``i`` is +zero, this is true, and so the calls to :ref:`pwmWrite() +` and :ref:`delay() ` happen next. At this +point, the post-loop expression ``i++`` is evaluated, which +:ref:`increments ` ``i``, so that ``i`` becomes one. +That concludes the first time through the loop. Each "time through +the loop" is referred to as an *iteration*. + +The loop then jumps back to the beginning, checking the condition as +the beginning of its second iteration (initialization is skipped, +since this only happens once, before the first iteration). One is +less than 65535, so the loop statements are executed again. This +proceeds over and over until the iteration when ``i`` finally +reaches 65536. At that point, the condition is no longer true, so the +loop stops executing, and the ``loop()`` function returns. + +Here's another example, using a ``for`` loop to brighten and fade an +LED (see the :ref:`pwmWrite() ` reference for more +information):: + + int pwmPin = 9; // hook up the LED to pin 9 + void loop() { + int x = 1; + for (int i = 0; i >= 0; i += x) { + analogWrite(pwmPin, i); // controls the brightness of the LED + if (i == 65535) { + x = -1; // switch direction, so i starts decreasing + } + delay(1); + } + } + +Coding Tips +----------- + +The C ``for`` loop is more flexible than ``for`` loops found in some +other computer languages, including BASIC. Any or all of the three +header elements may be left blank, although the semicolons are +required. Also the statements for initialization, condition, and +post-loop can be any valid C statements, and use any C datatypes, +including :ref:`floating point numbers `. These types +of unusual ``for`` loops sometimes provide solutions to less-common +programming problems. + +For example, using a multiplication in the post-loop line will +generate a `geometric progression +`_:: + + for(int x = 1; x <= 100; x = x * 2) { + SerialUSB.println(x); + } + + +This loop prints out the numbers 1, 2, 4, 8, ..., 64. Check +your understanding of ``for`` loops by answering the following two +questions (answers are in footnote [#fanswers]_\ ): + +1. How many iterations occur before the loop finishes? + +2. Why does it stop at 64? + +See also +-------- + +- :ref:`while ` loops +- :ref:`do ` loops + +.. rubric:: Footnotes + +.. [#fanswers] + 1. Seven. + + 2. After the seventh iteration, the post-loop causes ``x`` to + equal 128. This is larger than 100, so the loop condition is + false, and the loop stops. + + +.. include:: cc-attribution.txt diff --git a/source/lang/goto.rst b/source/lang/goto.rst new file mode 100644 index 0000000..96a6262 --- /dev/null +++ b/source/lang/goto.rst @@ -0,0 +1,130 @@ +.. highlight:: cpp + +.. _lang-goto: + +Labels and goto +=============== + +A *label* gives a name to a line of code within a function. You can +label a line by writing a name for it, then a colon (``:``), before +the line starts. The ``goto`` keyword allows program flow to transfer +to a labeled line from anywhere within the same function. + +.. warning:: The use of ``goto`` is discouraged in C and C++ + programming. It is *never necessary* to use ``goto`` to write a + program. + + Unless you know what you're doing, using ``goto`` tends to + encourage code which is harder to debug and understand than + programs without ``goto`` that do the same thing. That said, + however, it's sometimes useful; :ref:`see below ` + for a concrete example. + +Using Labels and goto +--------------------- + +Labels and ``goto`` are probably best explained through example. +Let's start with an example of how to label lines. The first line +(``int x = analogRead(some_pin);``) in the :ref:`loop ` +function below has label ``readpin``. The third line (``delay(x);``) +has label ``startdelay``. The second line (``SerialUSB.println(x);``) +does not have a label:: + + void loop() { + readpin: + int x = analogRead(some_pin); + SerialUSB.println(x); // for debugging + startdelay: + delay(x); + // ... more code ... + } + +Anything which can be a :ref:`variable ` name can +be a label. + +Let's say that we wanted to print ``x`` only if it was very large, say +at least 2000. We might want to do this just so anybody watching on a +:ref:`serial monitor ` would know they were in for +a longer wait than usual. We can accomplish this through the use of a +``goto`` statement that skips the printing if ``x`` is less than +2000:: + + void loop() { + readpin: + int x = analogRead(some_pin); + if (x < 2000) { + goto startdelay; + } + SerialUSB.println(x); // for debugging + startdelay: + delay(x); + // ... more code ... + } + +In this modified program, whenever ``x`` is less than 2000, the body +of the :ref:`if ` statement in the second line is +executed. The ``goto`` statement inside the ``if`` body skips +straight to the line labeled ``startdelay``, passing over the line +doing the printing. + +A ``goto`` does not have to "move forwards"; it can go "backwards", +too. For example, the following program prints "5" forever (why?):: + + void loop() { + printfive: + SerialUSB.println(5); + goto printfive; + SerialUSB.println(6); + } + +.. _goto-when-to-use: + +When to Use goto +---------------- + +As mentioned above, use of ``goto`` is `generally discouraged +`_. However, +when used with care, ``goto`` can simplify certain programs. One +important use case for ``goto`` is breaking out of deeply nested +:ref:`for ` loops or :ref:`if ` logic blocks. +Here's an example:: + + for(int r = 0; r < 255; r++) { + for(int g = 255; g > -1; g--) { + for(int b = 0; b < 255; b++) { + if (analogRead(0) > 250) { + goto bailout; + } + // more statements ... + } + // innermost loop ends here + } + } + bailout: + // more code here + +In the above example, whenever the :ref:`analog reading +` on pin 0 was greater than 250, the program would +jump to the line labeled ``bailout``, exiting all three loops at once. + +While there is already a :ref:`break ` keyword for +breaking out of a loop, it will only break out of the *innermost* +loop. So, if instead of saying "``goto bailout;``", there was a +"``break;``" instead, the program would only exit from the loop with +header "``for(int b = 0; b < 255; b++)``". The program would continue +at the line which reads "``// innermost loop ends here``", which is +clearly undesirable if you wanted to leave all three loops at once. + +More examples of when ``goto`` is a good choice are given in Donald +Knuth's paper, "Structured Programming with go to Statements"; see +below for a link. + +See Also +-------- + +- Dijkstra, Edsger W. `Go To Statement Considered Harmful `_ (PDF) + +- Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) + + +.. include:: cc-attribution.txt diff --git a/source/lang/highbyte.rst b/source/lang/highbyte.rst new file mode 100644 index 0000000..af0bfcd --- /dev/null +++ b/source/lang/highbyte.rst @@ -0,0 +1,53 @@ +.. _lang-highbyte: + +highByte(x) +=========== + +.. warning:: This macro is provided for compatibility with Arduino + only. It returns the second-least significant byte in an integral + value. It makes sense to call this the "high" byte on a 16-bit + ``int`` microcontroller like the Atmel chips on Arduinos, but it + makes no sense at all on a 32-bit microcontroller like the STM32s + in the Maple line. + + In short: we provide this so that existing Arduino code works as + expected, but **strongly discourage its use** in new programs. + +Description +----------- + +(Macro) Extracts the second lowest byte of an integral data type. + +Parameters +---------- + +**x**: a value of any integral type. + +Returns +------- + +Second lowest byte in **x**. + +Example +------- + +:: + + int x = 0xDEADBEEF; + SerialUSB.println(x, HEX); // prints "BE" + +Arduino Compatibility +--------------------- + +The Maple version of ``highByte()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`lowByte() ` + + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/if.rst b/source/lang/if.rst new file mode 100644 index 0000000..02ba1e7 --- /dev/null +++ b/source/lang/if.rst @@ -0,0 +1,81 @@ +.. highlight:: cpp + +.. _lang-if: + +if Statements +============= + +An ``if`` statement is used to execute code when certain conditions +are met. The general syntax for an ``if`` statement is:: + + if (condition) { + body + } + +An ``if`` statement first tests whether its *condition* is true (such +as an input being above a certain number). If the condition is true, +the ``if`` statement executes its *body*, which is made up of lines of +code inside :ref:`curly braces `. If the condition is +false, the body is not executed. Here's a more concrete example:: + + if (someVariable > 50) { + // do something here + } + +The program tests to see if ``someVariable`` is greater than 50. If it +is, the program executes every line in the curly braces (which in the +above example does nothing, since the body is just the :ref:`comment +` line "``// do something here``"). + +Put another way, if the statement in parentheses is true, the +statements inside the braces are run. If not, the program skips over +the code. + +An ``if`` statement's condition (which is inside the parentheses after +``if``) often uses one or more :ref:`boolean ` or +:ref:`comparison ` operators. + +Writing the if Body +------------------- + +The brackets may be omitted after an ``if`` statement's +conditional. If this is done, the next line (which ends in a +semicolon) becomes the only line in the body. The following three +``if`` statements all do the same thing:: + + if (x > 120) digitalWrite(ledPin, HIGH); + + if (x > 120) + digitalWrite(ledPin, HIGH); + + if (x > 120) { + digitalWrite(ledPin, HIGH); + } + +However, the following two examples are different:: + + // example 1: two lines of code in the if body + if (x > 120) { + digitalWrite(ledPin1, HIGH); + digitalWrite(ledPin2, HIGH); + } + + // example 2: one line of code in the if body, and + // another line of code after the if statement + if (x > 120) + digitalWrite(ledPin1, HIGH); // this is in the if body + digitalWrite(ledPin2, HIGH); // this is NOT in the if body + +In the first example, since the body is enclosed in curly braces, both +lines are included. In the second example, since the curly braces are +missing, only the first line is in the ``if`` body. + +See Also +-------- + +- :ref:`boolean operators ` +- :ref:`comparison operators ` +- :ref:`else ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/include.rst b/source/lang/include.rst new file mode 100644 index 0000000..a8bc74c --- /dev/null +++ b/source/lang/include.rst @@ -0,0 +1,71 @@ +.. highlight:: cpp + +.. _lang-include: + +#include +======== + +``#include`` is used to include outside libraries in your sketch. +This gives the programmer access to a large group of standard C +libraries (groups of pre-made functions and data types), and also +libraries written especially for Maple. + +Example +------- + +This example (from the `Arduino LiquidCrystal Tutorial +`_) includes a library +that is used to control :ref:`LCD displays `:: + + // include the library code: + #include + + // initialize the library with the numbers of the interface pins + LiquidCrystal lcd(12, 11, 5, 4, 3, 2); + + void setup() { + // set up the LCD's number of columns and rows: + lcd.begin(16, 2); + // Print a message to the LCD. + lcd.print("hello, world!"); + } + + void loop() { + // set the cursor to column 0, line 1 + // (note: line 1 is the second row, since counting begins with 0): + lcd.setCursor(0, 1); + // print the number of seconds since reset: + lcd.print(millis()/1000); + } + +Note that a ``#include`` line, like :ref:`#define `, +has **no semicolon**. The compiler will print strange error messages +if you add one. + +C Standard Library +------------------ + +The standard C library that comes with Maple is called `newlib +`_. Its main sources of documentation +are its `main reference `_ +page and its `math functions +`_ reference page. Here's an +example that imports the math.h library in order to take the `cube +root `_ of a number:: + + #include + + void setup() { + // no setup necessary + } + + void loop() { + // "cbrt" stands for "cube root" + double cubeRootOf3 = cbrt(3.0); + // prints a number that is approximately the cube root of 3: + SerialUSB.println(cubeRootOf3); + } + + + +.. include:: cc-attribution.txt diff --git a/source/lang/increment.rst b/source/lang/increment.rst new file mode 100644 index 0000000..5536a0a --- /dev/null +++ b/source/lang/increment.rst @@ -0,0 +1,44 @@ +.. highlight:: cpp + +.. _lang-increment: + +Increment (``++``) and Decrement (``--``) +========================================= + +These operators increment (add one to) or decrement (subtract one +from) a variable. If they come before the variable, they return its +new value; otherwise, they return its old value. + +Some quick examples:: + + x++; // adds one to x, and returns the old value of x + ++x; // adds one to x, and returns the new value of x + + x--; // decrement x by one and returns the old value of x + --x; // decrement x by one and returns the new value of x + +A more extended example:: + + x = 2; + y = ++x; // x now contains 3, y contains 3 + y = x--; // x contains 2 again, y still contains 3 + +.. warning:: Be careful! You cannot put a space in between the two + ``+`` or ``-`` signs. This example is broken:: + + // this line won't compile (notice the extra space): + int y = x+ +; + +Parameters +---------- + +**x**: an integer value (like an ``int``, ``long``, ``unsigned int``, +etc.). + +See also +-------- + +- :ref:`Compound arithmetic operators ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/int.rst b/source/lang/int.rst new file mode 100644 index 0000000..ac2f16a --- /dev/null +++ b/source/lang/int.rst @@ -0,0 +1,67 @@ +.. highlight:: cpp + +.. _lang-int: + +int +=== + +Description +----------- + +The ``int`` data type represents integers. Integers are your primary +data type for number storage, and store a 4 byte value. This yields a +range of -2,147,483,648 to 2,147,483,647 (minimum value of -2^31 and a +maximum value of (2^31) - 1; that's about negative 2 billion to +positive 2 billion). + +An ``int`` stores a negative number with a technique called `two's +complement math +`_\ . +The highest bit in an ``int``, sometimes refered to as the "sign" bit, +flags the number as a negative number. (See the linked article on +two's complement for more information). + +The Maple takes care of dealing with negative numbers for you, so that +arithmetic operations work mostly as you'd expect. There can be an +:ref:`unexpected complication ` in +dealing with the :ref:`bitshift right operator (>>) +`, however. + +Here is an example of declaring an ``int`` variable named ``ledPin``, +then giving it value 13:: + + int ledPin = 13; + +The general syntax for declaring an ``int`` variable named ``var``, +then giving it value ``val``, looks like:: + + int var = val; + +.. _lang-int-overflow: + +Integer Overflow +---------------- + +When ``int`` variables leave the range specified above, they +:ref:`roll over ` in the other direction. +Here are some examples:: + + int x; + x = -2,147,483,648; + x--; // x now contains 2,147,483,647; rolled over "left to right" + + x = 2,147,483,647; + x++; // x now contains -2,147,483,648; rolled over "right to left" + +See Also +-------- + +- :ref:`unsigned int ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`long ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/intcast.rst b/source/lang/intcast.rst new file mode 100644 index 0000000..03c0c07 --- /dev/null +++ b/source/lang/intcast.rst @@ -0,0 +1,32 @@ +.. highlight:: cpp + +.. _lang-intcast: + +int() +===== + +Description +----------- + +Converts a value to the :ref:`int ` data type. Here is +an example:: + + double d = 2.5; + int i = int(d); // i holds "2", an int value + +The value inside of the parentheses (``int(...)``) can be of any type. +However, if it is not a numeric type (like ``double``, ``char``, +etc.), you will get strange results. + +See the :ref:`int ` reference for details about the +precision and limitations of ``int`` variables on the Maple. + +See Also +-------- + +- :ref:`int ` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/interrupts.rst b/source/lang/interrupts.rst new file mode 100644 index 0000000..5ca7041 --- /dev/null +++ b/source/lang/interrupts.rst @@ -0,0 +1,62 @@ +.. _lang-interrupts: + +interrupts() +============ + +Description +----------- + +Re-enables interrupts (after they've been disabled by +`noInterrupts `_\ ()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None + + + +Returns +------- + +None + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `noInterrupts `_\ () +- `attachInterrupt `_\ () +- `detachInterrupt `_\ () + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/keywords.rst b/source/lang/keywords.rst new file mode 100644 index 0000000..451701e --- /dev/null +++ b/source/lang/keywords.rst @@ -0,0 +1,11 @@ +.. _lang-keywords: + +Keywords +======== + +Stub. + +Include list of all C++ keywords, with links to internal documentation +as appropriate. + +Reference this page from language.rst diff --git a/source/lang/long.rst b/source/lang/long.rst new file mode 100644 index 0000000..8a19b2b --- /dev/null +++ b/source/lang/long.rst @@ -0,0 +1,55 @@ +.. highlight:: cpp + +.. _lang-long: + +long +==== + +Description +----------- + +The ``long`` data type stores extended size integer values. You can +use a ``long`` when your values are too large to fit into an :ref:`int +`. A ``long`` occupies 8 bytes of memory. This yields a +range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion +billion, or about 92 million times the number of stars in the Milky +Way galaxy). The exact range of a ``long`` on the Maple is from +-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to +(2^63-1). A ``long`` it is subject to the same :ref:`overflow issues +` as any numeric data type. + +Here's an example of declaring a long (see :ref:`integer constants +` for an explanation of the "L" at the end of the +number):: + + // Speed of light in nanometers per second (approximate). + long c = 299792458000000000L; + +The general syntax for declaring an ``long`` variable named ``var``, +then giving it value ``val``, looks like:: + + long var = val; + +This is identical to the ``int`` syntax, with ``long`` replacing +``int``. + +Note that ``long`` values will still :ref:`overflow +`, just like ``int`` values, but their much +larger range makes this less likely to happen. + +The downside to using a ``long`` instead of an ``int`` (besides the +extra storage) is that :ref:`arithmetic ` operations +on ``long``\ s will take slightly longer than on ``int``\ s. + +See Also +-------- + +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`int ` +- :ref:`unsigned int ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/longcast.rst b/source/lang/longcast.rst new file mode 100644 index 0000000..16d7582 --- /dev/null +++ b/source/lang/longcast.rst @@ -0,0 +1,30 @@ +.. highlight:: cpp + +.. _lang-longcast: + +long() +====== + +Description +----------- + +Converts a value to the :ref:`long ` data type. Here is +an example:: + + double d = 2.5; + long i = long(d); // i holds "2L", an long value + +The value inside of the parentheses (``long(...)``) can be of any type. +However, if it is not a numeric type (like ``double``, ``char``, +etc.), you will get strange results. + +See the :ref:`long ` reference for details about the +precision and limitations of ``long`` variables on the Maple. + +See Also +-------- + +- :ref:`long ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/loop.rst b/source/lang/loop.rst new file mode 100644 index 0000000..d8f6183 --- /dev/null +++ b/source/lang/loop.rst @@ -0,0 +1,45 @@ +.. highlight:: cpp + +.. _lang-loop: + +loop() +====== + +After creating a :ref:`setup() ` function, which +initializes your sketch, the ``loop()`` function gets called +repeatedly, allowing your program to change and respond. Use it to +actively control your Maple board. + +Example +------- + +:: + + + int buttonPin = 38; + + // setup initializes serial and the button pin + void setup() { + SerialUSB.begin(); + pinMode(buttonPin, INPUT); + } + + // loop() checks the button pin each time it executes, + // and will print 'H' if it is pressed, 'L' otherwise + void loop() { + if (digitalRead(buttonPin) == HIGH) { + SerialUSB.println('H'); + } else { + SerialUSB.println('L'); + } + + delay(1000); + } + +See Also +-------- + +- :ref:`setup() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/lowbyte.rst b/source/lang/lowbyte.rst new file mode 100644 index 0000000..f9fb711 --- /dev/null +++ b/source/lang/lowbyte.rst @@ -0,0 +1,45 @@ +.. _lang-lowbyte: + +lowByte() +========= + +Description +----------- + +Extracts the low-order (rightmost) byte of a variable (e.g. a +word). + + + +Syntax +------ + +lowByte(x) + + + +Parameters +---------- + +x: a value of any type + + + +Returns +------- + +byte + + + +See also +-------- + + +- `highByte `_\ () +- `word `_\ () + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/map.rst b/source/lang/map.rst new file mode 100644 index 0000000..40b12a8 --- /dev/null +++ b/source/lang/map.rst @@ -0,0 +1,122 @@ +.. _lang-map: + +map(value, fromLow, fromHigh, toLow, toHigh) +============================================ + +Description +----------- + +Re-maps a number from one range to another. That is, a **value** of +**fromLow** would get mapped to **toLow**, a value of **fromHigh** +to **toHigh**, values in-between to values in-between, etc. + + + +Does not constrain values to within the range, because out-of-range +values are sometimes intended and useful. The constrain() function +may be used either before or after this function, if limits to the +ranges are desired. + + + +Note that the "lower bounds" of either range may be larger or +smaller than the "upper bounds" so the map() function may be used +to reverse a range of numbers, for example + + + +``y = map(x, 1, 50, 50, 1);`` + + + +The function also handles negative numbers well, so that this +example + + + +``y = map(x, 1, 50, 50, -100);`` + + + +is also valid and works well. + + + +The map() function uses integer math so will not generate +fractions, when the math might indicate that it should do so. +Fractional remainders are truncated, and are not rounded or +averaged. + + + +Parameters +---------- + +value: the number to map + + + +fromLow: the lower bound of the value's current range + + + +fromHigh: the upper bound of the value's current range + + + +toLow: the lower bound of the value's target range + + + +toHigh: the upper bound of the value's target range + + + +Returns +------- + +The mapped value. + + + +Example +------- + +:: + + /* Map an analog value to 8 bits (0 to 255) */ + void setup() {} + + void loop() + { + int val = analogRead(0); + val = map(val, 0, 1023, 0, 255); + analogWrite(9, val); + } + + + +Appendix +~~~~~~~~ + +For the mathematically inclined, here's the whole function + + + +:: + + long map(long x, long in_min, long in_max, long out_min, long out_max) + { + return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; + } + + + +See Also +-------- + + +- `constrain `_\ () + + +.. include:: cc-attribution.txt diff --git a/source/lang/max.rst b/source/lang/max.rst new file mode 100644 index 0000000..7dbf6a7 --- /dev/null +++ b/source/lang/max.rst @@ -0,0 +1,63 @@ +.. highlight:: cpp + +.. _lang-max: + +max(x, y) +========= + +Description +----------- + +(Macro) Calculates the maximum of two numbers. + + + +Parameters +---------- + +**x**: the first number; may be any number or numeric expression. + +**y**: the second number; may be any number or numeric expression. + + +Returns +------- + +The larger of the two parameter values. + +Example +------- + +:: + + sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 + // (effectively ensuring that it is at least 20) + +.. note:: Perhaps counter-intuitively, max() is often used to + constrain the lower end of a variable's range, while :ref:`min() + ` is used to constrain the upper end of the range. + +Warning +------- + +Because of the way ``max()`` is implemented, avoid using other +functions inside the parentheses. It may lead to incorrect results:: + + max(a--, 0); // avoid this - yields incorrect results + + a--; // use this instead - + max(a, 0); // keep other operations outside max() + +Arduino Compatibility +--------------------- + +The Maple version of ``max()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`min() ` +- :ref:`constrain() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/micros.rst b/source/lang/micros.rst new file mode 100644 index 0000000..711c013 --- /dev/null +++ b/source/lang/micros.rst @@ -0,0 +1,69 @@ +.. _lang-micros: + +micros() +======== + +Description +----------- + +Returns the number of microseconds since the Arduino board began +running the current program. This number will overflow (go back to +zero), after approximately 70 minutes. On 16 MHz Arduino boards +(e.g. Duemilanove and Nano), this function has a resolution of four +microseconds (i.e. the value returned is always a multiple of +four). On 8 MHz Arduino boards (e.g. the LilyPad), this function +has a resolution of eight microseconds. + + + +*Note*: there are 1,000 microseconds in a millisecond and 1,000,000 +microseconds in a second. + + + +Parameters +---------- + +None + + + +Returns +------- + +Number of microseconds since the program started (*unsigned long*) + + + +Example +------- + +:: + + unsigned long time; + + void setup(){ + Serial.begin(9600); + } + void loop(){ + Serial.print("Time: "); + time = micros(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + + + +See also +-------- + + +- `millis `_\ () +- `delay `_\ () +- `delayMicroseconds `_\ () + + + +.. include:: cc-attribution.txt diff --git a/source/lang/millis.rst b/source/lang/millis.rst new file mode 100644 index 0000000..6ebfff5 --- /dev/null +++ b/source/lang/millis.rst @@ -0,0 +1,70 @@ +.. _lang-millis: + +millis() +======== + +Description +----------- + +Returns the number of milliseconds since the Arduino board began +running the current program. This number will overflow (go back to +zero), after approximately 50 days. + + + +Parameters +---------- + +None + + + +Returns +------- + +Number of milliseconds since the program started (*unsigned long*) + + + +Example +------- + +:: + + unsigned long time; + + void setup(){ + Serial.begin(9600); + } + void loop(){ + Serial.print("Time: "); + time = millis(); + //prints time since program started + Serial.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + + + +Tip: +---- + +Note that the parameter for millis is an unsigned long, errors may +be generated if a programmer tries to do math with other datatypes +such as ints. + + + +See also +-------- + + +- `micros `_\ () +- `delay `_\ () +- `delayMicroseconds `_\ () +- `Tutorial: Blink Without Delay `_ + + + +.. include:: cc-attribution.txt diff --git a/source/lang/min.rst b/source/lang/min.rst new file mode 100644 index 0000000..ffbf1ee --- /dev/null +++ b/source/lang/min.rst @@ -0,0 +1,66 @@ +.. highlight:: cpp + +.. _lang-min: + +min(x, y) +========= + +Description +----------- + +(Macro) Calculates the minimum of two numbers. + + + +Parameters +---------- + +**x**: the first number; may be any number or numeric expression. + +**y**: the second number; may be any number or numeric expression. + + +Returns +------- + +The smaller of the two numbers. + + +Example +------- + +:: + + sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 + // ensuring that it never gets above 100. + + +.. note:: Perhaps counter-intuitively, max() is often used to + constrain the lower end of a variable's range, while min() is used + to constrain the upper end of the range. + + +Warning +------- + +Because of the way ``min()`` is implemented, avoid using other +functions inside the parentheses. It may lead to incorrect results:: + + min(a++, 100); // avoid this - yields incorrect results + + a++; // use this instead - + min(a, 100); // keep other operations outside min() + +Arduino Compatibility +--------------------- + +The Maple version of ``min()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`max() ` +- :ref:`constrain() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/modulo.rst b/source/lang/modulo.rst new file mode 100644 index 0000000..9e0dabd --- /dev/null +++ b/source/lang/modulo.rst @@ -0,0 +1,77 @@ +.. highlight:: cpp + +.. _lang-modulo: + +% (modulo) +========== + +Description +----------- + +Calculates the `remainder `_ +when one integer is divided by another. It is useful for keeping a +variable within a particular range (e.g. the size of an array). + +Syntax +------ + +:: + + result = dividend % divisor + + + +Parameters +---------- + +**dividend**: the number to be divided + +**divisor**: the number to divide by + +Returns +------- + +The remainder of **dividend**\ /\ **divisor**\ . + +Examples +-------- + +:: + + int x; + x = 7 % 5; // x now contains 2 + x = 9 % 5; // x now contains 4 + x = 5 % 5; // x now contains 0 + x = 4 % 5; // x now contains 4 + +:: + + /* update one value in an array each time through a loop */ + + int values[10]; + int i = 0; + + void setup() { + // no setup necessary + } + + void loop() { + values[i] = analogRead(0); + i = (i + 1) % 10; // modulo operator makes sure i stays between 0 and 9 + } + +Tip +--- + +The modulo operator does not work on floats. For that, you can use +the C standard library function `fmod() +`_. + + +See Also +-------- + +- :ref:`Arithmetic ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/nointerrupts.rst b/source/lang/nointerrupts.rst new file mode 100644 index 0000000..2043c91 --- /dev/null +++ b/source/lang/nointerrupts.rst @@ -0,0 +1,59 @@ +.. _lang-nointerrupts: + +noInterrupts() +============== + +Description +----------- + +Disables interrupts (you can re-enable them with interrupts()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None. + + + +Returns +------- + +None. + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `interrupts `_\ () + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/notone.rst b/source/lang/notone.rst new file mode 100644 index 0000000..22432e2 --- /dev/null +++ b/source/lang/notone.rst @@ -0,0 +1,50 @@ +.. _lang-notone: + +noTone() +======== + +Description +----------- + +Stops the generation of a square wave triggered by +`tone `_\ (). Has no effect if +no tone is being generated. + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +noTone(pin) + + + +Parameters +---------- + +pin: the pin on which to stop generating the tone + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `tone `_ () + + + +.. include:: cc-attribution.txt diff --git a/source/lang/pinmode.rst b/source/lang/pinmode.rst new file mode 100644 index 0000000..aed23d6 --- /dev/null +++ b/source/lang/pinmode.rst @@ -0,0 +1,76 @@ +.. highlight:: cpp + +.. _lang-pinmode: + +pinMode() +========= + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: pinMode + +.. doxygenenum:: WiringPinMode + +Discussion +---------- + +pinMode() is usually called within :ref:`lang-setup` in order to +configure a pin for a certain usage (although it may be called +anywhere). + + +Example +------- + + :: + + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() + { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() + { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + + + +Arduino Compatibility +--------------------- + +The libmaple implementation of pinMode() supports OUTPUT and INPUT +modes with a meaning identical to that of the Arduino function. + +INPUT_ANALOG and PWM modes were added because the Maple does not +distinguish between analog and digital pins the same way the Arduino +does. Unlike the Arduino, you **must call pinMode**\ () to set up a pin +for these purposes before a call to, e.g., :ref:`lang-analogRead`. +In practice, this should only add a few lines of pinMode() calls to +your :ref:`lang-setup` function. + +OUTPUT_OPEN_DRAIN, INPUT_PULLUP, INPUT_PULLDOWN, and PWM_OPEN_DRAIN +modes represent functionality not currently available on Arduino +boards. + +See also +-------- + +- :ref:`lang-constants` +- :ref:`lang-digitalwrite` +- :ref:`lang-digitalread` +- Maple :ref:`GPIO ` reference page + + + +.. include:: cc-attribution.txt diff --git a/source/lang/pointer.rst b/source/lang/pointer.rst new file mode 100644 index 0000000..bc48d7d --- /dev/null +++ b/source/lang/pointer.rst @@ -0,0 +1,28 @@ +.. _lang-pointer: + +The pointer operators: & (reference) and \* (dereference) +========================================================= + + +Pointers are one of the more complicated subjects for beginners in +learning C, and it is possible to write the vast majority of +Arduino sketches without ever encountering pointers. However for +manipulating certain data structures, the use of pointers can +simplify the code, and and knowledge of manipulating pointers is +handy to have in one's toolkit. + +Introducing pointers is somewhat outside the scope of this +documentation. However, a good `pointer tutorial +`_ is available. +Also see the `Wikipedia article on pointers +`_, especially +the section on `pointers in C +`_. + +See Also +======== + +- http://xkcd.com/138/ + + +.. include:: cc-attribution.txt diff --git a/source/lang/pow.rst b/source/lang/pow.rst new file mode 100644 index 0000000..dbe89b6 --- /dev/null +++ b/source/lang/pow.rst @@ -0,0 +1,29 @@ +.. _lang-pow: + +pow(base, exponent) +=================== + +Calculates the value of a number raised to a power. + +Library Documentation +--------------------- + +.. doxygenfunction:: pow + +Example +------- + +``pow()`` can be used to raise a number to a fractional power. This +is useful for e.g. generating exponential mapping of values or +curves. See the `fscale `_ +function in the Arduino playground for more on this. + +See Also +-------- + +- :ref:`sqrt() ` +- :ref:`float ` +- :ref:`double ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/pulsein.rst b/source/lang/pulsein.rst new file mode 100644 index 0000000..7bbe84c --- /dev/null +++ b/source/lang/pulsein.rst @@ -0,0 +1,82 @@ +.. _lang-pulsein: + +pulseIn() +========= + +Description +----------- + +Reads a pulse (either HIGH or LOW) on a pin. For example, if +**value** is **HIGH**, **pulseIn()** waits for the pin to go +**HIGH**, starts timing, then waits for the pin to go **LOW** and +stops timing. Returns the length of the pulse in microseconds. +Gives up and returns 0 if no pulse starts within a specified time +out. + + + +The timing of this function has been determined empirically and +will probably show errors in longer pulses. Works on pulses from 10 +microseconds to 3 minutes in length. + + + +Syntax +------ + +pulseIn(pin, value) +pulseIn(pin, value, timeout) + + + +Parameters +---------- + +pin: the number of the pin on which you want to read the pulse. +(*int*) + + + +value: type of pulse to read: either +`HIGH `_ or +`LOW `_. (*int*) + + + +timeout (optional): the number of microseconds to wait for the +pulse to start; default is one second (*unsigned long*) + + + +Returns +------- + +the length of the pulse (in microseconds) or 0 if no pulse started +before the timeout (*unsigned long*) + + + +Example +------- + +:: + + + + int pin = 7; + unsigned long duration; + + void setup() + { + pinMode(pin, INPUT); + } + + void loop() + { + duration = pulseIn(pin, HIGH); + } + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/pwmwrite.rst b/source/lang/pwmwrite.rst new file mode 100644 index 0000000..acc0240 --- /dev/null +++ b/source/lang/pwmwrite.rst @@ -0,0 +1,51 @@ +.. highlight:: cpp + +.. _lang-pwmwrite: + +pwmWrite() +========== + +Writes a :ref:`PWM wave ` to a pin. You can use this to make an +LED get brighter or dimmer, control a servomotor, etc. After a call to +pwmWrite(), the pin will output a steady square wave with the given +duty cycle. You can change the duty cycle later by calling pwmWrite() +again with the same pin and a different duty. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: pwmWrite + +Example +------- + +Sets the output to the LED proportional to the value read from the +potentiometer (adapted for Maple from the Arduino `analogWrite() +reference `_):: + + + int ledPin = 13; // LED connected to pin 13 (Maple) + int analogPin = 3; // potentiometer connected to analog pin 3 + int val = 0; // variable to store the read value + + void setup() { + pinMode(ledPin, OUTPUT); // sets the LED pin as output + + pinMode(analogPin, PWM); // sets the potentiometer pin as PWM + // output + } + + void loop() { + val = analogRead(analogPin); // read the input pin + + analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, + // analogWrite values from 0 to 65535 + } + +See Also +-------- + +- :ref:`Maple PWM tutorial ` diff --git a/source/lang/random.rst b/source/lang/random.rst new file mode 100644 index 0000000..51bee67 --- /dev/null +++ b/source/lang/random.rst @@ -0,0 +1,95 @@ +.. _lang-random: + +random() +======== + +Description +----------- + +The random function generates pseudo-random numbers. + + + +Syntax +------ + +random(max) +random(min, max) + + + +Parameters +---------- + +min - lower bound of the random value, inclusive *(optional)* + + + +max - upper bound of the random value, exclusive + + + +Returns +------- + +a random number between min and max-1 (*long*) + + + +Note: +----- + +If it is important for a sequence of values generated by random() +to differ, on subsequent executions of a sketch, use randomSeed() +to initialize the random number generator with a fairly random +input, such as analogRead() on an unconnected pin. + + + +Conversely, it can occasionally be useful to use pseudo-random +sequences that repeat exactly. This can be accomplished by calling +randomSeed() with a fixed number, before starting the random +sequence. + + + +Example +------- + +:: + + long randNumber; + + void setup(){ + Serial.begin(9600); + + // if analog input pin 0 is unconnected, random analog + // noise will cause the call to randomSeed() to generate + // different seed numbers each time the sketch runs. + // randomSeed() will then shuffle the random function. + randomSeed(analogRead(0)); + } + + void loop() { + // print a random number from 0 to 299 + randNumber = random(300); + Serial.println(randNumber); + + // print a random number from 10 to 19 + randNumber = random(10, 20); + Serial.println(randNumber); + + delay(50); + } + + + +See also +-------- + + +- `randomSeed `_\ () + + + +.. include:: cc-attribution.txt diff --git a/source/lang/randomseed.rst b/source/lang/randomseed.rst new file mode 100644 index 0000000..3dcf4db --- /dev/null +++ b/source/lang/randomseed.rst @@ -0,0 +1,73 @@ +.. _lang-randomseed: + +randomSeed(seed) +================ + +Description +----------- + +randomSeed() initializes the pseudo-random number generator, +causing it to start at an arbitrary point in its random sequence. +This sequence, while very long, and random, is always the same. + + + +If it is important for a sequence of values generated by random() +to differ, on subsequent executions of a sketch, use randomSeed() +to initialize the random number generator with a fairly random +input, such as analogRead() on an unconnected pin. + + + +Conversely, it can occasionally be useful to use pseudo-random +sequences that repeat exactly. This can be accomplished by calling +randomSeed() with a fixed number, before starting the random +sequence. + + + +Parameters +---------- + +long, int - pass a number to generate the seed. + + + +Returns +------- + +no returns + + + +Example +------- + +:: + + long randNumber; + + void setup(){ + Serial.begin(9600); + randomSeed(analogRead(0)); + } + + void loop(){ + randNumber = random(300); + Serial.println(randNumber); + + delay(50); + } + + + +See also +-------- + + +- `random `_ + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/return.rst b/source/lang/return.rst new file mode 100644 index 0000000..e1b2924 --- /dev/null +++ b/source/lang/return.rst @@ -0,0 +1,61 @@ +.. highlight:: cpp + +.. _lang-return: + +return +====== + +(Keyword) Terminates a function and return a value from a function to +the calling function, if the function has non-``void`` return type. + +Syntax: +------- + +:: + + // from within a "void" function: + return; + + // from within a non-"void" function: + return value; + +In the second case, ``value`` should have a type which is the same as +the return type of the function, or be convertible to it (like an +``int`` to a ``long``, etc.; see :ref:`this note +` for some references). + +Examples: +--------- + +A function to compare a sensor input to a threshold:: + + // converts analog readings between 0 and 400 to 0, and 400 up to 1. + int checkSensor() { + if (analogRead(0) > 400) { + return 1; + else { + return 0; + } + } + +An early ``return`` is also useful when testing a section of code +without having to "comment out" large sections of possibly buggy code, +like so:: + + void loop() { + + // brilliant code idea to test here + + return; + + // the rest of a dysfunctional sketch here + // this code will never be executed + } + +See Also +-------- + +- :ref:`comments ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/scope.rst b/source/lang/scope.rst new file mode 100644 index 0000000..8e8bb13 --- /dev/null +++ b/source/lang/scope.rst @@ -0,0 +1,120 @@ +.. highlight:: cpp + +.. _lang-scope: + +Variable Scope +============== + +Variables in the C++ programming language, which Maple uses (all of +your sketches are C++ programs in disguise), have a property called +*scope*. Simply put, a variable's scope is made up of all of the +lines where the variable can be used. + +Scope in C++ is a fairly complex topic, so we won't try to describe it +in full here. Instead, we present a simplified view, describing two +different kinds of scopes, *global* and *local*. For more detailed +information, consult a C++ reference. + +Global and Local Variables +-------------------------- + +A global variable is one that can be "seen" by every function in a +program. In the :ref:`Maple IDE `, any variable declared outside +of a function (like :ref:`setup() ` and :ref:`loop() +`) is a global variable. + +A local variable can only be "seen" inside of a particular function. +You can declare a variable to be local to a function by declaring it +inside of the :ref:`curly braces ` which enclose that +function. + +When programs start to get larger and more complex, local variables +are a useful way to ensure that a function has exclusive access to its +own variables. This prevents programming errors when one function +mistakenly modifies variables used by another function. + +It is also sometimes useful to declare and initialize a variable +inside a :ref:`for ` loop. This creates a variable that +can only be accessed from inside the loop body. + +Example +------- + +Here is an example sketch (which you can copy into the Maple IDE and +run on your Maple) that illustrates the use of global and local +variables, as well as declaring variables inside of a ``for`` loop. +Be sure to open a :ref:`serial monitor ` after you +:ref:`verify ` and :ref:`upload ` the sketch:: + + int globalVar; // any function will see this variable + + void setup() { + // since "globalVar" is declared outside of any function, + // every function can "see" and use it: + globalVar = 50; + + // the variables "i" and "d" declared inside the "loop" function + // can't be seen here. see what happens when you uncomment the + // following lines, and try to Verify (compile) the sketch: + // + // i = 16; + // SerialUSB.print("i = "); + // SerialUSB.println(i); + // d = 26.5; + // SerialUSB.print("d = "); + // SerialUSB.println(d); + } + + void loop() { + // since "i" and "d" are declared inside of the "loop" function, + // they can only be seen and used from inside of it: + int i; + double d; + + for (int j = 0; j < 5; j++) { + // variable i can be used anywhere inside the "loop" function; + // variable j can only be accessed inside the for-loop brackets: + i = j * j; + SerialUSB.print("i = "); + SerialUSB.println(i); + } + + // globalVar can be accessed from anywhere. note how even + // though we set globalVar = 50 in the "setup" function, we can + // see that value here: + SerialUSB.print("globalVar = "); + SerialUSB.println(globalVar); + + // d can be accessed from anywhere inside the "loop" function: + d = 26.5; + SerialUSB.print("d = "); + SerialUSB.print(d); + SerialUSB.println(" (before separateFunction())"); + + separateFunction(); + + // notice how even though separateFunction() has a variable + // named "d", it didn't touch our (local) variable which has + // the same name: + SerialUSB.print("d = "); + SerialUSB.print(d); + SerialUSB.println(" (after separateFunction())"); + } + + void separateFunction() { + // variable "d" here has the same name as variable "d" inside of + // the "loop" function, but since they're both _local_ + // variables, they don't affect each other: + double d = 30.5; + SerialUSB.print("d = "); + SerialUSB.print(d); + SerialUSB.println(" (inside of separateFunction())"); + } + +See Also +-------- + +- `C++ programming Wikibook `_. +- Wikipedia article on `scope `_ + +.. include:: cc-attribution.txt diff --git a/source/lang/semicolon.rst b/source/lang/semicolon.rst new file mode 100644 index 0000000..4cf7b9f --- /dev/null +++ b/source/lang/semicolon.rst @@ -0,0 +1,25 @@ +.. highlight:: cpp + +.. _lang-semicolon: + +Semicolon (;) +============= + +Used to end a line of code. Example:: + + int a = 13; + +Tip +--- + +Forgetting to end a line in a semicolon will result in a compiler +error. The error text may be obvious, and refer to a missing +semicolon, or it may not. If an impenetrable or seemingly illogical +compiler error comes up, one of the first things to check is a +missing semicolon, in the immediate vicinity, preceding the line at +which the compiler complained. + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/serial.rst b/source/lang/serial.rst new file mode 100644 index 0000000..743f921 --- /dev/null +++ b/source/lang/serial.rst @@ -0,0 +1,68 @@ +.. _lang-serial: + +Serial +====== + +Used for communication between the Arduino board and a computer or +other devices. All Arduino boards have at least one serial port +(also known as a UART or USART): **Serial**. It communicates on +digital pins 0 (RX) and 1 (TX) as well as with the computer via +USB. Thus, if you use these functions, you cannot also use pins 0 +and 1 for digital input or output. + + + +You can use the Arduino environment's built-in serial monitor to +communicate with an Arduino board. Click the serial monitor button +in the toolbar and select the same baud rate used in the call to +begin(). + + + +The Arduino Mega has three additional serial ports: **Serial1** on +pins 19 (RX) and 18 (TX), **Serial2** on pins 17 (RX) and 16 (TX), +**Serial3** on pins 15 (RX) and 14 (TX). To use these pins to +communicate with your personal computer, you will need an +additional USB-to-serial adaptor, as they are not connected to the +Mega's USB-to-serial adaptor. To use them to communicate with an +external TTL serial device, connect the TX pin to your device's RX +pin, the RX to your device's TX pin, and the ground of your Mega to +your device's ground. (Don't connect these pins directly to an +RS232 serial port; they operate at +/- 12V and can damage your +Arduino board.) + + + +Functions +--------- + + +- `begin `_\ () +- `end `_\ () +- `available `_\ () +- `read `_\ () +- `flush `_\ () +- `print `_\ () + +.. _lang-serial-println: + +- `println `_\ () +- `write `_\ () + + + +Examples +-------- + + +- `ASCII Table `_ +- `Dimmer `_ +- `Graph `_ +- `Physical Pixel `_ +- `Virtual Color Mixer `_ +- `Serial Call Response `_ +- `Serial Call Response ASCII `_ + + + +.. include:: cc-attribution.txt diff --git a/source/lang/serialusb.rst b/source/lang/serialusb.rst new file mode 100644 index 0000000..730fb07 --- /dev/null +++ b/source/lang/serialusb.rst @@ -0,0 +1,8 @@ +.. _lang-serialusb: + +Serial over USB Communications +============================== + +.. _lang-serialusb-println: + +Stub. diff --git a/source/lang/setup.rst b/source/lang/setup.rst new file mode 100644 index 0000000..6b142d2 --- /dev/null +++ b/source/lang/setup.rst @@ -0,0 +1,34 @@ +.. _lang-setup: + +setup() +======= + +The setup() function is called when a sketch starts. Use it to +initialize variables, pin modes, start using libraries, etc. The +setup function will only run once, after each powerup or reset of +the Arduino board. + + + +Example +~~~~~~~ + +:: + + + int buttonPin = 3; + + void setup() + { + Serial.begin(9600); + pinMode(buttonPin, INPUT); + } + + void loop() + { + // ... + } + + + +.. include:: cc-attribution.txt diff --git a/source/lang/shiftout.rst b/source/lang/shiftout.rst new file mode 100644 index 0000000..e76cc01 --- /dev/null +++ b/source/lang/shiftout.rst @@ -0,0 +1,136 @@ +.. _lang-shiftout: + +shiftOut() +========== + +Description +----------- + +Shifts out a byte of data one bit at a time. Starts from either the +most (i.e. the leftmost) or least (rightmost) significant bit. Each +bit is written in turn to a data pin, after which a clock pin is +pulsed to indicate that the bit is available. + + + +This is a software implementation; Arduino (as of 0019) also +provides an `SPI library `_ +that uses the hardware implementation. + + + +Syntax +------ + +shiftOut(dataPin, clockPin, bitOrder, value) + + + +Parameters +---------- + +dataPin: the pin on which to output each bit (*int*) + + + +clockPin: the pin to toggle once the **dataPin** has been set to +the correct value (*int*) + + + +bitOrder: which order to shift out the bits; either **MSBFIRST** or +**LSBFIRST**. +(Most Significant Bit First, or, Least Significant Bit First) + + + +value: the data to shift out. (*byte*) + + + +Returns +------- + +None + + + +Note +---- + +The **dataPin** and **clockPin** must already be configured as +outputs by a call to +`pinMode `_\ (). + + + +**shiftOut** is currently written to output 1 byte (8 bits) so it +requires a two step operation to output values larger than 255. + +:: + + // Do this for MSBFIRST serial + int data = 500; + // shift out highbyte + shiftOut(dataPin, clock, MSBFIRST, (data >> 8)); + // shift out lowbyte + shiftOut(data, clock, MSBFIRST, data); + + // Or do this for LSBFIRST serial + data = 500; + // shift out lowbyte + shiftOut(dataPin, clock, LSBFIRST, data); + // shift out highbyte + shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); + + + +Example +------- + +*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register `_.* + + + +:: + + //**************************************************************// + // Name : shiftOutCode, Hello World // + // Author : Carlyn Maw,Tom Igoe // + // Date : 25 Oct, 2006 // + // Version : 1.0 // + // Notes : Code for using a 74HC595 Shift Register // + // : to count from 0 to 255 // + //**************************************************************** + + //Pin connected to ST_CP of 74HC595 + int latchPin = 8; + //Pin connected to SH_CP of 74HC595 + int clockPin = 12; + ////Pin connected to DS of 74HC595 + int dataPin = 11; + + void setup() { + //set pins to output because they are addressed in the main loop + pinMode(latchPin, OUTPUT); + pinMode(clockPin, OUTPUT); + pinMode(dataPin, OUTPUT); + } + + void loop() { + //count up routine + for (int j = 0; j < 256; j++) { + //ground latchPin and hold low for as long as you are transmitting + digitalWrite(latchPin, LOW); + shiftOut(dataPin, clockPin, LSBFIRST, j); + //return the latch pin high to signal chip that it + //no longer needs to listen for information + digitalWrite(latchPin, HIGH); + delay(1000); + } + } + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/sin.rst b/source/lang/sin.rst new file mode 100644 index 0000000..398b8f3 --- /dev/null +++ b/source/lang/sin.rst @@ -0,0 +1,32 @@ +.. _lang-sin: + +sin() +===== + +Calculates the `sine `_ of an +angle. + +Library Documentation +--------------------- + +.. doxygenfunction:: sin + +Arduino Compatibility +--------------------- + +The Maple version of ``sin()`` is compatible with Arduino. + +Note that the Maple implementation comes from `newlib +`_\ , while Arduino's is that of +`avr-libc `_\ . + +See Also +-------- + +- :ref:`cos ` +- :ref:`tan ` +- :ref:`float ` +- :ref:`double ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/sizeof.rst b/source/lang/sizeof.rst new file mode 100644 index 0000000..409a6d7 --- /dev/null +++ b/source/lang/sizeof.rst @@ -0,0 +1,64 @@ +.. highlight:: cpp + +.. _lang-sizeof: + +sizeof() +======== + +The ``sizeof`` operator on the Maple returns the number of bytes +needed to store a value of a given type\ [#fcharsize]_. This can be +an ordinary numeric type, like ``int``. It can be something more +complicated, like a ``struct`` or ``union``. If the argument to +``sizeof`` is an array, it returns the total number of bytes occupied +by the array. + +The general syntax looks like this:: + + sizeof(type) + sizeof(var) + +Example +------- + +The ``sizeof`` operator is useful for dealing with arrays (such as +strings) where it is convenient to be able to change the size of the +array without breaking other parts of the program. + +This program prints out a text string one character at a time. Try +changing the text phrase:: + + char myStr[] = "this is a test"; + int i; + + void setup() { + Serial.begin(9600); + } + + void loop() { + for (i = 0; i < sizeof(myStr) - 1; i++) { + Serial.print(i, DEC); + Serial.print(" = "); + Serial.println(myStr[i], BYTE); + } + } + + +Note that ``sizeof`` returns the total number of bytes. So for larger +variable types such as ``int``, the :ref:`for loop ` +would look something like this:: + + for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { + // do something with myInts[i] + } + +.. rubric:: Footnotes + +.. [#fcharsize] Technically (and pedantically) speaking, ``sizeof`` + returns a multiple of the number of bits a ``char`` occupies in + memory. However, on the Maple (this goes for most C++ + implementations), a ``char`` occupies 8 bits = 1 byte. All the C++ + standard guarantees, however, is that a ``char`` occupies at + *least* 8 bits. + +.. include:: cc-attribution.txt + diff --git a/source/lang/sq.rst b/source/lang/sq.rst new file mode 100644 index 0000000..a14817f --- /dev/null +++ b/source/lang/sq.rst @@ -0,0 +1,42 @@ +.. highlight:: cpp + +.. _lang-sq: + +sq(a) +===== + +Description +----------- + +(Macro) computes the square of a number. + +Parameters +---------- + +**a**: the number. + +Returns +------- + +**a** squared (**a** × **a**). + +Warning +------- + +Because of the way ``sq()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + b = sq(a++); // avoid this - yields incorrect results + + b = sq(a); // use this instead - + a++; // keep other operations outside sq() + + +Arduino Compatibility +--------------------- + +Maple's implementation of ``sq()`` is compatible with Arduino. + + +.. include:: cc-attribution.txt diff --git a/source/lang/sqrt.rst b/source/lang/sqrt.rst new file mode 100644 index 0000000..956a754 --- /dev/null +++ b/source/lang/sqrt.rst @@ -0,0 +1,25 @@ +.. _lang-sqrt: + +sqrt() +====== + +Calculates the square root of a number. + +Library Documentation +--------------------- + +.. doxygenfunction:: sqrt + +Arduino Compatibility +--------------------- + +The Maple versino of ``sqrt()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`pow ` +- :ref:`sq ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/static.rst b/source/lang/static.rst new file mode 100644 index 0000000..4646db1 --- /dev/null +++ b/source/lang/static.rst @@ -0,0 +1,57 @@ +.. highlight:: cpp + +.. _lang-static: + +Static +====== + +The ``static`` keyword can be used to create variables that are +visible to only one function. However, unlike local variables that get +created and destroyed every time a function is called, ``static`` +variables persist beyond the function call, preserving their data +between function calls. + +Variables declared as ``static`` will only be created and initialized +the first time a function is called. + +.. note:: This is only one use of the ``static`` keyword in C++. It + has some other important uses that are not documented here; consult + a reliable C++ reference for details. + +Example +------- + +One use case for ``static`` variables is implementing counters that +last longer than the functions which need them, but shouldn't be +shared to other functions. Here's an example:: + + void setup() { + SerialUSB.begin(); + } + + void loop() { + int reading; + if (timeToReadSensors()) { + reading = readSensors(); + } + // do something with reading + } + + int readSensors() { + static int numSensorReadings = 0; + numSensorReadings++; + if (numSensorReadings % 100 == 0) { + SerialUSB.print("just got to another 100 sensor readings"); + } + return analogRead(...); + } + +In this example, the static variable ``numSensorReadings`` is +initialized to zero the first time ``readSensors()`` is called, and +then incremented, so it starts out at one. Subsequent calls to +``readSensors()`` won't reset ``numSensorReadings`` to zero, because +it was declared ``static``. Thus, ``numSensorReadings`` is a count of +the number of times that ``readSensors()`` has been called. + + +.. include:: cc-attribution.txt diff --git a/source/lang/string.rst b/source/lang/string.rst new file mode 100644 index 0000000..92c3f69 --- /dev/null +++ b/source/lang/string.rst @@ -0,0 +1,131 @@ +.. highlight:: cpp + +.. _lang-string: + +Strings +======= + +Description +----------- + +Text strings can be represented in two ways. You can + +1. Use the :ref:`String ` data type, which is +part of the core as of version 0.0.9, or + +2. You can make a string out of an array of type :ref:`char +` and null-terminate it. + +This page describes the second method. + +Examples +-------- + +All of the following are valid declarations for strings:: + + char str1[15]; + char str2[6] = {'m', 'a', 'p', 'l', 'e'}; + char str3[6] = {'m', 'a', 'p', 'l', 'e', '\0'}; + char str4[ ] = "maple"; + char str5[6] = "maple"; + char str6[15] = "maple"; + +As you can see, there are several methods available for declaring and +initializing strings: + +- Declare an array of ``char`` without initializing it, as with ``str1``. + +- Declare an array of ``char`` (with one extra ``char``) and the + compiler will add the required null character, as with ``str2``. + +- Explicitly add the null character (``'\0'``), as with ``str3``. + +- Initialize with a string constant in quotation marks (``"..."``); + the compiler will size the array to fit the string constant and a + terminating null character (``str4``). + +- Initialize the array with an explicit size and string constant, + (``str5``). + +- Initialize the array, leaving extra space for a larger string + (``str6``). + +Null Termination +---------------- + +Generally, strings are terminated with a null character (`ASCII +`_ code 0). This allows functions +(like ``SerialUSB.print()``) to tell where the end of a string is. +Otherwise, they would continue reading subsequent bytes of memory that +aren't actually part of the string. + +This means that your string needs to have space for one more character +than the text you want it to contain. That is why ``str2`` and +``str5`` need to be six characters, even though "maple" is only five +-- the last position is automatically filled with a NULL +character. ``str4`` will be automatically sized to six characters, one +for the extra null. In the case of ``str3``, we've explicitly included +the null character (written ``'\0'``) ourselves. + +Note that it's possible to have a string without a final null +character (e.g. if you had specified the length of ``str2`` as five +instead of six). This will break most functions that use strings, so +you shouldn't do it intentionally. If you notice something behaving +strangely (operating on characters not in the string), however, this +could be the problem. + +Single quotes or double quotes? +------------------------------- + +Strings are always defined inside double quotes (``"Abc"``) and +characters are always defined inside single quotes (``'A'``). + +Wrapping long strings +--------------------- + +You can wrap long strings like this:: + + char myString[] = "This is the first line" + " this is the second line" + " etcetera"; + +Arrays of Strings +----------------- + +It is often convenient, when working with large amounts of text, +such as a project with an LCD display, to setup an array of +strings. Because strings themselves are arrays, this is in actually +an example of a two-dimensional array. + +In the code below, the asterisk after the datatype char ``char *`` +indicates that this is an array of "pointers". All array names are +actually pointers, so this is required to make an array of arrays. +Pointers are one of the more esoteric parts of C for beginners to +understand, but it isn't necessary to understand pointers in detail to +use them effectively here:: + + char* myStrings[] = {"This is string 1", "This is string 2", + "This is string 3", "This is string 4", + "This is string 5", "This is string 6"}; + + void setup() { + SerialUSB.begin(); + } + + void loop() { + for (int i = 0; i < 6; i++) { + SerialUSB.println(myStrings[i]); + delay(500); + } + } + + +See Also +-------- + +- :ref:`array ` +- :ref:`__attribute__ ` +- :ref:`Variables ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/stringclass.rst b/source/lang/stringclass.rst new file mode 100644 index 0000000..5e53f08 --- /dev/null +++ b/source/lang/stringclass.rst @@ -0,0 +1,9 @@ +.. _lang-stringclass: + +String Class +============ + +Stub. + + +.. include:: cc-attribution.txt diff --git a/source/lang/stringobject.rst b/source/lang/stringobject.rst new file mode 100644 index 0000000..d7f287c --- /dev/null +++ b/source/lang/stringobject.rst @@ -0,0 +1,91 @@ +.. _lang-stringobject: + +String +====== + +Description +----------- + +The String class, part of the core as of version 0019, allows you +to use and manipulate strings of text in more complex ways than +`character arrays `_ do. You +can concatenate Strings, append to them, search for and replace +substrings, and more. It takes more memory than a simple character +array, but it is also more useful. + + + +For reference, character arrays are referred to as strings with a +small s, and instances of the String class are referred to as +Strings with a capital S. Note that constant strings, specified in +"double quotes" are treated as char arrays, not instances of the +String class. + + + +Functions +--------- + + +- `String `_\ () +- `charAt `_\ () +- `compareTo `_\ () +- `concat `_\ () +- `endsWith `_\ () +- `equals `_\ () +- `equalsIgnoreCase `_\ () +- `getBytes `_\ () +- `indexOf `_\ () +- `lastIndexOf `_\ () +- `length `_\ () +- `replace `_\ () +- `setCharAt `_\ () +- `startsWith `_\ () +- `substring `_\ () +- `toCharArray `_\ () +- `toLowerCase `_\ () +- `toUpperCase `_\ () +- `trim `_\ () + + + +Operators +--------- + + +- `[] (element access) `_ +- `+ (concatenation) `_ +- `== (comparison) `_ + + + +Examples +-------- + + +- `StringConstructors `_ +- `StringAdditionOperator `_ +- `StringIndexOf `_ +- `StringAppendOperator `_ +- `StringLengthTrim `_ +- `StringCaseChanges `_ +- `StringReplace `_ +- `StringCharacters `_ +- `StringStartsWithEndsWith `_ +- `StringComparisonOperators `_ +- `StringSubstring `_ + + + +See Also +-------- + + +- `string `_: character + arrays +- `Variable Declaration `_ + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/switchcase.rst b/source/lang/switchcase.rst new file mode 100644 index 0000000..46c47d8 --- /dev/null +++ b/source/lang/switchcase.rst @@ -0,0 +1,117 @@ +.. highlight:: cpp + +.. _lang-switchcase: + +switch / case statements +======================== + +Like :ref:`if/else ` blocks, A ``switch`` statement +controls program flow by allowing you to specify different code that +should be executed under various cases. + +The general syntax looks like this:: + + switch (var) { + case val1: + // statements + break; + case val2: + // statements + break; + ... + default: + // statements + } + +Where ``var`` is a variable whose value to investigate, and the +``val1``, ``val2`` after each ``case`` are constant values that +``var`` might be. + + +Description +----------- + +A ``switch`` statement compares the value of a variable to the values +specified in ``case`` statements. When a ``case`` statement is found +whose value matches that of the variable, the code in that case +statement is run. + +Here's a more concrete example:: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + afterTheSwitch(); + +In the above example, if ``var == 1``, then the code beginning on the +line after ``case 1`` gets executed. That is, if ``var`` is one, +``doThing1()`` gets called first, and then the ``break`` statement is +executed. + +The ``break`` keyword exits the ``switch`` statement, and is typically +used at the end of each ``case``. Since there is a ``break`` at the +end of ``case 1``, the ``switch`` statement exits, and the next line +to be run is the one which calls ``afterTheSwitch()``. + +Without a ``break``, the ``switch`` statement will continue executing +the following ``case`` expressions ("falling-through") until a +``break`` (or the end of the switch statement) is reached. Let's +pretend the ``switch`` looked like this instead:: + + switch (var) { + case 1: + doThing1(); + // no break statement anymore + case 2: + doThing2(); + break; + } + afterTheSwitch(); + +Now, if ``var`` is one, ``doThing1()`` gets executed like before. +However, without a ``break``, the code would continue to be executed +line-by-line, so ``doThing2()`` would be called next. At this point, +a ``break`` has been reached, so the program continues by calling +``afterTheSwitch()``. This is usually not what you want, which is why +each ``case`` usually has a ``break`` at the end. + +Writing "``default:``" instead of a ``case`` statement allows you to +specify what to do if none of the ``case`` statements matches. Having +a ``default`` is optional (you can leave it out), but if you have one, +it must appear after all of the ``case`` statements. Let's add a +``default`` to the ``switch`` we've been discussing:: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + default: + doSomethingElse(); + } + afterTheSwitch(); + +If ``var`` is one, then ``doThing1()`` gets called. If ``var`` is +two, ``doThing2()`` gets called. If ``var`` is anything else, +``doSomethingElse()`` gets called. As stated above, a ``default`` is +optional. If you're missing one and none of the ``case`` statements +match, the ``switch`` does nothing at all, as if it weren't there. + +``switch`` statements are often used with an ``enum`` value as the +variable to compare. In this case, you can write down all of the +values the ``enum`` takes as ``case`` statements, and be sure you've +covered all the possibilities. + +See also: +--------- + +- :ref:`if...else ` + +.. include:: cc-attribution.txt diff --git a/source/lang/tan.rst b/source/lang/tan.rst new file mode 100644 index 0000000..4bbe0db --- /dev/null +++ b/source/lang/tan.rst @@ -0,0 +1,31 @@ +.. _lang-tan: + +tan() +===== + +Calculates the tangent of an angle. + +Library Documentation +--------------------- + +.. doxygenfunction:: tan + +Arduino Compatibility +--------------------- + +The Maple version of ``tan()`` is compatible with Arduino. + +Note that the Maple implementation comes from `newlib +`_\ , while Arduino's is that of +`avr-libc `_\ . + +See Also +-------- + + +- :ref:`sin ` +- :ref:`cos ` +- :ref:`float ` +- :ref:`double ` + +.. include:: cc-attribution.txt diff --git a/source/lang/tone.rst b/source/lang/tone.rst new file mode 100644 index 0000000..96f0a7c --- /dev/null +++ b/source/lang/tone.rst @@ -0,0 +1,81 @@ +.. _lang-tone: + +tone() +====== + +Description +----------- + +Generates a square wave of the specified frequency (and 50% duty +cycle) on a pin. A duration can be specified, otherwise the wave +continues until a call to +`noTone `_\ (). The pin can be +connected to a piezo buzzer or other speaker to play tones. + + + +Only one tone can be generated at a time. If a tone is already +playing on a different pin, the call to tone() will have no effect. +If the tone is playing on the same pin, the call will set its +frequency. + + + +Use of the tone() function will interfere with PWM output on pins 3 +and 11 (on boards other than the Mega). + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +tone(pin, frequency) +tone(pin, frequency, duration) + + + +Parameters +---------- + +pin: the pin on which to generate the tone + + + +frequency: the frequency of the tone in hertz + + + +duration: the duration of the tone in milliseconds (optional) + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `noTone `_\ () +- `analogWrite `_\ () +- `Tutorial:Tone `_ +- `Tutorial:Pitch follower `_ +- `Tutorial:Simple Keyboard `_ +- `Tutorial: multiple tones `_ + + +- `Tutorial: PWM `_ + + + +.. include:: cc-attribution.txt diff --git a/source/lang/types.rst b/source/lang/types.rst new file mode 100644 index 0000000..d095da1 --- /dev/null +++ b/source/lang/types.rst @@ -0,0 +1,7 @@ +.. _lang-types: + +Built-in types +============== + +Stub. (explain all built-in integral and floating-point types, +including ``uint8`` style ones). diff --git a/source/lang/unsignedchar.rst b/source/lang/unsignedchar.rst new file mode 100644 index 0000000..c49690d --- /dev/null +++ b/source/lang/unsignedchar.rst @@ -0,0 +1,36 @@ +.. highlight:: cpp + +.. _lang-unsignedchar: + +unsigned char +============= + +Description +----------- + +An unsigned version of the :ref:`char ` data type. An +``unsigned char`` occupies 1 byte of memory; it stores an integer from +0 to 255. + +Like an :ref:`unsigned int `, an ``unsigned char`` +won't store negative numbers; it is also subject to the same +:ref:`overflow issues ` as any integral data type. + +Example +------- + +:: + + unsigned char c = 240; + +See Also +-------- + + +- :ref:`byte ` +- :ref:`int ` +- :ref:`array ` +- :ref:`SerialUSB.println() ` +- :ref:`Serial.println() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/unsignedint.rst b/source/lang/unsignedint.rst new file mode 100644 index 0000000..aa5cc1b --- /dev/null +++ b/source/lang/unsignedint.rst @@ -0,0 +1,58 @@ +.. highlight:: cpp + +.. _lang-unsignedint: + +unsigned int +============ + +Description +----------- + +An ``unsigned int`` (unsigned integer) is the same as an :ref:`int +` in that it stores a 4 byte integer value. However, +Instead of storing both negative and positive numbers, an ``unsigned +int`` can only store nonnegative values, yielding a range of 0 to +4,294,967,295 (the positive value is 2^32 - 1). + +The difference between an ``unsigned int`` and a (signed) ``int`` lies +in the way the highest bit, sometimes referred to as the "sign" bit, +is interpreted. In the case of the Maple ``int`` type (which is +signed), if the high bit is a "1", the number is interpreted as a +negative number, using a technique known as `two's complement math +`_. The +bits in an an ``unsigned int`` are interpreted according to the usual +rules for converting `binary to decimal +`_. + +An ``unsigned int`` is subject to the same :ref:`overflow issues +` as a regular ``int``; the only difference is +that an ``unsigned int`` will "underflow" at 0, and "overflow" at +4,294,967,295. Here is some example code which illustrates this:: + + unsigned int x; + x = 0; + x--; // x now contains 4,294,967,295; rolled over "left to right" + x++; // x now contains 0; rolled over "right to left" + +Here is an example of declaring an ``unsigned int`` variable named +``ledPin``, then giving it value 13:: + + unsigned int ledPin = 13; + +The general syntax for declaring an ``unsigned int`` variable named +``var``, then giving it value ``val``, looks like:: + + unsigned int var = val; + +See Also +-------- + +- :ref:`int ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`long ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/unsignedlong.rst b/source/lang/unsignedlong.rst new file mode 100644 index 0000000..2ca49f8 --- /dev/null +++ b/source/lang/unsignedlong.rst @@ -0,0 +1,44 @@ +.. highlight:: cpp + +.. _lang-unsignedlong: + +unsigned long +============= + +Description +----------- + +An unsigned version of the :ref:`long ` data type. An +``unsigned long`` occupies 8 bytes of memory; it stores an integer +from 0 to 2^64-1, which is approximately 1.8×10^19 (18 quintillion, or +18 billion billion). + +Like an :ref:`unsigned int `, an ``unsigned long`` +won't store negative numbers; it is also subject to the same +:ref:`overflow issues ` as any integral data type. + +Here is an example of declaring an ``unsigned long`` variable named +``c``, then giving it value 299,792,458,000,000,000 (see :ref:`integer +constants ` for an explanation of the "L" at the +end of the number):: + + // Speed of light in nanometers per second (approximate). + unsigned long c = 299792458000000000L; + +The general syntax for declaring an ``unsigned long`` variable named +``var``, then giving it value ``val``, looks like:: + + unsigned long var = val; + +See Also +-------- + +- :ref:`long ` +- :ref:`int ` +- :ref:`unsigned ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/variables.rst b/source/lang/variables.rst new file mode 100644 index 0000000..05a4f96 --- /dev/null +++ b/source/lang/variables.rst @@ -0,0 +1,170 @@ +.. highlight:: cpp + +.. _lang-variables: + +Variables +========= + +A variable is a way of naming and storing a value for later use by +the program, such as data from a sensor or an intermediate value +used in a calculation. + +.. contents:: Contents + :local: + +.. _lang-variables-declaring: + +Declaring Variables +------------------- + +Before they are used, all variables have to be *declared*. Declaring a +variable means defining its type, giving it a name, and (optionally) +giving it an initial value (this is often referred to as +*initializing* the variable). Variables do not have to be initialized +(given a value) when they are declared, but it is good style to give +them an initial value whenever possible. + +Here is an example of declaring a variable named ``inputVariable1`` +with type :ref:`int ` (the ``int`` type is used to store +integers, like -2, -1, 0, 1, etc.):: + + int inputVariable1; + +In the above declaration, we did not give the variable an initial +value. Here is another example, where we declare an ``int`` variable +named ``inputVariable2``, with an initial value of ``0``:: + + int inputVariable2 = 0; + +The Maple environment comes ready to use with many useful types of +variables. See the :ref:`built-in types ` page for more +information. + +Here are a few examples of declaring variables of different types:: + + int lightSensVal; + char currentLetter; + unsigned long speedOfLight = 186000UL; + char errorMessage = {"choose another option"}; // see string + +Naming Variables +---------------- + +The rules for naming a variable are simple. Names for variables can +contain letters, numbers, and underscores (the underscore is the +:kbd:`_` character), and cannot begin with a number. So +``temperature_reading``, ``tempReading``, ``tempReading1``, and +``tempReading2`` are all valid variable names, but ``4_temp_readings`` +is not, because it begins with a number. + +You cannot choose a name for a variable that is one of the C++ +:ref:`keywords `. + +Variable names are case-sensitive, so "tempreading" and "tempReading" +are different variables. However, it is very bad style to write code +that chooses variables which are the same up to case. + +You should give your variables descriptive names, so as to make your +code more readable. Variable names like ``tiltSensor`` or +``pushButton`` help you (and anyone else reading your code) understand +what the variable represents. Variable names like ``var`` or +``value``, on the other hand, do little to make your code readable. + +.. _lang-variables-scope: + +Variable Scope +-------------- + +An important choice that programmers face is where (in the program +text) to declare variables. The specific place that variables are +declared influences how various functions in a program will "see" the +variable. This is called variable *scope*. See the :ref:`scope +reference ` for more information. + +.. _lang-variables-initializing: + +Initializing Variables +---------------------- + +Variables may be *initialized* (assigned a starting value) when they +are declared or not. It is always good programming practice however to +double check that a variable has valid data in it before it is used. +Using a variable before you give it a value is a common source of +bugs. + +.. _lang-variables-rollover: + +Variable Rollover +----------------- + +Every (numeric) type has a valid *range*. The range of a type is the +smallest and largest value that a variable of that type can store. +For example, the :ref:`int ` type has a range of +-2,147,483,648 to 2,147,483,647 [#frange]_. + +When variables are made to exceed their range's maximum value, they +"roll over" back to their minimum value. Note that this happens in +both directions. It's like in the game *Pac-Man* -- when Pac-Man goes +past the right edge of the screen, he reappears on the left, and when +he goes past the left side of the screen, he reappears on the right:: + + int x; + x = -2,147,483,648; + x = x - 1; // x now contains -2,147,483,647; rolled over "left to right" + + x = 2,147,483,647; + x = x + 1; // x now contains -2,147,483,648; rolled over "right to left" + +Each numeric type's reference page includes its range. See the +:ref:`built-in types ` reference for links to each type's +reference page. + +Using Variables +--------------- + +Once variables have been declared, they are given values using the +:ref:`assignment operator `, which is a single equals +sign, ``=``. The assignment operator tells the program to store the +value on the right side of the equals sign into the variable on the +left side:: + + inputVariable1 = 7; // sets variable named inputVariable1 to 7 + inputVariable2 = analogRead(2); // sets variable named inputVariable2 to + // the (digitized) input voltage read from + // analog pin #2 + +Once a variable has been set (assigned a value), you can test its +value to see if it meets certain conditions, or you can use its value +directly. For instance, the following code tests whether the +inputVariable2 is less than 100, then sets a delay based on +inputVariable2 (which, at that point, is at least 100):: + + if (inputVariable2 < 100) { + inputVariable2 = 100; + } + + delay(inputVariable2); + +See Also +-------- + +- :ref:`lang-scope` +- :ref:`lang-types` + +.. rubric:: Footnotes + +.. [#frange] This range might seem a little weird at first. The + reasons for this range of values have to do with the fact that an + ``int`` occupies 32 bits of memory, and the facts :: + + 2^31 = -2,147,483,648 + 2^31 - 1 = 2,147,483,647 + + + Why 2^31 instead of 2^32? Well, that has to do with `how ints are + (usually) stored + `_ on computers. + + +.. include:: cc-attribution.txt + diff --git a/source/lang/void.rst b/source/lang/void.rst new file mode 100644 index 0000000..bc7a3dc --- /dev/null +++ b/source/lang/void.rst @@ -0,0 +1,40 @@ +.. _lang-void: + +void +==== + +The void keyword is used only in function declarations. It +indicates that the function is expected to return no information to +the function from which it was called. + + + +Example: +-------- + +:: + + // actions are performed in the functions "setup" and "loop" + // but no information is reported to the larger program + + void setup() + { + // ... + } + + void loop() + { + // ... + } + + + + +See also +-------- + +`function declaration `_ + + + +.. include:: cc-attribution.txt diff --git a/source/lang/volatile.rst b/source/lang/volatile.rst new file mode 100644 index 0000000..a0ef671 --- /dev/null +++ b/source/lang/volatile.rst @@ -0,0 +1,73 @@ +.. _lang-volatile: + +volatile keyword +================ + +volatile is a keyword known as a variable *qualifier*, it is +usually used before the datatype of a variable, to modify the way +in which the compiler and subsequent program treats the variable. + + + +Declaring a variable volatile is a directive to the compiler. The +compiler is software which translates your C/C++ code into the +machine code, which are the real instructions for the Atmega chip +in the Arduino. + + + +Specifically, it directs the compiler to load the variable from RAM +and not from a storage register, which is a temporary memory +location where program variables are stored and manipulated. Under +certain conditions, the value for a variable stored in registers +can be inaccurate. + + + +A variable should be declared volatile whenever its value can be +changed by something beyond the control of the code section in +which it appears, such as a concurrently executing thread. In the +Arduino, the only place that this is likely to occur is in sections +of code associated with interrupts, called an interrupt service +routine. + + + +Example +------- + +:: + + // toggles LED when interrupt pin changes state + + int pin = 13; + volatile int state = LOW; + + void setup() + { + pinMode(pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() + { + digitalWrite(pin, state); + } + + void blink() + { + state = !state; + } + + + +See also +-------- + + +- `AttachInterrupt `_ + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/while.rst b/source/lang/while.rst new file mode 100644 index 0000000..be1ea14 --- /dev/null +++ b/source/lang/while.rst @@ -0,0 +1,49 @@ +.. _lang-while: + +while Loops +=========== + +Description +----------- + +**while** loops will loop continuously, and infinitely, until the +expression inside the parenthesis, () becomes false. Something must +change the tested variable, or the **while** loop will never exit. +This could be in your code, such as an incremented variable, or an +external condition, such as testing a sensor. + + + +Syntax +------ + +:: + + while(expression){ + // statement(s) + } + + + +Parameters +---------- + +expression - a (boolean) C statement that evaluates to true or +false + + + +Example +------- + +:: + + var = 0; + while(var < 200){ + // do something repetitive 200 times + var++; + } + + + +.. include:: cc-attribution.txt diff --git a/source/language-index.rst b/source/language-index.rst new file mode 100644 index 0000000..90b3d79 --- /dev/null +++ b/source/language-index.rst @@ -0,0 +1,131 @@ +.. _language-index: + +Language Reference Index +======================== + +This is the index of the :ref:`language reference ` +documentation. + +Not converted Arduino docs: + +.. toctree:: + :maxdepth: 1 + + lang/pwmwrite + lang/types + lang/serialusb + +Finished: + +.. toctree:: + :maxdepth: 1 + + lang/abs + lang/analogread + lang/pinmode + lang/arithmetic + lang/array + lang/assignment + lang/attachinterrupt + lang/bit + lang/bitclear + lang/bitread + lang/bitset + lang/bitshift + lang/analogwrite + lang/bitwisemath + lang/bitwisecompound + lang/bitwrite + lang/boolean + lang/booleanvariables + lang/braces + lang/break + lang/byte + lang/bytecast + lang/char + lang/charcast + lang/comments + lang/const + lang/constrain + lang/continue + lang/cos + lang/define + lang/delay + lang/delaymicroseconds + lang/detachinterrupt + lang/digitalread + lang/double + lang/doublecast + lang/dowhile + lang/else + lang/float + lang/floatcast + lang/for + lang/goto + lang/highbyte + lang/if + lang/comparison + lang/include + lang/increment + lang/arithmeticcompound + lang/int + lang/intcast + lang/long + lang/longcast + lang/loop + lang/max + lang/min + lang/modulo + lang/pointer + lang/pow + lang/return + lang/scope + lang/semicolon + lang/sin + lang/sizeof + lang/sqrt + lang/sq + lang/static + lang/string + lang/switchcase + lang/tan + lang/unsignedchar + lang/unsignedint + lang/unsignedlong + lang/variables + +Unfinished; straightforward to convert: + +.. toctree:: + :maxdepth: 1 + + lang/void + lang/volatile + lang/while + lang/keywords + lang/enum + +Unfinished, requires libmaple/Arduino knowledge: + +.. toctree:: + :maxdepth: 1 + + lang/constants + lang/digitalwrite + lang/notone + lang/serial + lang/interrupts + lang/analogwrite + lang/nointerrupts + lang/pulsein + lang/stringobject + lang/tone + lang/random + lang/randomseed + lang/setup + lang/map + lang/shiftout + lang/micros + lang/millis + lang/lowbyte + lang/stringclass diff --git a/source/language.rst b/source/language.rst index bbdbf90..0a79fb0 100644 --- a/source/language.rst +++ b/source/language.rst @@ -42,174 +42,174 @@ Unique Maple Additions #define DEBUG_LEVEL DEBUG_NONE - before including either wirish or libmaple. In this case, all + before including either wirish.h or libmaple.h. In this case, all assertions will pass without any lost clock cycles. Note that this will **not work in the IDE**; even with this definition, assertions will still be enabled. -.. _language-arduino-docs: +.. _language-lang-docs: Maple Language Reference ------------------------ -+-------------------------------------------------+----------------------------------------------+---------------------------------------------------+ -| Structure | Variables | Functions | -| | | | -+=================================================+==============================================+===================================================+ -|* :ref:`setup() ` |**Constants** |**Digital I/O** | -| | | | -|* :ref:`loop() ` |* :ref:`HIGH ` | |* :ref:`pinMode() ` | -| | :ref:`LOW ` | | -| | |* :ref:`digitalWrite() ` | -|**Control Structures** |* :ref:`INPUT ` | | | -| | :ref:`OUTPUT ` |* :ref:`digitalRead() ` | -|* :ref:`if ` | | | -| |* :ref:`true ` | | | -|* :ref:`if...else ` | :ref:`false ` |**Analog I/O** | -| | | | -|* :ref:`for ` |* :ref:`integer constants |* :ref:`analogRead() ` | -| | ` | | -|* :ref:`switch/case ` | |* :ref:`pwmWrite() ` | -| |* :ref:`floating point constants | (:ref:`analogWrite() ` is | -|* :ref:`while ` | ` | also available, though its use is discouraged) | -| | | | -|* :ref:`do...while ` | | | -| |**Data Types** |**Advanced I/O** | -|* :ref:`break ` | | | -| | The size of each datatype, in bytes, is |* tone(): TODO | -|* :ref:`continue ` | given in parentheses where appropriate. | | -| | |* noTone(): TODO | -|* :ref:`return ` | *Note*: The ``word`` type is (deliberately) | | -| | :ref:`not supported `. |* shiftOut(): TODO | -|* :ref:`goto ` | | | -| |* :ref:`void ` |* pulseIn(): TODO | -| | | | -|**Further syntax** |* :ref:`boolean ` (1 byte) | | -| | |**Time** | -|* :ref:`; ` (semicolon) |* :ref:`char ` (1 byte) | | -| | |* :ref:`millis() ` | -|* :ref:`{} ` (curly braces) |* :ref:`unsigned char | | -| | ` (1 byte) |* :ref:`micros() ` | -|* :ref:`// ` | | | -| (single line comment) |* :ref:`byte ` (1 byte) |* :ref:`delay() ` | -| | | | -|* :ref:`/\* \*/ |* :ref:`int ` (4 bytes) |* :ref:`delayMicroseconds() | -| ` | | ` | -| (multi-line comment) |* :ref:`unsigned int ` | | -| | (4 bytes) | | -|* :ref:`#define ` | |**Math** | -| |* :ref:`long ` (8 bytes) | | -|* :ref:`#include ` | |* :ref:`min() ` | -| |* :ref:`unsigned long ` | | -| | (8 bytes) |* :ref:`max() ` | -|**Arithmetic Operators** | | | -| |* :ref:`float ` (4 bytes) |* :ref:`abs() ` | -|* :ref:`= ` | | | -| (assignment operator) |* :ref:`double ` (8 bytes) |* :ref:`constrain() ` | -| | | | -|* :ref:`+ ` (addition) |* :ref:`string ` |* :ref:`map() ` | -| | | | -|* :ref:`- ` |* :ref:`array ` |* :ref:`pow() ` | -| (subtraction) | | | -| |* Also provided: ``int8``, ``int16``, |* :ref:`sqrt() ` | -|* :ref:`* ` | ``int32``, ``int64``, and their unsigned | | -| (multiplication) | counterparts ``uint8``, ``uint16``, | | -| | ``uint32``, ``uint64``. |**Trigonometry** | -|* :ref:`/ ` (division) | | | -| | |* :ref:`sin() ` | -|* :ref:`% ` (modulo) |**Conversion** | | -| | |* :ref:`cos() ` | -| |* :ref:`char() ` | | -|**Comparison Operators** | |* :ref:`tan() ` | -| |* :ref:`byte() ` | | -|* :ref:`== ` (equal to) | | | -| |* :ref:`int() ` |**Random Numbers** | -|* :ref:`\!= ` | | | -| (not equal to) |* :ref:`long() ` |* :ref:`randomSeed() ` | -| | | | -|* :ref:`< ` (less than) |* :ref:`float() ` |* :ref:`random() ` | -| | | | -|* :ref:`> ` |* :ref:`double() ` | | -| (greater than) | |**Bits and Bytes** | -| | | | -|* :ref:`<= ` |**Variable Scope & Qualifiers** |* :ref:`lowByte() ` | -| (less than or equal to) | | | -| |* :ref:`variables `, |* :ref:`highByte() ` is | -|* :ref:`>= ` | :ref:`scope ` | provided, though its use is discouraged. | -| (greater than or equal to) | | | -| |* :ref:`static ` |* :ref:`bitRead() ` | -| | | | -|**Boolean Operators** |* :ref:`volatile ` |* :ref:`bitWrite() ` | -| | | | -|* :ref:`&& ` (and) |* :ref:`const ` |* :ref:`bitSet() ` | -| | | | -|* :ref:`|| ` (or) | |* :ref:`bitClear() ` | -| |**Utilities** | | -|* :ref:`\! ` (not) | |* :ref:`bit() ` | -| |* :ref:`sizeof() ` | | -| | (``sizeof`` operator) | | -|**Pointer Access Operators** | |**External Interrupts** | -| | | | -|* :ref:`* dereference operator | |* :ref:`Reference Page ` | -| ` | | | -| | |* :ref:`attachInterrupt() | -|* :ref:`& reference operator | | ` | -| ` | | | -| | |* :ref:`detachInterrupt() | -| | | ` | -|**Bitwise Operators** | | | -| | | | -|* :ref:`& ` | |**Interrupts** | -| (bitwise and) | | | -| | |* interrupts(): TODO | -|* :ref:`| ` | | | -| (bitwise or) | |* noInterrupts(): TODO | -| | | | -|* :ref:`^ ` | | | -| (bitwise xor) | |**Communication** | -| | | | -|* :ref:`~ ` | |* :ref:`SerialUSB ` | -| (bitwise not) | | | -| | |* :ref:`Serial ` | -|* :ref:`\<\< ` | | | -| (shift left) | |**Looking for something else?** | -| | | | -|* :ref:`>> ` | | See the :ref:`libraries` page for interfacing with| -| (shift right) | | particular types of hardware. Try the list of | -| | | `community-contributed code` . Maple links | -| | | against `newlib` and allows the use of any of its | -|**Compound Operators** | | functions; see its documentation for more details.| -| | | | -|* :ref:`++ ` | | | -| (increment) | | | -| | | | -|* :ref:`- - ` | | | -| (decrement) | | | -| | | | -|* :ref:`+= ` | | | -| (compound add) | | | -| | | | -|* :ref:`-= | | | -| ` (compound | | | -| subtract) | | | -| | | | -|* :ref:`*= | | | -| ` (compound | | | -| multiply) | | | -| | | | -|* :ref:`/= | | | -| ` (compound | | | -| divide) | | | -| | | | -|* :ref:`&= | | | -| ` (compound | | | -| bitwise and) | | | -| | | | -|* :ref:`|= | | | -| ` (compound | | | -| bitwise or) | | | -| | | | -+-------------------------------------------------+----------------------------------------------+---------------------------------------------------+ ++--------------------------------------------+----------------------------------------------+---------------------------------------------------+ +| Structure | Variables | Functions | +| | | | ++============================================+==============================================+===================================================+ +|* :ref:`setup() ` |**Constants** |**Digital I/O** | +| | | | +|* :ref:`loop() ` |* :ref:`HIGH ` | |* :ref:`pinMode() ` | +| | :ref:`LOW ` | | +| | |* :ref:`digitalWrite() ` | +|**Control Structures** |* :ref:`INPUT ` | | | +| | :ref:`OUTPUT ` |* :ref:`digitalRead() ` | +|* :ref:`if ` | | | +| |* :ref:`true ` | | | +|* :ref:`if...else ` | :ref:`false ` |**Analog I/O** | +| | | | +|* :ref:`for ` |* :ref:`integer constants |* :ref:`analogRead() ` | +| | ` | | +|* :ref:`switch/case ` | |* :ref:`pwmWrite() ` | +| |* :ref:`floating point constants | (:ref:`analogWrite() ` is | +|* :ref:`while ` | ` | also available, though its use is discouraged) | +| | | | +|* :ref:`do...while ` | | | +| |**Data Types** |**Advanced I/O** | +|* :ref:`break ` | | | +| | The size of each datatype, in bytes, is |* tone(): TODO | +|* :ref:`continue ` | given in parentheses where appropriate. | | +| | |* noTone(): TODO | +|* :ref:`return ` | *Note*: The ``word`` type is (deliberately) | | +| | :ref:`not supported `. |* shiftOut(): TODO | +|* :ref:`goto ` | | | +| |* :ref:`void ` |* pulseIn(): TODO | +| | | | +|**Further syntax** |* :ref:`boolean ` (1 byte) | | +| | |**Time** | +|* :ref:`; (semicolon) ` |* :ref:`char ` (1 byte) | | +| | |* :ref:`millis() ` | +|* :ref:`{} (curly braces) ` |* :ref:`unsigned char | | +| | ` (1 byte) |* :ref:`micros() ` | +|* :ref:`// (single-line comment) | | | +| ` |* :ref:`byte ` (1 byte) |* :ref:`delay() ` | +| | | | +|* :ref:`/\* \*/ (multi-line comment) |* :ref:`int ` (4 bytes) |* :ref:`delayMicroseconds() | +| ` | | ` | +| |* :ref:`unsigned int ` | | +|* :ref:`#define ` | (4 bytes) | | +| | |**Math** | +|* :ref:`#include ` |* :ref:`long ` (8 bytes) | | +| | |* :ref:`min() ` | +| |* :ref:`unsigned long ` | | +|**Arithmetic Operators** | (8 bytes) |* :ref:`max() ` | +| | | | +|* :ref:`= ` |* :ref:`float ` (4 bytes) |* :ref:`abs() ` | +| (assignment operator) | | | +| |* :ref:`double ` (8 bytes) |* :ref:`constrain() ` | +|* :ref:`+ ` (addition) | | | +| |* :ref:`string ` |* :ref:`map() ` | +|* :ref:`- ` | | | +| (subtraction) |* :ref:`array ` |* :ref:`pow() ` | +| | | | +|* :ref:`* ` |* See also: :ref:`built-in types reference |* :ref:`sqrt() ` | +| (multiplication) | `. | | +| | | | +|* :ref:`/ ` (division) | |**Trigonometry** | +| |**Conversion** | | +|* :ref:`% ` (modulo) | |* :ref:`sin() ` | +| |* :ref:`char() ` | | +| | |* :ref:`cos() ` | +|**Comparison Operators** |* :ref:`byte() ` | | +| | |* :ref:`tan() ` | +|* :ref:`== ` (equal to) |* :ref:`int() ` | | +| | | | +|* :ref:`\!= ` |* :ref:`long() ` |**Random Numbers** | +| (not equal to) | | | +| |* :ref:`float() ` |* :ref:`randomSeed() ` | +|* :ref:`< ` (less than) | | | +| |* :ref:`double() ` |* :ref:`random() ` | +|* :ref:`> ` | | | +| (greater than) | | | +| |**Variable Scope & Qualifiers** |**Bits and Bytes** | +|* :ref:`<= ` | | | +| (less than or equal to) |* :ref:`variables `, |* :ref:`lowByte() ` | +| | :ref:`scope ` | | +|* :ref:`>= ` | |* :ref:`highByte() ` is | +| (greater than or equal to) |* :ref:`static ` | provided, though its use is discouraged. | +| | | | +| |* :ref:`volatile ` |* :ref:`bitRead() ` | +|**Boolean Operators** | | | +| |* :ref:`const ` |* :ref:`bitWrite() ` | +|* :ref:`&& ` (and) | | | +| | |* :ref:`bitSet() ` | +|* :ref:`|| ` (or) |**Utilities** | | +| | |* :ref:`bitClear() ` | +|* :ref:`\! ` (not) |* :ref:`sizeof() ` | | +| | (``sizeof`` operator) |* :ref:`bit() ` | +| | | | +|**Pointer Operators** | | | +| | |**External Interrupts** | +|* :ref:`* dereference operator | | | +| ` | |* :ref:`Reference Page ` | +| | | | +|* :ref:`& reference operator | |* :ref:`attachInterrupt() | +| ` | | ` | +| | | | +| | |* :ref:`detachInterrupt() | +|**Bitwise Operators** | | ` | +| | | | +|* :ref:`& ` | | | +| (bitwise and) | |**Interrupts** | +| | | | +|* :ref:`| ` | |* interrupts(): TODO | +| (bitwise or) | | | +| | |* noInterrupts(): TODO | +|* :ref:`^ ` | | | +| (bitwise xor) | | | +| | |**Communication** | +|* :ref:`~ ` | | | +| (bitwise not) | |* :ref:`SerialUSB ` | +| | | | +|* :ref:`\<\< ` | |* :ref:`Serial ` | +| (shift left) | | | +| | |**Looking for something else?** | +|* :ref:`>> ` | | | +| (shift right) | | See the :ref:`libraries` page for interfacing with| +| | | particular types of hardware. Maple links | +| | | against `newlib `_ | +|**Compound Operators** | | and allows the use of any of its functions; see | +| | | its documentation for more details. | +|* :ref:`++ ` | | | +| (increment) | | | +| | | | +|* :ref:`- - ` | | | +| (decrement) | | | +| | | | +|* :ref:`+= ` | | | +| (compound add) | | | +| | | | +|* :ref:`-= | | | +| ` (compound | | | +| subtract) | | | +| | | | +|* :ref:`*= | | | +| ` (compound | | | +| multiply) | | | +| | | | +|* :ref:`/= | | | +| ` (compound | | | +| divide) | | | +| | | | +|* :ref:`&= | | | +| ` (compound | | | +| bitwise and) | | | +| | | | +|* :ref:`|= | | | +| ` (compound | | | +| bitwise or) | | | +| | | | +| | | | ++--------------------------------------------+----------------------------------------------+---------------------------------------------------+ .. _language-missing-features: diff --git a/source/wirish.rst b/source/wirish.rst deleted file mode 100644 index e8e608e..0000000 --- a/source/wirish.rst +++ /dev/null @@ -1,10 +0,0 @@ - -[temporary] Wirish Functions -============================ - -.. toctree:: - :maxdepth: 2 - - wirish/pwmwrite - wirish/types - wirish/serialusb diff --git a/source/wirish/pwmwrite.rst b/source/wirish/pwmwrite.rst deleted file mode 100644 index 7667a72..0000000 --- a/source/wirish/pwmwrite.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. highlight:: cpp - -.. _wirish-pwmwrite: - -pwmWrite() -========== - -Writes a :ref:`PWM wave ` to a pin. You can use this to make an -LED get brighter or dimmer, control a servomotor, etc. After a call to -pwmWrite(), the pin will output a steady square wave with the given -duty cycle. You can change the duty cycle later by calling pwmWrite() -again with the same pin and a different duty. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: pwmWrite - -Example -------- - -Sets the output to the LED proportional to the value read from the -potentiometer (adapted for Maple from the Arduino `analogWrite() -reference `_):: - - - int ledPin = 13; // LED connected to pin 13 (Maple) - int analogPin = 3; // potentiometer connected to analog pin 3 - int val = 0; // variable to store the read value - - void setup() { - pinMode(ledPin, OUTPUT); // sets the LED pin as output - - pinMode(analogPin, PWM); // sets the potentiometer pin as PWM - // output - } - - void loop() { - val = analogRead(analogPin); // read the input pin - - analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, - // analogWrite values from 0 to 65535 - } - -See Also --------- - -- :ref:`Maple PWM tutorial ` diff --git a/source/wirish/serialusb.rst b/source/wirish/serialusb.rst deleted file mode 100644 index d0eac98..0000000 --- a/source/wirish/serialusb.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _wirish-serialusb: - -Serial over USB Communications -============================== - -Stub. diff --git a/source/wirish/types.rst b/source/wirish/types.rst deleted file mode 100644 index 0b78d01..0000000 --- a/source/wirish/types.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _wirish-types: - -Standard types -============== - -Stub. (uint8, uint64, etc.) -- cgit v1.2.3 From ee35f641687d0d3159c15eea5ad80d71efff4f82 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 29 Nov 2010 01:49:26 -0500 Subject: Finished converting the Arduino docs --- README | 83 ++++-- source/bootloader.rst | 7 + source/compatibility.rst | 35 ++- source/conf.py | 4 +- source/lang/abs.rst | 14 +- source/lang/analogwrite.rst | 2 +- source/lang/arithmetic.rst | 32 ++- source/lang/arithmeticcompound.rst | 46 ---- source/lang/assignment.rst | 4 +- source/lang/bit.rst | 4 - source/lang/bitclear.rst | 3 - source/lang/bitread.rst | 3 - source/lang/bitset.rst | 3 - source/lang/bitshift.rst | 8 +- source/lang/bitwisecompound.rst | 231 ---------------- source/lang/bitwisemath.rst | 22 +- source/lang/bitwrite.rst | 16 +- source/lang/boolean.rst | 2 +- source/lang/booleanvariables.rst | 5 +- source/lang/braces.rst | 109 -------- source/lang/break.rst | 4 +- source/lang/bytecast.rst | 3 - source/lang/char.rst | 7 +- source/lang/charcast.rst | 7 +- source/lang/comparison.rst | 4 +- source/lang/compoundarithmetic.rst | 44 ++++ source/lang/compoundbitwise.rst | 231 ++++++++++++++++ source/lang/const.rst | 4 +- source/lang/constants.rst | 410 +++++++++++++++-------------- source/lang/constrain.rst | 14 +- source/lang/continue.rst | 8 +- source/lang/curly-braces.rst | 109 ++++++++ source/lang/define.rst | 4 +- source/lang/digitalread.rst | 3 - source/lang/digitalwrite.rst | 116 +++----- source/lang/double.rst | 11 +- source/lang/doublecast.rst | 7 +- source/lang/dowhile.rst | 4 +- source/lang/else.rst | 54 ---- source/lang/enum.rst | 53 +++- source/lang/float.rst | 7 +- source/lang/floatcast.rst | 13 +- source/lang/for.rst | 16 +- source/lang/goto.rst | 4 +- source/lang/highbyte.rst | 16 +- source/lang/if.rst | 52 +++- source/lang/include.rst | 7 +- source/lang/increment.rst | 15 +- source/lang/int.rst | 9 +- source/lang/intcast.rst | 7 +- source/lang/interrupts.rst | 62 ----- source/lang/keywords.rst | 202 +++++++++++++- source/lang/long.rst | 9 +- source/lang/longcast.rst | 7 +- source/lang/lowbyte.rst | 26 +- source/lang/map.rst | 124 +++------ source/lang/max.rst | 12 +- source/lang/micros.rst | 65 ++--- source/lang/millis.rst | 70 ++--- source/lang/min.rst | 14 +- source/lang/modulo.rst | 13 +- source/lang/nointerrupts.rst | 59 ----- source/lang/notone.rst | 50 ---- source/lang/numeric-types.rst | 79 ++++++ source/lang/pinmode.rst | 43 +-- source/lang/pointer.rst | 21 +- source/lang/pow.rst | 12 +- source/lang/pulsein.rst | 82 ------ source/lang/pwmwrite.rst | 4 +- source/lang/random.rst | 90 +++---- source/lang/randomseed.rst | 69 ++--- source/lang/return.rst | 8 +- source/lang/scope.rst | 8 +- source/lang/semicolon.rst | 4 +- source/lang/serial.rst | 235 ++++++++++++++--- source/lang/serialusb.rst | 238 ++++++++++++++++- source/lang/setup.rst | 27 +- source/lang/shiftout.rst | 136 ---------- source/lang/sizeof.rst | 4 +- source/lang/sq.rst | 14 +- source/lang/static.rst | 4 +- source/lang/string.rst | 3 - source/lang/stringclass.rst | 9 - source/lang/stringobject.rst | 91 ------- source/lang/switchcase.rst | 23 +- source/lang/tone.rst | 81 ------ source/lang/types.rst | 7 - source/lang/unimplemented/interrupts.rst | 59 +++++ source/lang/unimplemented/nointerrupts.rst | 59 +++++ source/lang/unimplemented/notone.rst | 50 ++++ source/lang/unimplemented/pulsein.rst | 82 ++++++ source/lang/unimplemented/shiftout.rst | 136 ++++++++++ source/lang/unimplemented/stringclass.rst | 9 + source/lang/unimplemented/stringobject.rst | 89 +++++++ source/lang/unimplemented/tone.rst | 81 ++++++ source/lang/unsignedchar.rst | 7 +- source/lang/unsignedint.rst | 7 +- source/lang/unsignedlong.rst | 11 +- source/lang/variables.rst | 10 +- source/lang/void.rst | 33 +-- source/lang/volatile.rst | 76 +++--- source/lang/while.rst | 41 ++- source/language-index.rst | 127 +-------- source/language.rst | 204 +++++++------- source/libraries.rst | 4 +- source/spi.rst | 2 +- source/timers.rst | 25 +- source/troubleshooting.rst | 20 +- source/unix-toolchain.rst | 31 ++- source/usb.rst | 162 +----------- 110 files changed, 2692 insertions(+), 2514 deletions(-) delete mode 100644 source/lang/arithmeticcompound.rst delete mode 100644 source/lang/bitwisecompound.rst delete mode 100644 source/lang/braces.rst create mode 100644 source/lang/compoundarithmetic.rst create mode 100644 source/lang/compoundbitwise.rst create mode 100644 source/lang/curly-braces.rst delete mode 100644 source/lang/else.rst delete mode 100644 source/lang/interrupts.rst delete mode 100644 source/lang/nointerrupts.rst delete mode 100644 source/lang/notone.rst create mode 100644 source/lang/numeric-types.rst delete mode 100644 source/lang/pulsein.rst delete mode 100644 source/lang/shiftout.rst delete mode 100644 source/lang/stringclass.rst delete mode 100644 source/lang/stringobject.rst delete mode 100644 source/lang/tone.rst delete mode 100644 source/lang/types.rst create mode 100644 source/lang/unimplemented/interrupts.rst create mode 100644 source/lang/unimplemented/nointerrupts.rst create mode 100644 source/lang/unimplemented/notone.rst create mode 100644 source/lang/unimplemented/pulsein.rst create mode 100644 source/lang/unimplemented/shiftout.rst create mode 100644 source/lang/unimplemented/stringclass.rst create mode 100644 source/lang/unimplemented/stringobject.rst create mode 100644 source/lang/unimplemented/tone.rst diff --git a/README b/README index b467d2d..326d278 100644 --- a/README +++ b/README @@ -3,46 +3,81 @@ as a Doxygen configuration file; we turn Doxygen XML output into Sphinx documentation. You can generate HTML documentation using the Makefile if you have make, or using make.bat from Windows. -You need a recent-ish version of doxygen in your PATH: +Documentation Build Steps +------------------------- - http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc +1. You need a recent-ish version of Doxygen in your PATH: -For the Doxygen-to-Sphinx bridge, we rely on a project called Breathe, -by Michael Jones. + http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc -***** You must clone the LEAFLABS VERSION OF THE breathe repository ****** +2. Install breathe, which does Doxygen-to-Sphinx conversion: - ... and then set an environment variable BREATHE_HOME to be able to -build the documentation. Something like this on bash: + Read/write version (for LeafLabs developers): $ git clone git@github.com:leaflabs/breathe.git + + Read-only version (for non-LeafLabs developers): + + $ git clone git://github.com/leaflabs/breathe.git + + After that's done, set an environment variable BREATHE_HOME to + point to where you downloaded it. Something like this on bash: + $ export BREATHE_HOME=/path/to/breathe/repo/ -You can now build the HTML docs with (on Unix): + (You'll want to put this in your shell startup script). + +3. Install Sphinx. + + From source or .egg: + + http://pypi.python.org/pypi/Sphinx#downloads + + Via easy_install: $ sudo easy_install -U Sphinx + +4. Before the first time you run Sphinx (and any time the Doxygen + comments in the libmaple source code are changed), you'll need to + rebuild the Doxygen XML output: + + $ cd libmaple/docs/source + $ doxygen + +5. Finally, you can build the documentation: + $ make html -Which will produce Doxygen documentation in doxygen/xml, and HTML -documentation (this is what you want to look at) in build/html. + (Read the Makefile for more targets). -All of the documentation itself lives in source/. The directory -source/_static is for static content like style sheets; -source/_templates contains Sphinx templates (or, it would if we had -any). +Reading and Modifying the Documentation +--------------------------------------- -The docs are written in reStructuredText (reST); it's a Python thing -that they use to produce the docs at python.org (which are beautiful, -if you've never seen them). You can read more about Sphinx here: +The net effect of the above is to produce Doxygen XML output (ignore +this) in libmaple/docs/doxygen/xml, and HTML documentation (this is +what you want) in libmaple/docs/build/html. - http://sphinx.pocoo.org/tutorial.html +Just point your web browser at the file + + libmaple/docs/build/html/index.html -Specific information on documenting C and C++ is available here: +it corresponds to the Sphinx file - http://sphinx.pocoo.org/domains.html + libmaple/docs/source/index.rst + +All of the documentation itself lives in libmaple/docs/source/. The +directory source/_static/ is for static content (like style sheets); +source/_templates/ contains Sphinx templates (or, it would, if we had +any). + +The docs are written in Sphinx's version of reStructuredText (reST); +it's a Python thing that they use to produce the docs at +http://python.org. You can read more about Sphinx here: + + http://sphinx.pocoo.org/tutorial.html -You can view the reST source for any generated page of documentation -by clicking the "Show Source" link in the sidebar. +You can view the source for any generated page of documentation by +clicking the "Show Source" link in the sidebar. -The file source/conf.py is the Sphinx configuration file; you can go -read it for more information about our setup. +The file libmaple/docs/source/conf.py is the Sphinx configuration +file; you can go read it for more information about our setup. diff --git a/source/bootloader.rst b/source/bootloader.rst index 6cb9ece..1cfd17f 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -574,3 +574,10 @@ SOFT_RESET response: - 1 - Either 0 or 1 (FAILED and OK, respectively). Will end this bootloader session and reset the processor. + +.. _bootloader-reflashing: + +Flashing A Custom Bootloader +---------------------------- + +Stub (flashing a custom bootloader) diff --git a/source/compatibility.rst b/source/compatibility.rst index cf4c2b3..7eb0a8f 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -83,34 +83,32 @@ differences, most of which are improvements: full 32-bit (4 byte) integer values instead of the regular 16-bit (2 byte) Arduino values. -* `pinMode()`_ types: any :ref:`GPIO ` (including analog pins) - can be configured into one of the following modes with a single call - to `pinMode()`_: ``OUTPUT``, ``OUTPUT_OPEN_DRAIN``, - ``INPUT_FLOATING``, ``INPUT_PULLUP``, +* :ref:`pinMode() ` types: any :ref:`GPIO ` + (including analog pins) can be configured into one of the following + modes with a single call to ```pinMode()``: ``OUTPUT``, + ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``. Additionally, the PWM and Analog Input pins can be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the :ref:`GPIO documentation ` for more information. - .. TODO: reference libmaple docs above when they're done - -* Serial1 syntax: like the `Arduino Mega +* ``Serial1`` syntax: like the `Arduino Mega `_, the Maple has - multiple USART ports. By default, Serial is not mapped to any of - them, use ``Serial1`` through ``Serial3`` instead. - - .. TODO: reference libmaple docs for Serial[n] above when they're done + multiple :ref:`USART ports `. By default, ``Serial`` + is not mapped to any of them, use ``Serial1`` through ``Serial3`` + instead. * 16-bit :ref:`PWM `: Arduino boards support 8-bit PWM, which - means that calls to `analogWrite()`_ take values between 0 (always - off) and 255 (always on). The Maple supports 16-bit PWM, so the - corresponding values should be between 0 (always off) and 65535 - (always on). + means that calls to :ref:`analogWrite() ` take + values between 0 (always off) and 255 (always on). The Maple + supports 16-bit PWM, so the corresponding values should be between 0 + (always off) and 65535 (always on). * 12-bit :ref:`ADC `: Arduino boards support 10-bit ADC, which - means that calls to `analogRead()`_ will return values between 0 and - 1023. The Maple supports 12-bit ADC, so the same call will instead - return values between 0 and 4095. + means that calls to :ref:`analogRead() ` will + return values between 0 and 1023. The Maple supports 12-bit ADC, so + the same call will instead return values between 0 and 4095. +Stub (unfinished) .. class:: ported-feature @@ -130,5 +128,4 @@ I sorta work And I am also ordinary -Stub (unfinished) diff --git a/source/conf.py b/source/conf.py index 288efad..74090f6 100644 --- a/source/conf.py +++ b/source/conf.py @@ -88,7 +88,7 @@ with open('prolog.rst', 'r') as pr: #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). @@ -105,7 +105,7 @@ pygments_style = 'sphinx' #modindex_common_prefix = [] # Warn about all references where the target cannot be found. -#nitpicky = True +nitpicky = True # -- Options for HTML output -------------------------------------------------- diff --git a/source/lang/abs.rst b/source/lang/abs.rst index ed95e6f..0f71d9b 100644 --- a/source/lang/abs.rst +++ b/source/lang/abs.rst @@ -1,13 +1,19 @@ +.. highlight:: cpp + .. _lang-abs: -abs(x) +abs() ====== -Description ------------ - (Macro) computes the absolute value of a number. +Syntax +------ + +:: + + abs(x) + Parameters ---------- diff --git a/source/lang/analogwrite.rst b/source/lang/analogwrite.rst index d30d4d9..3d05f44 100644 --- a/source/lang/analogwrite.rst +++ b/source/lang/analogwrite.rst @@ -62,7 +62,7 @@ which control PWM output. See the :ref:`timers reference ` for more information. Another fix is to consult the :ref:`pin mapping mega table -` to find the timer which controls PWM on the +` to find the timer which controls PWM on the pin you're using, then set that Timer's overflow to 255. Subsequent calls to analogWrite() should work as on the Arduino (with the same loss of precision). Note, however, that that affects the overflow for diff --git a/source/lang/arithmetic.rst b/source/lang/arithmetic.rst index 9f21627..91fe22e 100644 --- a/source/lang/arithmetic.rst +++ b/source/lang/arithmetic.rst @@ -2,28 +2,27 @@ .. _lang-arithmetic: -Addition, Subtraction, Multiplication, & Division +Arithmetic Operators (``+``, ``-``, ``*``, ``/``) ================================================= -.. contents:: Contents - :local: - -Description ------------ - -These operators return the sum, difference, product, or quotient -(respectively) of the two operands. The operation is conducted using -the data type of the operands, so, for example, ``9 / 4`` gives ``2`` -since 9 and 4 are :ref:`int variables `. +The operators ``+``, ``-``, ``*``, and ``/`` respectively evaluate to +the sum, difference, product, or quotient (respectively) of the two +operands. The operation is conducted using the data type of the +operands, so, for example, ``9 / 4`` gives ``2`` since 9 and 4 are +:ref:`int variables `. This also means that the operation can overflow if the result is larger than that which can be stored in the data type (e.g. adding 1 -to an :ref:`lang-int` with the value 2147483647 gives --2147483648). If the operands are of different types, the "larger" -type is used for the calculation. +to an :ref:`lang-int` with the value 2,147,483,647 gives +-2,147,483,648). .. _lang-arithmetic-typeconversion: +If the operands are of different types, the "larger" type is used for +the calculation. If one of the numbers (operands) are of the type +**float** or of type **double**, floating point math will be used for +the calculation. + .. note:: The specifics of these rules are beyond the scope of this documentation; for more information, see `The C++ Programming Language `_\ , by Bjarne @@ -35,9 +34,8 @@ type is used for the calculation. see the Wikipedia page on `two's complement `_. -If one of the numbers (operands) are of the type **float** or of type -**double**, floating point math will be used for the -calculation. +.. contents:: Contents + :local: Examples -------- diff --git a/source/lang/arithmeticcompound.rst b/source/lang/arithmeticcompound.rst deleted file mode 100644 index aa0dc18..0000000 --- a/source/lang/arithmeticcompound.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. highlight:: cpp - -.. _lang-arithmeticcompound: - -Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) -=============================================================== - -Description ------------ - -Perform a mathematical operation on a variable with another constant -or variable. These operators are just a convenient shorthand:: - - x += y; // equivalent to the expression x = x + y; - x -= y; // equivalent to the expression x = x - y; - x *= y; // equivalent to the expression x = x * y; - x /= y; // equivalent to the expression x = x / y; - -Here is an example:: - - int x = 2; - int y = 10; - - x += 4; // x now contains 6 - x -= 3; // x now contains 3 - x *= y; // x now contains 30 - x /= 2; // x now contains 15 - x += max(20, 6); // x now contains 35 - x -= sq(5); // x now contains 15 - -Parameters ----------- - -**x**: a numeric variable - -**y**: a numeric variable, number constant, or any other expression -that evaluates to a number (e.g. call to a function that returns a -number). - -See Also --------- - -- :ref:`Arithmetic operators ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/assignment.rst b/source/lang/assignment.rst index 16f0bf4..b6ad4d5 100644 --- a/source/lang/assignment.rst +++ b/source/lang/assignment.rst @@ -2,8 +2,8 @@ .. _lang-assignment: -= assignment operator (single equal sign) -========================================= +Assignment Operator (``=``) +=========================== Stores the value to the right of the equal sign in the variable to the left of the equal sign. diff --git a/source/lang/bit.rst b/source/lang/bit.rst index c342fdd..dd5c050 100644 --- a/source/lang/bit.rst +++ b/source/lang/bit.rst @@ -3,14 +3,10 @@ bit() ===== -Description ------------ - (Macro) Computes the value of an (unsigned) integer with the specified bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8, 16, 32, etc.). - Syntax ------ diff --git a/source/lang/bitclear.rst b/source/lang/bitclear.rst index 5d1eb95..941f912 100644 --- a/source/lang/bitclear.rst +++ b/source/lang/bitclear.rst @@ -3,9 +3,6 @@ bitClear() ========== -Description ------------ - (Macro) Clears (writes a 0 to) a bit of a numeric variable. Syntax diff --git a/source/lang/bitread.rst b/source/lang/bitread.rst index 9f885cf..46b4478 100644 --- a/source/lang/bitread.rst +++ b/source/lang/bitread.rst @@ -3,9 +3,6 @@ bitRead() ========= -Description ------------ - (Macro) Gets the value of a bit in a number. diff --git a/source/lang/bitset.rst b/source/lang/bitset.rst index 502c1b6..ccd76de 100644 --- a/source/lang/bitset.rst +++ b/source/lang/bitset.rst @@ -3,9 +3,6 @@ bitSet() ======== -Description ------------ - (Macro) Sets (writes a 1 to) a bit of a numeric variable. diff --git a/source/lang/bitshift.rst b/source/lang/bitshift.rst index f05d49e..e1c8de0 100644 --- a/source/lang/bitshift.rst +++ b/source/lang/bitshift.rst @@ -2,17 +2,13 @@ .. _lang-bitshift: -Bit shift left (``<<``), bit shift right (``>>``) -================================================= - -Description ------------ +Bit Shift Operators (``<<``, ``>>``) +==================================== (Adapted from `The Bit Math Tutorial `_ in `The Arduino Playground `_\ ) - There are two bit shift operators in C++: the left shift operator ``<<`` and the right shift operator ``>>``. These operators cause the bits in the left operand to be shifted left or right by the number of diff --git a/source/lang/bitwisecompound.rst b/source/lang/bitwisecompound.rst deleted file mode 100644 index 2b0fe2f..0000000 --- a/source/lang/bitwisecompound.rst +++ /dev/null @@ -1,231 +0,0 @@ -.. highlight:: cpp - -.. _lang-bitwisecompound: - -Compound bitwise and (&=), or (\|=), XOR (^=) -============================================= - -The compound bitwise operators perform their calculations at the -bit level of variables. They are often used to clear and set -specific bits of a variable. - -See the :ref:`bitwise math tutorial ` for more -information on bitwise operators. - -.. contents:: Contents - :local: - -.. _lang-bitwisecompound-and: - -Compound bitwise AND (&=) -------------------------- - -The compound bitwise AND operator ``&=`` is often used with a variable -and a constant to force particular bits in a variable to be zero. This -is often referred to in programming guides as "clearing" or -"resetting" bits. In a program, writing the line ``x &= y;`` is -equivalent to writing ``x = x & y;``. That is, the value of ``x`` -after the line will be equal to its old value bitwise ANDed with the -value of ``y``:: - - x &= y; // equivalent to x = x & y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any :ref:`integer value -` (like ``3`` or ``0x20``) for ``y``. - -Before doing an example of ``&=``, let's first review the Bitwise AND -(``&``) operator:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 0 0 1 (operand1 & operand2) = result - -As shown above, bits that are "bitwise ANDed" with 0 become 0, while -bits that are "bitwise ANDed" with 1 are left unchanged. So, if ``b`` -is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b & -B11111111`` equals ``b``. - -.. _lang-bitwisecompound-binconst: - -.. note:: The above uses :ref:`binary constants - `\ . The numbers are still the same - value in other representations, they just might not be as easy to - understand. - - Normally, in C and C++ code, :ref:`hexadecimal - ` or :ref:`octal - ` are used when we're interested in - an integer's bits, rather than its value as a number. - - While hexadecimal and octal literals might be harder to understand - at first, you should really take the time to learn them. They're - part of C, C++, and many other programming languages, while binary - constants are available only for compatibility with Arduino. - - Also, ``B00000000`` is shown for clarity, but zero in any number - format is zero. - -So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while -leaving the rest of the variable's bits unchanged, use the compound -bitwise AND operator ``&=`` with the constant ``B11111100`` -(hexadecimal ``0xFC``\ ):: - - 1 0 1 0 1 0 1 0 variable - 1 1 1 1 1 1 0 0 mask - ---------------------- - 1 0 1 0 1 0 0 0 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged cleared - - -Here is the same representation with the variable's bits replaced -with the symbol ``x``\ :: - - x x x x x x x x variable - 1 1 1 1 1 1 0 0 mask - ---------------------- - x x x x x x 0 0 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged cleared - - -So, using a byte variable ``b``\ , if we say:: - - b = B10101010; // B10101010 == 0xAA - b &= B11111100; // B11111100 == 0xFC - -then we will have :: - - b == B10101000; // B10101000 == 0xA8 - -.. _lang-bitwisecompound-or: - -Compound bitwise OR (\|=) -------------------------- - -The compound bitwise OR operator ``|=`` is often used with a variable -and a constant to "set" (set to 1) particular bits in a variable. In -a program, writing the line ``x |= y;`` is equivalent to writing ``x = -x | y;``. That is, the value of ``x`` after the line will be equal to -its old value bitwise ORed with the value of ``y``:: - - x |= y; // equivalent to x = x | y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`compound bitwise AND -`\ , ``&=``). - -Before doing an example of ``|=``, let's first review the Bitwise OR -(``|``) operator:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) = result - -Bits that are "bitwise ORed" with 0 are unchanged, while bits that are -"bitwise ORed" with 1 are set to 1. So if ``b`` is a ``byte`` -variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111`` -equals ``B11111111`` (here we've used binary constants; see the -:ref:`note ` above). - -So, to set bits 0 and 1 of a one-byte variable, while leaving the rest -of the variable unchanged, use the compound bitwise OR operator -(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``):: - - 1 0 1 0 1 0 1 0 variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - 1 0 1 0 1 0 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged set - -Here is the same representation with the variable's bits replaced with -the symbol ``x``:: - - x x x x x x x x variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - x x x x x x 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged set - -So, using a byte variable ``b``, if we say:: - - b = B10101010; // B10101010 == 0xAA - b |= B00000011; // B00000011 == 0x3 - -then we will have :: - - b == B10101011; // B10101011 == 0xAB - -.. _lang-bitwisecompound-xor: - -Compound bitwise XOR (\^=) --------------------------- - -The compound bitwise XOR operator ``^=`` is used with a variable and a -constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a -variable. In a program, writing the line ``x ^= y;`` is equivalent to -writing ``x = x ^ y;``. That is, the value of ``x`` after the line -will be equal to its old value bitwise XORed with the value of ``y``:: - - x ^= y; // equivalent to x = x ^ y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`&= -` and :ref:`\|= -`; in fact, these three operators all -work the same in this way). - -Before doing an example of ``^=``, let's first review the Bitwise -XOR operator, ``^``:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 0 (operand1 ^ operand2) = result - -One way to look at bitwise XOR is that each bit in the result is a 1 -if the input bits are different, or 0 if they are the same. Another -way to think about it is that the result bit will be 1 when *exactly* -one (no more, no less) of the input bits is 1; otherwise, it will be -zero. This means that if you XOR a bit with 1, it will change (or -toggle) its value, while if you XOR a bit with 0, it stays the same. - -So, to toggle bits 0 and 1 of a one-byte variable, while leaving the -rest of the variable unchanged, use the compound bitwise XOR operator -``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see -:ref:`note ` above):: - - 1 0 1 0 1 0 1 0 variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - 1 0 1 0 1 0 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged toggled - -So, using a byte variable ``b``, if we say:: - - b = B10101010; // B10101010 == 0xAA - b ^= B00000011; // B00000011 == 0x3 - -then we will have :: - - b == B10101001; // B10101001 == 0xA9 - -See Also --------- - -- :ref:`Boolean operations ` (``&&``, ``||``) -- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) - - -.. include:: cc-attribution.txt diff --git a/source/lang/bitwisemath.rst b/source/lang/bitwisemath.rst index 30e8873..28fe6bf 100644 --- a/source/lang/bitwisemath.rst +++ b/source/lang/bitwisemath.rst @@ -2,8 +2,8 @@ .. _lang-bitwisemath: -Bitwise AND (&), OR (\|), XOR (^), NOT (~) -========================================== +Bitwise Operators (``&``, ``|``, ``^``, ``~``) +============================================== The bitwise operators perform their calculations at the bit level of variables. They help solve a wide range of common programming @@ -22,8 +22,8 @@ Below are descriptions and syntax for all of the operators. .. _lang-bitwisemath-and: -Bitwise AND (&) ---------------- +Bitwise AND (``&``) +------------------- The bitwise AND operator in C++ is a single ampersand, ``&``, used between two other integer expressions. Bitwise AND operates on each @@ -54,8 +54,8 @@ value 1000100 in binary, which is 68 in decimal. .. _lang-bitwisemath-or: -Bitwise OR (\|) ---------------- +Bitwise OR (``|``) +------------------ The bitwise OR operator in C++ is the vertical bar symbol, ``|``. Like the ``&`` operator, ``|`` operates independently on each bit in its @@ -78,8 +78,8 @@ uses 32):: .. _lang-bitwisemath-xor: -Bitwise XOR (^) ---------------- +Bitwise XOR (``^``) +------------------- There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE OR, also known as bitwise XOR. (In English, this is usually pronounced @@ -129,8 +129,8 @@ program to blink digital pin 13 (the LED pin on Maple):: .. _lang-bitwisemath-not: -Bitwise NOT (~) ---------------- +Bitwise NOT (``~``) +------------------- The bitwise NOT operator in C++ is the tilde character ``~``. Unlike ``&`` and ``|``, the bitwise NOT operator is applied to a single @@ -179,7 +179,7 @@ See Also -------- - :ref:`Boolean operations ` (``&&``, ``||``) -- :ref:`Compound bitwise operations ` (``&=``, +- :ref:`Compound bitwise operations ` (``&=``, ``|=``, ``^=``). diff --git a/source/lang/bitwrite.rst b/source/lang/bitwrite.rst index 86df26e..b3feff2 100644 --- a/source/lang/bitwrite.rst +++ b/source/lang/bitwrite.rst @@ -1,13 +1,19 @@ -.. _lang-bitwrite: +.. highlight:: cpp -bitWrite(x, n, b) -================= +.. _lang-bitwrite: -Description ------------ +bitWrite() +========== (Macro) Writes a bit of a numeric variable. +Syntax +------ + +:: + + bitWrite(x, n, b) + Parameters ---------- diff --git a/source/lang/boolean.rst b/source/lang/boolean.rst index 6ff4097..8d6aa5c 100644 --- a/source/lang/boolean.rst +++ b/source/lang/boolean.rst @@ -83,7 +83,7 @@ See Also -------- - :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) -- :ref:`Compound bitwise operators ` (``&=``, +- :ref:`Compound bitwise operators ` (``&=``, ``|=``, ``^=``). - :ref:`if statement ` diff --git a/source/lang/booleanvariables.rst b/source/lang/booleanvariables.rst index 9d0e992..6051b8c 100644 --- a/source/lang/booleanvariables.rst +++ b/source/lang/booleanvariables.rst @@ -6,9 +6,8 @@ Booleans ======== A **boolean** holds one of two values, :ref:`true -` or :ref:`false `. -On a Maple, each boolean variable occupies one byte of memory, and has -type ``bool``. +` or :ref:`false `. On a +Maple, each boolean variable has type ``bool``. .. warning:: diff --git a/source/lang/braces.rst b/source/lang/braces.rst deleted file mode 100644 index 229ad8c..0000000 --- a/source/lang/braces.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. highlight:: cpp - -.. _lang-braces: - -Curly Braces ({}) -================= - -.. contents:: Contents - :local: - -Introduction ------------- - -Curly braces (also referred to as just "braces" or as "curly -brackets") are a major part of the C and C++ programming -languages. They are used in several different constructs, outlined -below, and this can sometimes be confusing for beginners. - -An opening curly brace, ``{`` must always be followed by a closing -curly brace ``}``. This is a condition that is often referred to as -the braces being *balanced*. The Maple IDE (integrated development -environment) includes a convenient feature to check the balance of -curly braces. Just select a brace, or even click the insertion point -immediately following a brace, and its companion will be highlighted\ -[#fbug]_\ . - -Beginning programmers, and programmers coming to C++ from languages -without braces, often find using them confusing or daunting. - -Because the use of the curly brace is so varied, it is good -programming practice to type the closing brace immediately after -typing the opening brace when inserting a construct which requires -curly braces. Then insert some blank lines between your braces and -begin inserting statements. Your braces, and your attitude, will never -become unbalanced. - -Unbalanced braces can often lead to cryptic, impenetrable compiler -errors that can sometimes be hard to track down in a large program. -Because of their varied usages, braces are also incredibly important -to the syntax of a program and moving a brace one or two lines will -usually dramatically affect the meaning of a program. - -The main uses of curly braces ------------------------------ - -**Functions**:: - - // a function body needs braces around it - void myFunction(datatype argument) { - // ... function body goes in here ... - } - -**Loops** (see the :ref:`while `\ , :ref:`for -`\ , and :ref:`do/while ` loop reference -pages for more information):: - - // you should put braces around the body of a loop: - - while (boolean expression) { - // code inside the loop goes here - } - - for (initialisation; termination condition; incrementing expr) { - // code inside the loop goes here - } - - do { - // code inside the loop goes here - } while (boolean expression); - - -**Conditional statements** (see the :ref:`if statement ` -reference page for more information):: - - // you should put braces around the body of an "if", "else if", - // or "else": - - if (boolean expression) { - // code inside the "if" - } - else if (boolean expression) { - // code inside the "else if" - } - else { - // code inside the "else" - } - -**Switch statements** (see the :ref:`switch statement -` reference page for more information):: - - switch (var) { - case 1: - doThing1(); - break; - case 2: - doThing2(); - break; - } - -.. rubric:: Footnotes - -.. TODO remove this once IDE 0.1.0 released - -.. [#fbug] At present this feature is slightly buggy as the IDE will - often find (incorrectly) a brace in text that has been commented - out. - - -.. include:: cc-attribution.txt diff --git a/source/lang/break.rst b/source/lang/break.rst index dc50b5f..ce8ac17 100644 --- a/source/lang/break.rst +++ b/source/lang/break.rst @@ -2,8 +2,8 @@ .. _lang-break: -break -===== +``break`` +========= ``break`` is used to exit from a :ref:`while `\ , :ref:`for `\ , or :ref:`do/while ` loop, diff --git a/source/lang/bytecast.rst b/source/lang/bytecast.rst index 4ad2a89..b3f0de2 100644 --- a/source/lang/bytecast.rst +++ b/source/lang/bytecast.rst @@ -5,9 +5,6 @@ byte() (cast) ============= -Description ------------ - Converts a value to the :ref:`byte ` data type. .. note:: diff --git a/source/lang/char.rst b/source/lang/char.rst index 8c6dadf..b8747f3 100644 --- a/source/lang/char.rst +++ b/source/lang/char.rst @@ -2,11 +2,8 @@ .. _lang-char: -char -==== - -Description ------------ +``char`` +======== The ``char`` type stores a 1-byte character value (or integer with value from -128 to 127). Character literals are written in single diff --git a/source/lang/charcast.rst b/source/lang/charcast.rst index 844dd58..a480dec 100644 --- a/source/lang/charcast.rst +++ b/source/lang/charcast.rst @@ -2,11 +2,8 @@ .. _lang-charcast: -char() (cast) -============= - -Description ------------ +``char()`` (cast) +================= Converts a value to the :ref:`char ` data type. diff --git a/source/lang/comparison.rst b/source/lang/comparison.rst index 8873256..b24355f 100644 --- a/source/lang/comparison.rst +++ b/source/lang/comparison.rst @@ -2,8 +2,8 @@ .. _lang-comparison: -Comparison Operators -==================== +Comparison Operators (``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``) +=================================================================== The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and ``>=`` are used to compare two numbers. They are :ref:`true diff --git a/source/lang/compoundarithmetic.rst b/source/lang/compoundarithmetic.rst new file mode 100644 index 0000000..420f1db --- /dev/null +++ b/source/lang/compoundarithmetic.rst @@ -0,0 +1,44 @@ +.. highlight:: cpp + +.. _lang-compoundarithmetic: + +Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) +=============================================================== + +These oparators perform a mathematical operation on a variable with +another constant or variable. These operators are just a convenient +shorthand:: + + x += y; // equivalent to the expression x = x + y; + x -= y; // equivalent to the expression x = x - y; + x *= y; // equivalent to the expression x = x * y; + x /= y; // equivalent to the expression x = x / y; + +Here is an example:: + + int x = 2; + int y = 10; + + x += 4; // x now contains 6 + x -= 3; // x now contains 3 + x *= y; // x now contains 30 + x /= 2; // x now contains 15 + x += max(20, 6); // x now contains 35 + x -= sq(5); // x now contains 15 + +Parameters +---------- + +**x**: a numeric variable + +**y**: a numeric variable, number constant, or any other expression +that evaluates to a number (e.g. call to a function that returns a +number). + +See Also +-------- + +- :ref:`Arithmetic operators ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/compoundbitwise.rst b/source/lang/compoundbitwise.rst new file mode 100644 index 0000000..a4bbb24 --- /dev/null +++ b/source/lang/compoundbitwise.rst @@ -0,0 +1,231 @@ +.. highlight:: cpp + +.. _lang-compoundbitwise: + +Compound Bitwise Operators (``&=``, ``|=``, ``^=``) +=================================================== + +The compound bitwise operators perform their calculations at the +bit level of variables. They are often used to clear and set +specific bits of a variable. + +See the :ref:`bitwise math tutorial ` for more +information on bitwise operators. + +.. contents:: Contents + :local: + +.. _lang-compoundbitwise-and: + +Compound bitwise AND (``&=``) +----------------------------- + +The compound bitwise AND operator ``&=`` is often used with a variable +and a constant to force particular bits in a variable to be zero. This +is often referred to in programming guides as "clearing" or +"resetting" bits. In a program, writing the line ``x &= y;`` is +equivalent to writing ``x = x & y;``. That is, the value of ``x`` +after the line will be equal to its old value bitwise ANDed with the +value of ``y``:: + + x &= y; // equivalent to x = x & y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any :ref:`integer value +` (like ``3`` or ``0x20``) for ``y``. + +Before doing an example of ``&=``, let's first review the Bitwise AND +(``&``) operator:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) = result + +As shown above, bits that are "bitwise ANDed" with 0 become 0, while +bits that are "bitwise ANDed" with 1 are left unchanged. So, if ``b`` +is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b & +B11111111`` equals ``b``. + +.. _lang-compoundbitwise-binconst: + +.. note:: The above uses :ref:`binary constants + `\ . The numbers are still the same + value in other representations, they just might not be as easy to + understand. + + Normally, in C and C++ code, :ref:`hexadecimal + ` or :ref:`octal + ` are used when we're interested in + an integer's bits, rather than its value as a number. + + While hexadecimal and octal literals might be harder to understand + at first, you should really take the time to learn them. They're + part of C, C++, and many other programming languages, while binary + constants are available only for compatibility with Arduino. + + Also, ``B00000000`` is shown for clarity, but zero in any number + format is zero. + +So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while +leaving the rest of the variable's bits unchanged, use the compound +bitwise AND operator ``&=`` with the constant ``B11111100`` +(hexadecimal ``0xFC``\ ):: + + 1 0 1 0 1 0 1 0 variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + 1 0 1 0 1 0 0 0 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared + + +Here is the same representation with the variable's bits replaced +with the symbol ``x``\ :: + + x x x x x x x x variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + x x x x x x 0 0 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared + + +So, using a byte variable ``b``\ , if we say:: + + b = B10101010; // B10101010 == 0xAA + b &= B11111100; // B11111100 == 0xFC + +then we will have :: + + b == B10101000; // B10101000 == 0xA8 + +.. _lang-compoundbitwise-or: + +Compound bitwise OR (``|=``) +---------------------------- + +The compound bitwise OR operator ``|=`` is often used with a variable +and a constant to "set" (set to 1) particular bits in a variable. In +a program, writing the line ``x |= y;`` is equivalent to writing ``x = +x | y;``. That is, the value of ``x`` after the line will be equal to +its old value bitwise ORed with the value of ``y``:: + + x |= y; // equivalent to x = x | y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`compound bitwise AND +`\ , ``&=``). + +Before doing an example of ``|=``, let's first review the Bitwise OR +(``|``) operator:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) = result + +Bits that are "bitwise ORed" with 0 are unchanged, while bits that are +"bitwise ORed" with 1 are set to 1. So if ``b`` is a ``byte`` +variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111`` +equals ``B11111111`` (here we've used binary constants; see the +:ref:`note ` above). + +So, to set bits 0 and 1 of a one-byte variable, while leaving the rest +of the variable unchanged, use the compound bitwise OR operator +(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``):: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set + +Here is the same representation with the variable's bits replaced with +the symbol ``x``:: + + x x x x x x x x variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + x x x x x x 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set + +So, using a byte variable ``b``, if we say:: + + b = B10101010; // B10101010 == 0xAA + b |= B00000011; // B00000011 == 0x3 + +then we will have :: + + b == B10101011; // B10101011 == 0xAB + +.. _lang-compoundbitwise-xor: + +Compound bitwise XOR (``^=``) +----------------------------- + +The compound bitwise XOR operator ``^=`` is used with a variable and a +constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a +variable. In a program, writing the line ``x ^= y;`` is equivalent to +writing ``x = x ^ y;``. That is, the value of ``x`` after the line +will be equal to its old value bitwise XORed with the value of ``y``:: + + x ^= y; // equivalent to x = x ^ y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`&= +` and :ref:`\|= +`; in fact, these three operators all +work the same in this way). + +Before doing an example of ``^=``, let's first review the Bitwise +XOR operator, ``^``:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) = result + +One way to look at bitwise XOR is that each bit in the result is a 1 +if the input bits are different, or 0 if they are the same. Another +way to think about it is that the result bit will be 1 when *exactly* +one (no more, no less) of the input bits is 1; otherwise, it will be +zero. This means that if you XOR a bit with 1, it will change (or +toggle) its value, while if you XOR a bit with 0, it stays the same. + +So, to toggle bits 0 and 1 of a one-byte variable, while leaving the +rest of the variable unchanged, use the compound bitwise XOR operator +``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see +:ref:`note ` above):: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged toggled + +So, using a byte variable ``b``, if we say:: + + b = B10101010; // B10101010 == 0xAA + b ^= B00000011; // B00000011 == 0x3 + +then we will have :: + + b == B10101001; // B10101001 == 0xA9 + +See Also +-------- + +- :ref:`Boolean operations ` (``&&``, ``||``) +- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) + + +.. include:: cc-attribution.txt diff --git a/source/lang/const.rst b/source/lang/const.rst index 1658e6d..52de85f 100644 --- a/source/lang/const.rst +++ b/source/lang/const.rst @@ -2,8 +2,8 @@ .. _lang-const: -const Keyword -============= +``const`` +========= The ``const`` keyword stands for "constant". It is a variable *qualifier* that modifies the behavior of the variable, making a diff --git a/source/lang/constants.rst b/source/lang/constants.rst index b7521ed..bc5c894 100644 --- a/source/lang/constants.rst +++ b/source/lang/constants.rst @@ -1,11 +1,11 @@ .. _lang-constants: -constants +Constants ========= -Constants are predefined variables in the Arduino language. They -are used to make the programs easier to read. We classify constants -in groups. +Constants are like predefined variables, whose values can't +change. They are used to make the programs easier to read and modify. +This page describes the most commonly used constants. .. contents:: Contents :local: @@ -15,288 +15,290 @@ in groups. Boolean Constants ----------------- -There are two constants used to represent truth and falsity in the -Arduino language: **true**, and **false**. +There are two constants used to represent truth and falsity: ``true``, +and ``false``. .. _lang-constants-false: false ^^^^^ -false is the easier of the two to define. false is defined as 0 -(zero). +``false`` is the false ``bool`` value. An integer which is 0 evaluates +to ``false`` as a boolean. .. _lang-constants-true: true ^^^^ -true is often said to be defined as 1, which is correct, but true -has a wider definition. Any integer which is *non-zero* is TRUE, in -a Boolean sense. So -1, 2 and -200 are all defined as true, too, in -a Boolean sense. +``true`` is the true ``bool`` value. As an integer, ``true`` is often +said to be 1. This is correct in the sense that ``true`` evaluates to +1 as an integer. However, any integer which is *non-zero* is ``true`` +as a :ref:`bool `. So -1, 2 and -200 are all +"true", in the sense that these numbers are treated the same as +``true`` in a boolean context. +Note that the ``true`` and ``false`` constants are typed in lowercase; +unlike e.g. ``HIGH``, ``LOW``, ``INPUT``, and ``OUTPUT`` (which are +described below). -Note that the *true* and *false* constants are typed in lowercase -unlike HIGH, LOW, INPUT, & OUTPUT. +Pin Levels: HIGH and LOW +------------------------ -Defining Pin Levels, HIGH and LOW ---------------------------------- - -When reading or writing to a digital pin there are only two -possible values a pin can take/be-set-to: **HIGH** and **LOW**. +When reading or writing to a digital pin there are only two possible +values a pin can be set to: ``HIGH`` and ``LOW``. .. _lang-constants-high: -**HIGH** - - - -The meaning of HIGH (in reference to a pin) is somewhat different -depending on whether a pin is set to an INPUT or OUTPUT. When a pin -is configured as an INPUT with pinMode, and read with digitalRead, -the microcontroller will report HIGH if a voltage of 3 volts or -more is present at the pin. - - +HIGH +^^^^ -A pin may also be configured as an INPUT with pinMode, and -subsequently made HIGH with digitalWrite, this will set the -internal 20K pullup resistors, which will *steer* the input pin to -a HIGH reading unless it is pulled LOW by external circuitry. +The meaning of ``HIGH`` (in reference to a pin) is somewhat different +depending on whether the pin is set to ``INPUT`` or ``OUTPUT``. When a +pin is configured as an ``INPUT`` (using :ref:`pinMode() +`), and read with :ref:`digitalRead() +`, the microcontroller will report ``HIGH`` if a +voltage of 3 volts or more is present at the pin. +.. TODO? Following seems false; check it out sometime, leave out for now: +.. A pin may also be configured as an ``INPUT`` with ``pinMode()``, and +.. subsequently made ``HIGH`` with :ref:`digitalWrite() +.. `, this will set the internal pullup resistors, +.. which will *steer* the input pin to a HIGH reading unless it is pulled +.. LOW by external circuitry. -When a pin is configured to OUTPUT with pinMode, and set to HIGH -with digitalWrite, the pin is at 5 volts. In this state it can -*source* current, e.g. light an LED that is connected through a -series resistor to ground, or to another pin configured as an -output, and set to LOW. +When a pin is configured to ``OUTPUT`` with pinMode, and set to +``HIGH`` with :ref:`digitalWrite() `, the pin is at +3.3 volts. In this state it can *source* current, e.g. light an LED +that is connected through a series resistor to ground, or to another +pin configured as an output and set to ``LOW``. .. _lang-constants-low: -**LOW** +LOW +^^^ +The meaning of ``LOW`` also has a different meaning depending on +whether a pin is set to ``INPUT`` or ``OUTPUT``. When a pin is +configured as an ``INPUT`` with :ref:`pinMode() `, and +read with :ref:`digitalRead() `, the microcontroller +will report ``LOW`` if a voltage of 2 volts or less is present at the +pin. +When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to +``LOW`` with :ref:`digitalWrite() `, the +microcontroller will attempt to keep that pin's voltage at 0V. In this +state it can *sink* current, e.g. light an LED that is connected +through a series resistor to +3.3V, or to another pin configured as an +output, and set to ``HIGH``. -The meaning of LOW also has a different meaning depending on -whether a pin is set to INPUT or OUTPUT. When a pin is configured -as an INPUT with pinMode, and read with digitalRead, the -microcontroller will report LOW if a voltage of 2 volts or less is -present at the pin. +Pin Modes +--------- +Digital pins can be used in a variety of modes. The basic modes, +``INPUT`` and ``OUTPUT``, have been introduced above. Changing a pin +from ``INPUT`` TO ``OUTPUT`` with :ref:`pinMode() ` +drastically changes the electrical behavior of the pin. - -When a pin is configured to OUTPUT with pinMode, and set to LOW -with digitalWrite, the pin is at 0 volts. In this state it can -*sink* current, e.g. light an LED that is connected through a -series resistor to, +5 volts, or to another pin configured as an -output, and set to HIGH. - - - -Defining Digital Pins, INPUT and OUTPUT ---------------------------------------- - -Digital pins can be used either as **INPUT** or **OUTPUT**. -Changing a pin from INPUT TO OUTPUT with pinMode() drastically -changes the electrical behavior of the pin. +This section describes the basic digital pin modes (``INPUT`` and +``OUTPUT``) only. For a detailed description of all possible pin +modes, see the :ref:`pinMode() ` reference page. .. _lang-constants-input: -Pins Configured as Inputs -^^^^^^^^^^^^^^^^^^^^^^^^^ +INPUT +^^^^^ -Arduino (Atmega) pins configured as **INPUT** with pinMode() are -said to be in a high-impedance state. One way of explaining this is -that pins configured as INPUT make extremely small demands on the -circuit that they are sampling, say equivalent to a series resistor -of 100 Megohms in front of the pin. This makes them useful for -reading a sensor, but not powering an LED. +Maple (STM32) pins configured as ``INPUT`` are said to be in a +high-impedance state. One way of explaining this is that pins +configured as ``INPUT`` make extremely small demands on the circuit +that they are sampling. This makes them useful for reading a sensor, +but not powering an LED. .. _lang-constants-output: -Pins Configured as Outputs -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Pins configured as **OUTPUT** with pinMode() are said to be in a -low-impedance state. This means that they can provide a substantial -amount of current to other circuits. Atmega pins can source -(provide positive current) or sink (provide negative current) up to -40 mA (milliamps) of current to other devices/circuits. This makes -them useful for powering LED's but useless for reading sensors. -Pins configured as outputs can also be damaged or destroyed if -short circuited to either ground or 5 volt power rails. The amount -of current provided by an Atmega pin is also not enough to power -most relays or motors, and some interface circuitry will be -required. - -.. _lang-constants-fp: - -Floating-Point Constants ------------------------- - -Similar to integer constants, floating point constants are used to -make code more readable. Floating point constants are swapped at -compile time for the value to which the expression evaluates. - -.. TODO explain that floating point literals are doubles - -.. _lang-constants-fp-f: - -.. TODO f modifiers - -Examples: +OUTPUT +^^^^^^ -``n = .005;`` +Pins configured as ``OUTPUT`` with :ref:`pinMode() ` are +said to be in a low-impedance state. This means that they can provide +a substantial amount of current to other circuits. STM32 pins can +source (provide positive current) or sink (provide negative current) +up to 50 mA (milliamps) of current to other devices/circuits. This +makes them useful for powering LEDs, but useless for reading sensors. -Floating point constants can also be expressed in a variety of -scientific notation. 'E' and 'e' are both accepted as valid -exponent indicators. - -:: - - - floating-point evaluates to: also evaluates to: - constant - - 10.0 10 - 2.34E5 2.34 * 10^5 234000 - 67e-12 67.0 * 10^-12 .000000000067 +Pins configured as outputs can also be damaged or destroyed if short +circuited to either ground or 3.3V power rails. The amount of current +provided by an STM32 pin is also not enough to power most relays or +motors, and some interface circuitry will be required. .. _lang-constants-integers: Integer Constants ----------------- -Integer constants are numbers used directly in a sketch, like -``123``. By default, these numbers are treated as -`int `_'s but you can change -this with the U and L modifiers (see below). - - - -Normally, integer constants are treated as base 10 (decimal) -integers, but special notation (formatters) may be used to enter -numbers in other bases. - - - -:: - - Base Example Formatter Comment - - 10 (decimal) 123 none - - 2 (binary) B1111011 leading 'B' only works with 8 bit values (0 to 255) - characters 0-1 valid - - 8 (octal) 0173 leading "0" characters 0-7 valid - - 16 (hexadecimal) 0x7B leading "0x" characters 0-9, A-F, a-f valid +Integer constants (or more properly speaking, integer *literals*) are +numbers used directly in a sketch, like ``123``. By default, an +integer literal is treated as a (signed) :ref:`int `, but +you can change this with the U and L modifiers (see :ref:`below +`). You can specify negative numbers by +putting a minus sign in front, like ``-123``. + +Normally, integer literals are treated as base 10 (decimal) integers, +but special notation (formatters) may be used to enter numbers in +other bases. These are summarized in the following table: + +.. list-table:: + :header-rows: 1 + + * - Base + - Example + - Formatter + - Comment + + * - 10 (decimal) + - ``123`` + - None + - + + * - 2 (binary) + - ``0b1111011`` + - Leading "0b" + - GCC extension; not standard C++ + + * - 8 (octal) + - ``0173`` + - Leading "0" + - Characters 0-7 valid + + * - 16 (hexadecimal) + - ``0x7B`` + - Leading "0x" + - Characters 0-9, A-F (or a-f) valid + +Binary constants (like ``B1111011``) for values between 0 and 255 are +supported for compatibility with Arduino only. Their use in new +programs is discouraged. .. _lang-constants-integers-dec: -**Decimal** is base 10. This is the common-sense math with which -you are acquainted. Constants without other prefixes are assumed to -be in decimal format. +**Decimal** is base 10. This is the common number system we learn in +school. Integer literals without other prefixes are assumed to be in +decimal format. - - -Example: -:: - - 101 // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) +For example, the decimal literal ``101`` is one hundred and one: 1×10\ +:sup:`2` + 0×10\ :sup:`1` + 1×10\ :sup:`0` = 101. .. _lang-constants-integers-bin: -**Binary** is base two. Only characters 0 and 1 are valid. - - - -Example: -:: - - B101 // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) - -The binary formatter only works on bytes (8 bits) between 0 (B0) -and 255 (B11111111). If it is convenient to input an int (16 bits) -in binary form you can do it a two-step procedure such as: +**Binary** is base two. Only characters 0 and 1 are valid. Binary +literals are indicated by the prefix ``0b`` (this is a :ref:`GCC +` extension; it's not standard C++). - - -:: - - myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte +For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` + +0×2\ :sup:`1` + 1×2\ :sup:`0` = 5. .. _lang-constants-integers-oct: **Octal** is base eight. Only characters 0 through 7 are valid. Octal -values are indicated by the prefix "0". +literals are indicated by the prefix ``0``. -Example: +For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` + +0×8\ :sup:`1` + 1×8\ :sup:`0` = 65. -:: +.. warning:: Bugs sometimes result by (unintentionally) including a + leading "0" before an integer literal, which makes the compiler + interpret it in octal. - 0101 // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) +.. _lang-constants-integers-hex: -Warning -It is possible to generate a hard-to-find bug by (unintentionally) -including a leading zero before a constant and having the compiler -unintentionally interpret your constant as octal. +**Hexadecimal** (or "hex") is base sixteen. Valid characters are 0 +through 9 and letters A through F; A has the value 10, B is 11, up to +F, which is 15. Hex values are indicated by the prefix ``0x``. A-F +may be typed in upper or lower case (a-f). -.. _lang-constants-integers-hex: +For example, the hexadecimal literal ``0x101`` is two hundred fifty +seven: 1×16\ :sup:`2` + 0×16\ :sup:`1` + 1×16\ :sup:`0` = 257. -**Hexadecimal (or hex)** is base sixteen. Valid characters are 0 -through 9 and letters A through F; A has the value 10, B is 11, up -to F, which is 15. Hex values are indicated by the prefix "0x". -Note that A-F may be syted in upper or lower case (a-f). +The hexadecimal literal ``0xCF2`` is three thousand, three hundred +fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314. +(Remember that in hex, ``A`` means 10, and counting up, ``B``\ =11, so +``C``\ =12 and ``F``\ =15). +.. _lang-constants-integers-u-l: -Example: +U and L Suffixes +^^^^^^^^^^^^^^^^ -:: +By default, an integer constant is treated as an :ref:`int +`, with the attendant :ref:`limitations in values +`. To specify an integer constant with another data +type, follow it with: - 0x101 // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) +- a ``u`` or ``U`` to interpret the constant as an unsigned value. + For example, ``33U`` is an :ref:`unsigned int `. -.. _lang-constants-integers-u-l: +- an ``l`` or ``L`` to interpret the constant as a long value. For + example, ``100000L`` is a :ref:`long `. -U & L formatters -^^^^^^^^^^^^^^^^ +- a ``ul`` or ``UL`` to do both. For example, ``32767UL`` is an + :ref:`unsigned long `. + +.. _lang-constants-fp: -By default, an integer constant is treated as an -`int `_ with the attendant -limitations in values. To specify an integer constant with another -data type, follow it with: +Floating-Point Constants +------------------------ +Similar to integer literals, floating point constants (properly: +floating-point *literals*) are used to make code more readable. +Floating point literals are swapped at compile time for the value to +which the expression evaluates. +A floating point literal is any number which includes a decimal point. +For instance, ``3.0`` is a floating-point literal for the number 3. +By default, a floating-point literal is a :ref:`double `. +In order for the literal to be interpreted as a :ref:`float +`, you can write ``f`` directly after it. For example, +``3.0f`` is a floating-point literal with type ``float``. +Floating point constants can also be expressed in a variety of +scientific notation. ``E`` and ``e`` are both accepted as valid +exponent indicators. Some examples are given in the following table: -- a 'u' or 'U' to force the constant into an unsigned data format. - Example: ``33u`` -- a 'l' or 'L' to force the constant into a long data format. - Example: ``100000L`` -- a 'ul' or 'UL' to force the constant into an unsigned long - constant. Example: ``32767ul`` +.. list-table:: + :header-rows: 1 + * - Floating-point literal + - Evaluates to + - Alternate expression + * - ``10.0`` + - 10 + - -See also --------- + * - ``2.34E5`` + - 2.34×10\ :sup:`5` + - ``234000.0`` + * - ``67e-12`` + - 67.0×10\ :sup:`-12` + - ``0.000000000067`` -- `pinMode() `_ -- `Integer Constants `_ -- `boolean variables `_ -- `#define `_ -- `byte `_ -- `int `_ -- `unsigned int `_ -- `long `_ -- `unsigned long `_ +See Also +-------- +- :ref:`pinMode() ` +- :ref:`Boolean Variables ` +- :ref:`#define ` +- :ref:`int ` +- :ref:`unsigned int ` +- :ref:`long ` +- :ref:`unsigned long ` +- :ref:`float ` +- :ref:`double ` .. include:: cc-attribution.txt diff --git a/source/lang/constrain.rst b/source/lang/constrain.rst index 297a2d4..d19b61c 100644 --- a/source/lang/constrain.rst +++ b/source/lang/constrain.rst @@ -2,14 +2,18 @@ .. _lang-constrain: -constrain(x, a, b) -================== - -Description ------------ +constrain() +=========== (Macro) Constrains a number to be within a range. +Syntax +------ + +:: + + constrain(x, a, b) + Parameters ---------- diff --git a/source/lang/continue.rst b/source/lang/continue.rst index 21b3984..13d1815 100644 --- a/source/lang/continue.rst +++ b/source/lang/continue.rst @@ -2,9 +2,8 @@ .. _lang-continue: -========== - continue -========== +``continue`` +============ The ``continue`` keyword skips the rest of the current iteration of a :ref:`while `\ , :ref:`for `\ , or @@ -12,9 +11,8 @@ The ``continue`` keyword skips the rest of the current iteration of a conditional expression of the loop, and proceeding with any subsequent iterations. - Example -======= +------- :: diff --git a/source/lang/curly-braces.rst b/source/lang/curly-braces.rst new file mode 100644 index 0000000..a4bd3dc --- /dev/null +++ b/source/lang/curly-braces.rst @@ -0,0 +1,109 @@ +.. highlight:: cpp + +.. _lang-curly-braces: + +Curly Braces (``{``, ``}``) +=========================== + +.. contents:: Contents + :local: + +Introduction +------------ + +Curly braces (also referred to as just "braces" or as "curly +brackets") are a major part of the C and C++ programming +languages. They are used in several different constructs, outlined +below, and this can sometimes be confusing for beginners. + +An opening curly brace, ``{`` must always be followed by a closing +curly brace ``}``. This is a condition that is often referred to as +the braces being *balanced*. The Maple IDE (integrated development +environment) includes a convenient feature to check the balance of +curly braces. Just select a brace, or even click the insertion point +immediately following a brace, and its companion will be highlighted\ +[#fbug]_\ . + +Beginning programmers, and programmers coming to C++ from languages +without braces, often find using them confusing or daunting. + +Because the use of the curly brace is so varied, it is good +programming practice to type the closing brace immediately after +typing the opening brace when inserting a construct which requires +curly braces. Then insert some blank lines between your braces and +begin inserting statements. Your braces, and your attitude, will never +become unbalanced. + +Unbalanced braces can often lead to cryptic, impenetrable compiler +errors that can sometimes be hard to track down in a large program. +Because of their varied usages, braces are also incredibly important +to the syntax of a program and moving a brace one or two lines will +usually dramatically affect the meaning of a program. + +The main uses of curly braces +----------------------------- + +**Functions**:: + + // a function body needs braces around it + void myFunction(datatype argument) { + // ... function body goes in here ... + } + +**Loops** (see the :ref:`while `\ , :ref:`for +`\ , and :ref:`do/while ` loop reference +pages for more information):: + + // you should put braces around the body of a loop: + + while (boolean expression) { + // code inside the loop goes here + } + + for (initialisation; termination condition; incrementing expr) { + // code inside the loop goes here + } + + do { + // code inside the loop goes here + } while (boolean expression); + + +**Conditional statements** (see the :ref:`if statement ` +reference page for more information):: + + // you should put braces around the body of an "if", "else if", + // or "else": + + if (boolean expression) { + // code inside the "if" + } + else if (boolean expression) { + // code inside the "else if" + } + else { + // code inside the "else" + } + +**Switch statements** (see the :ref:`switch statement +` reference page for more information):: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + +.. rubric:: Footnotes + +.. TODO remove this once IDE 0.1.0 released + +.. [#fbug] At present this feature is slightly buggy as the IDE will + often find (incorrectly) a brace in text that has been commented + out. + + +.. include:: cc-attribution.txt diff --git a/source/lang/define.rst b/source/lang/define.rst index 30738ec..677390d 100644 --- a/source/lang/define.rst +++ b/source/lang/define.rst @@ -2,8 +2,8 @@ .. _lang-define: -#define -======= +``#define`` +=========== ``#define`` is a useful C and C++ feature that allows the programmer to give a name to a constant value before the program is compiled. diff --git a/source/lang/digitalread.rst b/source/lang/digitalread.rst index 71583ca..3502587 100644 --- a/source/lang/digitalread.rst +++ b/source/lang/digitalread.rst @@ -5,9 +5,6 @@ digitalRead() ============= -Description ------------ - Reads the value from a specified digital pin, either :ref:`HIGH ` or :ref:`LOW `. diff --git a/source/lang/digitalwrite.rst b/source/lang/digitalwrite.rst index 419ef3a..6124d5f 100644 --- a/source/lang/digitalwrite.rst +++ b/source/lang/digitalwrite.rst @@ -1,116 +1,68 @@ +.. highlight:: cpp + .. _lang-digitalwrite: digitalWrite() ============== -Description ------------ - -Write a `HIGH `_ or a -`LOW `_ value to a -digital pin. - - - -If the pin has been configured as an OUTPUT with -`pinMode `_\ (), its voltage -will be set to the corresponding value: 5V (or 3.3V on 3.3V boards) -for HIGH, 0V (ground) for LOW. - - - -If the pin is configured as an INPUT, writing a HIGH value with -digitalWrite() will enable an internal 20K pullup resistor (see the -`tutorial on digital pins `_). -Writing LOW will disable the pullup. The pullup resistor is enough -to light an LED dimly, so if LEDs appear to work, but very dimly, -this is a likely cause. The remedy is to set the pin to an output -with the pinMode() function. - +Write a :ref:`HIGH ` or a :ref:`LOW +` value to a pin configured as :ref:`OUTPUT +`. +Library Documentation +--------------------- -**NOTE:** Digital pin 13 is harder to use as a digital input than -the other digital pins because it has an LED and resistor attached -to it that's soldered to the board on most boards. If you enable -its internal 20k pull-up resistor, it will hang at around 1.7 V -instead of the expected 5V because the onboard LED and series -resistor pull the voltage level down, meaning it always returns -LOW. If you must use pin 13 as a digital input, use an external -pull down resistor. +.. doxygenfunction:: digitalWrite - - -Syntax ------- - -digitalWrite(pin, value) - - - -Parameters +Discussion ---------- -pin: the pin number - +If the pin has been configured as an ``OUTPUT`` with :ref:`pinMode() +` its voltage will be set to the corresponding value: +3.3V for ``HIGH``, and 0V (ground) for ``LOW``. +.. TODO make the following paragraphs true, but refer the reader to +.. INPUT_PULLUP and INPUT_PULLDOWN: -value: `HIGH `_ or -`LOW `_ - - - -Returns -------- - -none - +If the pin is configured as an ``INPUT``, writing a ``HIGH`` value +with ``digitalWrite()`` will enable an internal pullup resistor. +Writing ``LOW`` will disable the pullup. The pullup resistor is enough +to light an LED dimly, so if LEDs appear to work, but very dimly, this +is a likely cause. The remedy is to set the pin to an output with the +:ref:`pinMode() ` function. +.. note:: Pin 13 is harder to use as an input than the other pins + because it has an LED and resistor soldered to it in series. If you + enable its internal pull-up resistor, it will likely hang at around + 1.1V instead of the expected 3.3V because the onboard LED and + series resistor pull the voltage level down. If you must use pin 13 + as a digital input, use an external pull-down resistor. Example ------- -:: +The following example sets pin 13 to ``HIGH``, makes a one-second-long +delay, sets the pin back to ``LOW``, and delays again, causing a +blinking pattern:: int ledPin = 13; // LED connected to digital pin 13 - void setup() - { + void setup() { pinMode(ledPin, OUTPUT); // sets the digital pin as output } - void loop() - { + void loop() { digitalWrite(ledPin, HIGH); // sets the LED on delay(1000); // waits for a second digitalWrite(ledPin, LOW); // sets the LED off delay(1000); // waits for a second } - - -Sets pin 13 to HIGH, makes a one-second-long delay, and sets the -pin back to LOW. - - - -Note ----- - -The analog input pins can be used as digital pins, referred to as -A0, A1, etc. - - - -See also +See Also -------- - -- `pinMode `_\ () -- `digitalRead `_\ () -- `Tutorial: Digital Pins `_ - - - +- :ref:`pinMode ` +- :ref:`digitalRead ` .. include:: cc-attribution.txt diff --git a/source/lang/double.rst b/source/lang/double.rst index b4a1219..1527778 100644 --- a/source/lang/double.rst +++ b/source/lang/double.rst @@ -1,13 +1,10 @@ .. _lang-double: -double -====== +``double`` +========== -Description ------------ - -Double precision floating point number. Occupies 8 bytes. On Maple, -the ``double`` type has a range of approximately -1.79769×10^308 to +Double precision floating point type. Occupies 8 bytes. On Maple, the +``double`` type has a range of approximately -1.79769×10^308 to 1.79769×10^308; the ``double`` type subject to the same :ref:`overflow issues ` as any numeric data type. diff --git a/source/lang/doublecast.rst b/source/lang/doublecast.rst index 4ea1776..511fe24 100644 --- a/source/lang/doublecast.rst +++ b/source/lang/doublecast.rst @@ -2,11 +2,8 @@ .. _lang-doublecast: -double() (cast) -=============== - -Description ------------ +``double()`` (cast) +=================== Converts a value to the :ref:`double ` floating point data type. Here is an example:: diff --git a/source/lang/dowhile.rst b/source/lang/dowhile.rst index 77e02a3..fe92226 100644 --- a/source/lang/dowhile.rst +++ b/source/lang/dowhile.rst @@ -2,8 +2,8 @@ .. _lang-dowhile: -do/while Loop -============= +``do``/``while`` +================ A ``do`` loop works in the same manner as a :ref:`while ` loop, with the exception that the condition is tested diff --git a/source/lang/else.rst b/source/lang/else.rst deleted file mode 100644 index 863f21b..0000000 --- a/source/lang/else.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. highlight:: cpp - -.. _lang-else: - -if/else -======= - -``if``/\ ``else`` allows greater control over the flow of code than -the basic :ref:`if ` statement, by allowing multiple tests -to be grouped together. For example, an :ref:`analog input -` could be tested, with one action taken if the -input was less than 500, and another action taken if the input was 500 -or greater. The code would look like this:: - - if (pinFiveInput < 500) { - // action A - } else { - // action B - } - -``else`` can precede another ``if`` test, so that multiple, mutually -exclusive tests can be run at the same time. - -Each test will proceed to the next one until a true test is -encountered. When a true test is found, its associated block of code -is run, and the program then skips to the line following the entire -if/else construction. If no test proves to be true, the default -``else`` block is executed, if one is present, and sets the default -behavior. - - -Note that an ``else if`` block may be used with or without a -terminating ``else`` block, and vice-versa. An unlimited number of -such ``else if`` branches is allowed. Here is a code example:: - - if (pinFiveInput < 500) { - // do Thing A - } else if (pinFiveInput >= 1000) { - // do Thing B - } else { - // do Thing C - } - -Another way to express branching, mutually exclusive tests, is with a -:ref:`switch/case ` statement. - -See Also --------- - -- :ref:`if ` -- :ref:`switch/case ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/enum.rst b/source/lang/enum.rst index 5ecd99c..ba82383 100644 --- a/source/lang/enum.rst +++ b/source/lang/enum.rst @@ -1,8 +1,53 @@ +.. highlight:: cpp + .. _lang-enum: -enum -==== +``enum`` +======== + +The ``enum`` keyword is used to specify an enumeration type. An +enumeration type is a type whose values are taken from a specified, +fixed list of constant values. + +Example +------- + +Here's an example defining an enumeration type called ``weather``, +which has values ``HOT``, ``COMFY``, and ``COLD``:: + + enum weather {HOT, COMFY, COLD}; + +Once you've defined this type, you can create variables of type +``weather``, in the same way you would with an :ref:`int ` +or a :ref:`long `:: + + // create a weather variable named theWeather, with value COMFY: + weather theWeather = COMFY; + +Enumeration types are useful within :ref:`switch statements +`. If you know that an argument is of an enumeration +type, you can make ``case`` statements for all of that type's possible +values, so you know you won't miss anything:: + + void describeWeather(weather currentWeather) { + switch(currentWeather) { + case HOT: + SerialUSB.println("it's hot out"); + break; + case COMFY: + SerialUSB.println("it's nice today"); + break; + case COLD: + SerialUSB.println("it's freezing!"); + break; + } + } + +Such a ``switch`` statement would need no :ref:`default +`, since we know that ``currentWeather`` must +be either ``HOT``, ``COMFY``, or ``COLD``. -Stub. +See Also +-------- -Reference this from language.rst +- :ref:`lang-switchcase` diff --git a/source/lang/float.rst b/source/lang/float.rst index ef1a339..6937c8c 100644 --- a/source/lang/float.rst +++ b/source/lang/float.rst @@ -2,11 +2,8 @@ .. _lang-float: -float -===== - -Description ------------ +``float`` +========= Single-precision floating point number. Occupies 4 bytes. On Maple, the ``float`` type has a range of approximately -3.40282×10^38 to diff --git a/source/lang/floatcast.rst b/source/lang/floatcast.rst index 7476188..4766478 100644 --- a/source/lang/floatcast.rst +++ b/source/lang/floatcast.rst @@ -2,15 +2,12 @@ .. _lang-floatcast: -float() (cast) -============== +``float()`` (cast) +================== -Description ------------ - -Converts a value to the :ref:`float ` data type. Here -is an example (see the :ref:`constants reference -` for an explanation of the "2.0f"):: +Converts a value to the :ref:`float ` data type. Here is +an example (see the :ref:`constants reference ` for +an explanation of the "2.0f"):: int x = 2; float f = float(x); // f now holds 2.0f, a float value diff --git a/source/lang/for.rst b/source/lang/for.rst index 6b00d7a..71c5aca 100644 --- a/source/lang/for.rst +++ b/source/lang/for.rst @@ -2,14 +2,8 @@ .. _lang-for: -for Loops -========= - -.. contents:: Contents - :local: - -Description ------------ +``for`` +======= A ``for`` loop is used to repeat a block of statements enclosed in curly braces. ``for`` loops are useful for performing repetitive @@ -19,6 +13,12 @@ operations, and are often used in combination with :ref:`arrays *header*, which sets up the for loop, and then a *body*, which is made up of lines of code enclosed in curly braces. +.. contents:: Contents + :local: + +Syntax +------ + There are three parts to the ``for`` loop header: an *initialization* expression, *loop condition* expression, and a *post-loop* expression. The general syntax looks like this:: diff --git a/source/lang/goto.rst b/source/lang/goto.rst index 96a6262..ff2f248 100644 --- a/source/lang/goto.rst +++ b/source/lang/goto.rst @@ -2,8 +2,8 @@ .. _lang-goto: -Labels and goto -=============== +Labels and ``goto`` +=================== A *label* gives a name to a line of code within a function. You can label a line by writing a name for it, then a colon (``:``), before diff --git a/source/lang/highbyte.rst b/source/lang/highbyte.rst index af0bfcd..50a1fa6 100644 --- a/source/lang/highbyte.rst +++ b/source/lang/highbyte.rst @@ -1,7 +1,11 @@ +.. highlight:: cpp + .. _lang-highbyte: -highByte(x) -=========== +highByte() +========== + +(Macro) Extracts the second lowest byte of an integral data type. .. warning:: This macro is provided for compatibility with Arduino only. It returns the second-least significant byte in an integral @@ -13,10 +17,12 @@ highByte(x) In short: we provide this so that existing Arduino code works as expected, but **strongly discourage its use** in new programs. -Description ------------ +Syntax +------ -(Macro) Extracts the second lowest byte of an integral data type. +:: + + highByte(x) Parameters ---------- diff --git a/source/lang/if.rst b/source/lang/if.rst index 02ba1e7..bef89e2 100644 --- a/source/lang/if.rst +++ b/source/lang/if.rst @@ -2,8 +2,8 @@ .. _lang-if: -if Statements -============= +``if``/``else`` +=============== An ``if`` statement is used to execute code when certain conditions are met. The general syntax for an ``if`` statement is:: @@ -15,8 +15,8 @@ are met. The general syntax for an ``if`` statement is:: An ``if`` statement first tests whether its *condition* is true (such as an input being above a certain number). If the condition is true, the ``if`` statement executes its *body*, which is made up of lines of -code inside :ref:`curly braces `. If the condition is -false, the body is not executed. Here's a more concrete example:: +code inside :ref:`curly braces `. If the condition +is false, the body is not executed. Here's a more concrete example:: if (someVariable > 50) { // do something here @@ -70,12 +70,52 @@ In the first example, since the body is enclosed in curly braces, both lines are included. In the second example, since the curly braces are missing, only the first line is in the ``if`` body. +``else`` +-------- + +``if``/\ ``else`` allows greater control over the flow of code than +the basic :ref:`if ` statement, by allowing multiple tests to +be grouped together. For example, an :ref:`analog input +` could be tested, with one action taken if the input +was less than 500, and another action taken if the input was 500 or +greater. The code would look like this:: + + if (pinFiveInput < 500) { + // action A + } else { + // action B + } + +``else`` can precede another ``if`` test, so that multiple, mutually +exclusive tests can be run at the same time. + +Each test will proceed to the next one until a true test is +encountered. When a true test is found, its associated block of code +is run, and the program then skips to the line following the entire +if/else construction. If no test proves to be true, the default +``else`` block is executed, if one is present, and sets the default +behavior. + +Note that an ``else if`` block may be used with or without a +terminating ``else`` block, and vice-versa. An unlimited number of +such ``else if`` branches is allowed. Here is a code example:: + + if (pinFiveInput < 500) { + // do Thing A + } else if (pinFiveInput >= 1000) { + // do Thing B + } else { + // do Thing C + } + +Another way to express branching, mutually exclusive tests, is with a +:ref:`switch/case ` statement. + + See Also -------- - :ref:`boolean operators ` - :ref:`comparison operators ` -- :ref:`else ` - .. include:: cc-attribution.txt diff --git a/source/lang/include.rst b/source/lang/include.rst index a8bc74c..74fe7af 100644 --- a/source/lang/include.rst +++ b/source/lang/include.rst @@ -2,8 +2,8 @@ .. _lang-include: -#include -======== +``#include`` +============ ``#include`` is used to include outside libraries in your sketch. This gives the programmer access to a large group of standard C @@ -15,7 +15,8 @@ Example This example (from the `Arduino LiquidCrystal Tutorial `_) includes a library -that is used to control :ref:`LCD displays `:: +that is used to control :ref:`LCD displays +`:: // include the library code: #include diff --git a/source/lang/increment.rst b/source/lang/increment.rst index 5536a0a..6dffa80 100644 --- a/source/lang/increment.rst +++ b/source/lang/increment.rst @@ -2,8 +2,8 @@ .. _lang-increment: -Increment (``++``) and Decrement (``--``) -========================================= +Increment and Decrement Operators (``++``, ``--``) +================================================== These operators increment (add one to) or decrement (subtract one from) a variable. If they come before the variable, they return its @@ -29,16 +29,9 @@ A more extended example:: // this line won't compile (notice the extra space): int y = x+ +; -Parameters ----------- - -**x**: an integer value (like an ``int``, ``long``, ``unsigned int``, -etc.). - -See also +See Also -------- -- :ref:`Compound arithmetic operators ` - +- :ref:`lang-compoundarithmetic` .. include:: cc-attribution.txt diff --git a/source/lang/int.rst b/source/lang/int.rst index ac2f16a..ca75f75 100644 --- a/source/lang/int.rst +++ b/source/lang/int.rst @@ -2,11 +2,8 @@ .. _lang-int: -int -=== - -Description ------------ +``int`` +======= The ``int`` data type represents integers. Integers are your primary data type for number storage, and store a 4 byte value. This yields a @@ -43,7 +40,7 @@ Integer Overflow ---------------- When ``int`` variables leave the range specified above, they -:ref:`roll over ` in the other direction. +:ref:`roll over ` in the other direction. Here are some examples:: int x; diff --git a/source/lang/intcast.rst b/source/lang/intcast.rst index 03c0c07..386fe14 100644 --- a/source/lang/intcast.rst +++ b/source/lang/intcast.rst @@ -2,11 +2,8 @@ .. _lang-intcast: -int() -===== - -Description ------------ +``int()`` (cast) +================ Converts a value to the :ref:`int ` data type. Here is an example:: diff --git a/source/lang/interrupts.rst b/source/lang/interrupts.rst deleted file mode 100644 index 5ca7041..0000000 --- a/source/lang/interrupts.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _lang-interrupts: - -interrupts() -============ - -Description ------------ - -Re-enables interrupts (after they've been disabled by -`noInterrupts `_\ ()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None - - - -Returns -------- - -None - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `noInterrupts `_\ () -- `attachInterrupt `_\ () -- `detachInterrupt `_\ () - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/keywords.rst b/source/lang/keywords.rst index 451701e..e4ebe99 100644 --- a/source/lang/keywords.rst +++ b/source/lang/keywords.rst @@ -3,9 +3,203 @@ Keywords ======== -Stub. +This page lists all of the C++ keywords, and either links to a +reference page explaining their use, or provides a brief description. -Include list of all C++ keywords, with links to internal documentation -as appropriate. +List of Keywords +---------------- -Reference this page from language.rst +The C++ keywords are: + +``and``, ``and_eq``, ``asm``, ``auto``, ``bitand``, ``bitor``, +``bool``, ``break``, ``case``, ``catch``, ``char``, ``class``, +``compl``, ``const``, ``const_cast``, ``continue``, ``default``, +``delete``, ``do``, ``double``, ``dynamic_cast``, ``else``, ``enum``, +``explicit``, ``export``, ``extern``, ``false``, ``float``, ``for``, +``friend``, ``goto``, ``if``, ``inline``, ``int``, ``long``, +``mutable``, ``namespace``, ``new``, ``not``, ``not_eq``, +``operator``, ``or``, ``or_eq``, ``private``, ``protected``, +``public``, ``register``, ``reinterpret_cast``, ``return``, ``short``, +``signed``, ``sizeof``, ``static``, ``static_cast``, ``struct``, +``switch``, ``template``, ``this``, ``throw``, ``true``, ``try``, +``typedef``, ``typeid``, ``typename``, ``union``, ``unsigned``, +``using``, ``virtual``, ``void``, ``volatile``, ``wchar_t``, +``while``, ``xor``, ``xor_eq`` + +Boolean Operator Synonyms +------------------------- + +- ``and`` is a synonym for :ref:`&& `. +- ``not`` is a synonym for :ref:`\! `. +- ``not_eq`` is a synonym for :ref:`\!= `. +- ``or`` is a synonym for :ref:`|| `. + +Bitwise Operator Synonyms +------------------------- + +- ``and_eq`` is a synonym for :ref:`&= `. +- ``bitand`` is a synonym for (bitwise) :ref:`& `. +- ``bitor`` is a synonym for :ref:`\| `. +- ``compl`` is a synonym for :ref:`~ `. +- ``or_eq`` is a synonym for :ref:`|= `. +- ``xor`` is a synonym for :ref:`^ `. +- ``xor_eq`` is a synonym for :ref:`^= `. + +Constants +--------- + +- ``true`` and ``false`` are the :ref:`boolean constants + `. + +Control Flow +------------ + +- ``break`` can exit out of a :ref:`switch statement + ` or a :ref:`for `, :ref:`do + `, or :ref:`while ` loop. + +- ``case`` defines alternatives in a :ref:`switch statement `. + +- ``continue`` will move control flow to the next iteration of the + enclosing :ref:`for `, :ref:`do `, or + :ref:`while ` loop. + +- ``default`` defines the default alternative in a :ref:`switch + statement `. + +- ``do`` introduces a :ref:`do ` loop. + +- ``else`` is used in :ref:`if statements `. + +- ``for`` introduces a :ref:`for ` loop. + +- ``goto`` :ref:`jumps ` to a label. + +- ``if`` introduces an :ref:`if statement `. + +- ``return`` :ref:`transfers flow to a function's caller `. + +- ``switch`` introduces a :ref:`switch statement `. + +- ``while`` introduces a :ref:`while ` loop. + +Types +----- + +The following keywords are used for built-in types. + +- :ref:`bool ` +- :ref:`lang-char` +- :ref:`lang-double` +- :ref:`lang-float` +- :ref:`lang-int` +- :ref:`lang-long` +- :ref:`short ` +- :ref:`void ` (not really a type, but used in the absence + of one) + +The following keywords are used to introduce new types. + +- :ref:`enum ` + +Qualifiers +---------- + +- :ref:`static ` can be used to declare persistent local + variables; it has other uses not documented here. + +- ``unsigned`` is used to specify an unsigned integral type. + Examples: :ref:`lang-unsignedint`, :ref:`lang-unsignedchar`, + :ref:`lang-unsignedlong`. + +- :ref:`volatile ` is useful when declaring variables + that may be modified by external interrupts. + +- :ref:`const ` is used to define constants. + +Other +----- + +These keywords are not described in the Maple documentation. For more +information, consult a C++ reference. + +- ``asm`` is used to insert literal assembly language. + +- ``auto`` is used to declare that a variable has automatic storage. + +- ``catch`` is used in exception handling. Note that the default + flags we pass to :ref:`GCC ` include ``-fno-exceptions``. + +- ``class`` is used to define classes. + +- ``const_cast`` is used in typecasting. + +- ``delete`` is used to free ``new``\ -allocated storage. Note that + dynamic memory allocation is not available by default on the Maple, + so you'll have to bring your own ``new`` and ``delete`` if you want + this. + +- ``dynamic_cast`` is used in typecasting. + +- ``explicit`` is used to declare constructors that can be called only + explicitly. + +- ``export`` declares a template definition accessible to other + compilation units. + +- ``extern`` can mark a declaration as a declaration and not a + definition, and also grant external linkage to a ``const`` or + ``typedef``. + +- ``friend`` is used to declare that certain functions have access to + a class's private variables. + +- ``inline`` is a compiler hint to inline a function. + +- ``mutable`` specifies that a member can be updated, even when a + member of a ``const`` object. + +- ``namespace`` declares a new namespace. + +- ``new`` dynamically allocates space for a value. Note that dynamic + memory allocation is not available by default on the Maple, so + you'll have to bring your own ``new`` and ``delete`` if you want + this. + +- ``operator`` is used to define type-specific operator overrides. + +- ``private`` declares a private class member. + +- ``protected`` declares a protected class member. + +- ``public`` declares a public class member. + +- ``register`` is a compiler hint to store a variable in a register. + +- ``reinterpret_cast`` is used in typecasting. + +- ``signed`` is the opposite of ``unsigned``. + +- ``static_cast`` is used in typecasting. + +- ``struct`` declares a new struct. + +- ``template`` introduces a template class, function, etc. + +- ``this`` is a pointer to the receiver object. + +- ``throw`` is used in exception handling. Note that the default + flags we pass to :ref:`GCC ` include ``-fno-exceptions``. + +- ``try`` is used in exception handling. Note that the default + flags we pass to :ref:`GCC ` include ``-fno-exceptions``. + +- ``typedef`` defines a type synonym. + +- ``union`` defines an untagged union. + +- ``using`` is a directive related to namespaces. + +- ``virtual`` declares a method which may be overridden. + +- ``wchar_t`` is the wide character type. diff --git a/source/lang/long.rst b/source/lang/long.rst index 8a19b2b..d8498c0 100644 --- a/source/lang/long.rst +++ b/source/lang/long.rst @@ -2,11 +2,8 @@ .. _lang-long: -long -==== - -Description ------------ +``long`` +======== The ``long`` data type stores extended size integer values. You can use a ``long`` when your values are too large to fit into an :ref:`int @@ -19,7 +16,7 @@ Way galaxy). The exact range of a ``long`` on the Maple is from ` as any numeric data type. Here's an example of declaring a long (see :ref:`integer constants -` for an explanation of the "L" at the end of the +` for an explanation of the "L" at the end of the number):: // Speed of light in nanometers per second (approximate). diff --git a/source/lang/longcast.rst b/source/lang/longcast.rst index 16d7582..2b92345 100644 --- a/source/lang/longcast.rst +++ b/source/lang/longcast.rst @@ -2,11 +2,8 @@ .. _lang-longcast: -long() -====== - -Description ------------ +``long()`` (cast) +================= Converts a value to the :ref:`long ` data type. Here is an example:: diff --git a/source/lang/lowbyte.rst b/source/lang/lowbyte.rst index f9fb711..58e622f 100644 --- a/source/lang/lowbyte.rst +++ b/source/lang/lowbyte.rst @@ -3,43 +3,23 @@ lowByte() ========= -Description ------------ - Extracts the low-order (rightmost) byte of a variable (e.g. a word). - - Syntax ------ lowByte(x) - - Parameters ---------- -x: a value of any type - - +**x**: a value of any type. However, if a non-integral type is used, +the results will be strange. Returns ------- -byte - - - -See also --------- - - -- `highByte `_\ () -- `word `_\ () - - - +The low byte's value (this will be between 0 and 255). .. include:: cc-attribution.txt diff --git a/source/lang/map.rst b/source/lang/map.rst index 40b12a8..79122b3 100644 --- a/source/lang/map.rst +++ b/source/lang/map.rst @@ -1,122 +1,68 @@ -.. _lang-map: - -map(value, fromLow, fromHigh, toLow, toHigh) -============================================ - -Description ------------ - -Re-maps a number from one range to another. That is, a **value** of -**fromLow** would get mapped to **toLow**, a value of **fromHigh** -to **toHigh**, values in-between to values in-between, etc. - +.. highlight:: cpp +.. _lang-map: -Does not constrain values to within the range, because out-of-range -values are sometimes intended and useful. The constrain() function -may be used either before or after this function, if limits to the -ranges are desired. +map() +===== +Re-maps a number from one range to another. +.. contents:: Contents + :local: -Note that the "lower bounds" of either range may be larger or -smaller than the "upper bounds" so the map() function may be used -to reverse a range of numbers, for example +Library Documentation +--------------------- +.. doxygenfunction:: map +Discussion +---------- -``y = map(x, 1, 50, 50, 1);`` +``map()`` does not constrain values to within the range, because +out-of-range values are sometimes intended and useful. The +:ref:`constrain() ` macro may be used either before or +after this function, if limits to the ranges are desired. +Note that the "lower bounds" of either range may be larger or smaller +than the "upper bounds" so that ``map()`` may be used to reverse a +range of numbers; for example:: + y = map(x, 1, 50, 50, 1); The function also handles negative numbers well, so that this -example - - - -``y = map(x, 1, 50, 50, -100);`` - - +example :: -is also valid and works well. + y = map(x, 1, 50, 50, -100); +is also valid. - -The map() function uses integer math so will not generate +The ``map()`` function uses integer math (its arguments and return +values all have type :ref:`long `), so it will not generate fractions, when the math might indicate that it should do so. -Fractional remainders are truncated, and are not rounded or -averaged. - - - -Parameters ----------- - -value: the number to map - - - -fromLow: the lower bound of the value's current range - - - -fromHigh: the upper bound of the value's current range - - - -toLow: the lower bound of the value's target range - - - -toHigh: the upper bound of the value's target range - - - -Returns -------- - -The mapped value. - - +Fractional remainders are truncated, and are not rounded or averaged. Example ------- :: - /* Map an analog value to 8 bits (0 to 255) */ - void setup() {} + /* Map an ADC reading (12 bits) to 16-bit PWM (0 to 65,535) */ - void loop() - { - int val = analogRead(0); - val = map(val, 0, 1023, 0, 255); - analogWrite(9, val); + void setup() { + pinMode(0, INPUT_ANALOG); + pinMode(9, PWM); } - - -Appendix -~~~~~~~~ - -For the mathematically inclined, here's the whole function - - - -:: - - long map(long x, long in_min, long in_max, long out_min, long out_max) - { - return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; + void loop() { + int val = analogRead(0); + val = map(val, 0, 4095, 0, 65535); + analogWrite(9, val); } - See Also -------- - -- `constrain `_\ () - +- :ref:`constrain() ` .. include:: cc-attribution.txt diff --git a/source/lang/max.rst b/source/lang/max.rst index 7dbf6a7..d38eebe 100644 --- a/source/lang/max.rst +++ b/source/lang/max.rst @@ -2,15 +2,17 @@ .. _lang-max: -max(x, y) -========= - -Description ------------ +max() +===== (Macro) Calculates the maximum of two numbers. +Syntax +------ + +:: + max(x, y) Parameters ---------- diff --git a/source/lang/micros.rst b/source/lang/micros.rst index 711c013..f12976b 100644 --- a/source/lang/micros.rst +++ b/source/lang/micros.rst @@ -1,69 +1,46 @@ +.. highlight:: cpp + .. _lang-micros: micros() ======== -Description ------------ - -Returns the number of microseconds since the Arduino board began -running the current program. This number will overflow (go back to -zero), after approximately 70 minutes. On 16 MHz Arduino boards -(e.g. Duemilanove and Nano), this function has a resolution of four -microseconds (i.e. the value returned is always a multiple of -four). On 8 MHz Arduino boards (e.g. the LilyPad), this function -has a resolution of eight microseconds. - - - -*Note*: there are 1,000 microseconds in a millisecond and 1,000,000 -microseconds in a second. +Returns the number of microseconds since the Maple board began running +the current program. This number will overflow (go back to zero), +after approximately 70 minutes. +.. note:: There are 1,000 microseconds in a millisecond, and 1,000,000 + microseconds in a second. +Library Documentation +--------------------- -Parameters ----------- - -None - - - -Returns -------- - -Number of microseconds since the program started (*unsigned long*) - - +.. doxygenfunction:: micros Example ------- :: - unsigned long time; + unsigned int time; - void setup(){ - Serial.begin(9600); + void setup() { } - void loop(){ - Serial.print("Time: "); + + void loop() { + SerialUSB.print("Time: "); time = micros(); - //prints time since program started - Serial.println(time); + // prints time since program started + SerialUSB.println(time); // wait a second so as not to send massive amounts of data delay(1000); } - - -See also +See Also -------- - -- `millis `_\ () -- `delay `_\ () -- `delayMicroseconds `_\ () - - +- :ref:`millis() ` +- :ref:`delay() ` +- :ref:`delayMicroseconds() ` .. include:: cc-attribution.txt diff --git a/source/lang/millis.rst b/source/lang/millis.rst index 6ebfff5..54e4507 100644 --- a/source/lang/millis.rst +++ b/source/lang/millis.rst @@ -1,70 +1,52 @@ +.. highlight:: cpp + .. _lang-millis: millis() ======== -Description ------------ - -Returns the number of milliseconds since the Arduino board began -running the current program. This number will overflow (go back to -zero), after approximately 50 days. - - - -Parameters ----------- - -None - - - -Returns -------- - -Number of milliseconds since the program started (*unsigned long*) +Returns the number of milliseconds since the Maple board began running +the current program. This number will overflow (go back to zero) after +approximately 50 days. +Library Documentation +--------------------- +.. doxygenfunction:: millis Example ------- -:: +The following time prints the value returned by ``millis()`` roughly +once per second:: - unsigned long time; + unsigned int time; - void setup(){ - Serial.begin(9600); + void setup() { } - void loop(){ - Serial.print("Time: "); + + void loop() { + SerialUSB.print("Time: "); time = millis(); - //prints time since program started + // prints time since program started Serial.println(time); + // wait a second so as not to send massive amounts of data delay(1000); } +Tip +--- +Since the return value for ``millis()`` is an :ref:`unsigned long +`, overflow errors may occur if you try to do math +with other data types, such as :ref:`ints `. -Tip: ----- - -Note that the parameter for millis is an unsigned long, errors may -be generated if a programmer tries to do math with other datatypes -such as ints. - - - -See also +See Also -------- - -- `micros `_\ () -- `delay `_\ () -- `delayMicroseconds `_\ () -- `Tutorial: Blink Without Delay `_ - - +- :ref:`micros ` +- :ref:`delay ` +- :ref:`delayMicroseconds ` .. include:: cc-attribution.txt diff --git a/source/lang/min.rst b/source/lang/min.rst index ffbf1ee..1245f6f 100644 --- a/source/lang/min.rst +++ b/source/lang/min.rst @@ -2,15 +2,17 @@ .. _lang-min: -min(x, y) -========= - -Description ------------ +min() +===== (Macro) Calculates the minimum of two numbers. +Syntax +------ + +:: + min(x,y) Parameters ---------- @@ -19,13 +21,11 @@ Parameters **y**: the second number; may be any number or numeric expression. - Returns ------- The smaller of the two numbers. - Example ------- diff --git a/source/lang/modulo.rst b/source/lang/modulo.rst index 9e0dabd..289fba0 100644 --- a/source/lang/modulo.rst +++ b/source/lang/modulo.rst @@ -2,11 +2,8 @@ .. _lang-modulo: -% (modulo) -========== - -Description ------------ +Modulo Operator (``%``) +======================= Calculates the `remainder `_ when one integer is divided by another. It is useful for keeping a @@ -17,9 +14,7 @@ Syntax :: - result = dividend % divisor - - + dividend % divisor Parameters ---------- @@ -67,11 +62,9 @@ The modulo operator does not work on floats. For that, you can use the C standard library function `fmod() `_. - See Also -------- - :ref:`Arithmetic ` - .. include:: cc-attribution.txt diff --git a/source/lang/nointerrupts.rst b/source/lang/nointerrupts.rst deleted file mode 100644 index 2043c91..0000000 --- a/source/lang/nointerrupts.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _lang-nointerrupts: - -noInterrupts() -============== - -Description ------------ - -Disables interrupts (you can re-enable them with interrupts()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None. - - - -Returns -------- - -None. - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `interrupts `_\ () - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/notone.rst b/source/lang/notone.rst deleted file mode 100644 index 22432e2..0000000 --- a/source/lang/notone.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _lang-notone: - -noTone() -======== - -Description ------------ - -Stops the generation of a square wave triggered by -`tone `_\ (). Has no effect if -no tone is being generated. - - - -**NOTE:** if you want to play different pitches on multiple pins, -you need to call noTone() on one pin before calling tone() on the -next pin. - - - -Syntax ------- - -noTone(pin) - - - -Parameters ----------- - -pin: the pin on which to stop generating the tone - - - -Returns -------- - -nothing - - - -See also --------- - - -- `tone `_ () - - - -.. include:: cc-attribution.txt diff --git a/source/lang/numeric-types.rst b/source/lang/numeric-types.rst new file mode 100644 index 0000000..9d2be48 --- /dev/null +++ b/source/lang/numeric-types.rst @@ -0,0 +1,79 @@ +.. _lang-numeric-types: + +Numeric types +============= + +This document serves as a reference for all of the built-in numeric +types which are available when programming in the IDE. Programmers +using the :ref:`command-line tools ` will have access +to these types as long as they have imported ``wirish.h``; several are +defined in in `libmaple_types.h +`_. + +.. _lang-numeric-types-integral: + +Integral types +-------------- + +.. cpp:type:: char + + 8-bit integer value. + +.. cpp:type:: short + + 16-bit integer value. + +.. cpp:type:: int + + 32-bit integer value. + +.. cpp:type:: long + + 64-bit integer value. + +.. cpp:type:: long long + + 64-bit integer value. + +.. cpp:type:: int8 + + Synonym for ``char``. + +.. cpp:type:: uint8 + + Synonym for ``unsigned char``. + +.. cpp:type:: int16 + + Synonym for ``short``. + +.. cpp:type:: uint16 + + Synonym for ``unsigned short``. + +.. cpp:type:: int32 + + Synonym for ``int``. + +.. cpp:type:: uint32 + + Synonym for ``unsigned int`` + +.. cpp:type:: int64 + + Synonym for ``long long`` + +.. cpp:type:: uint64 + + Synonym for ``unsigned long long``. + +Floating-Point Types +-------------------- + +.. cpp:type:: float + + 32-bit, IEEE 754 single-precision floating-point type. + +.. cpp:type:: double + + 64-bit, IEEE 754 double-precision floating-point type. diff --git a/source/lang/pinmode.rst b/source/lang/pinmode.rst index aed23d6..b9095da 100644 --- a/source/lang/pinmode.rst +++ b/source/lang/pinmode.rst @@ -18,50 +18,51 @@ Library Documentation Discussion ---------- -pinMode() is usually called within :ref:`lang-setup` in order to +``pinMode()`` is usually called within :ref:`lang-setup` in order to configure a pin for a certain usage (although it may be called anywhere). - Example ------- - :: - +:: int ledPin = 13; // LED connected to digital pin 13 - void setup() - { + void setup() { pinMode(ledPin, OUTPUT); // sets the digital pin as output } - void loop() - { + void loop() { digitalWrite(ledPin, HIGH); // sets the LED on delay(1000); // waits for a second digitalWrite(ledPin, LOW); // sets the LED off delay(1000); // waits for a second } - - Arduino Compatibility --------------------- -The libmaple implementation of pinMode() supports OUTPUT and INPUT -modes with a meaning identical to that of the Arduino function. +.. TODO check out Arduino vs. Maple static discilpline cutoffs to +.. ensure accuracy of following: + +The libmaple implementation of ``pinMode()`` supports the ``INPUT`` +and ``OUTPUT`` modes with semantics identical to that of the Arduino +function (however, be advised that the Maple, as a 3.3V device, will +only drive 3.3V to an ``OUTPUT`` pin that has been set ``HIGH``). + +``INPUT_ANALOG`` and ``PWM`` modes were added because the Maple does +not distinguish between analog and digital pins the same way the +Arduino does. Unlike the Arduino, you **must call** ``pinMode()`` to +set up a pin for these purposes before a call to, e.g., +:ref:`lang-analogRead`. In practice, this should only add a few lines +to your :ref:`lang-setup` function. -INPUT_ANALOG and PWM modes were added because the Maple does not -distinguish between analog and digital pins the same way the Arduino -does. Unlike the Arduino, you **must call pinMode**\ () to set up a pin -for these purposes before a call to, e.g., :ref:`lang-analogRead`. -In practice, this should only add a few lines of pinMode() calls to -your :ref:`lang-setup` function. +.. TODO verify following before putting it in: -OUTPUT_OPEN_DRAIN, INPUT_PULLUP, INPUT_PULLDOWN, and PWM_OPEN_DRAIN -modes represent functionality not currently available on Arduino -boards. +.. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and +.. ``PWM_OPEN_DRAIN`` modes represent functionality not currently +.. available on Arduino boards. See also -------- diff --git a/source/lang/pointer.rst b/source/lang/pointer.rst index bc48d7d..0a42270 100644 --- a/source/lang/pointer.rst +++ b/source/lang/pointer.rst @@ -1,15 +1,19 @@ .. _lang-pointer: -The pointer operators: & (reference) and \* (dereference) -========================================================= +Pointer Operators (``&``, ``*``) +================================ +The pointer operators ``&`` (reference) and ``*`` (dereference) are +different from the bitwise math operator :ref:`& +` and the arithmetic operator :ref:`* +`. Pointers are one of the more complicated subjects for beginners in -learning C, and it is possible to write the vast majority of -Arduino sketches without ever encountering pointers. However for -manipulating certain data structures, the use of pointers can -simplify the code, and and knowledge of manipulating pointers is -handy to have in one's toolkit. +learning C, and it is possible to write many useful Arduino sketches +without ever encountering pointers. However, for manipulating certain +data structures, the use of pointers can simplify the code, improve +its efficiency, and generally provide many benefits that would be +difficult to achieve without the use of pointers. Introducing pointers is somewhat outside the scope of this documentation. However, a good `pointer tutorial @@ -20,9 +24,8 @@ the section on `pointers in C `_. See Also -======== +-------- - http://xkcd.com/138/ - .. include:: cc-attribution.txt diff --git a/source/lang/pow.rst b/source/lang/pow.rst index dbe89b6..4280400 100644 --- a/source/lang/pow.rst +++ b/source/lang/pow.rst @@ -1,7 +1,7 @@ .. _lang-pow: -pow(base, exponent) -=================== +pow() +===== Calculates the value of a number raised to a power. @@ -10,13 +10,7 @@ Library Documentation .. doxygenfunction:: pow -Example -------- - -``pow()`` can be used to raise a number to a fractional power. This -is useful for e.g. generating exponential mapping of values or -curves. See the `fscale `_ -function in the Arduino playground for more on this. +.. TODO LATER some examples See Also -------- diff --git a/source/lang/pulsein.rst b/source/lang/pulsein.rst deleted file mode 100644 index 7bbe84c..0000000 --- a/source/lang/pulsein.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _lang-pulsein: - -pulseIn() -========= - -Description ------------ - -Reads a pulse (either HIGH or LOW) on a pin. For example, if -**value** is **HIGH**, **pulseIn()** waits for the pin to go -**HIGH**, starts timing, then waits for the pin to go **LOW** and -stops timing. Returns the length of the pulse in microseconds. -Gives up and returns 0 if no pulse starts within a specified time -out. - - - -The timing of this function has been determined empirically and -will probably show errors in longer pulses. Works on pulses from 10 -microseconds to 3 minutes in length. - - - -Syntax ------- - -pulseIn(pin, value) -pulseIn(pin, value, timeout) - - - -Parameters ----------- - -pin: the number of the pin on which you want to read the pulse. -(*int*) - - - -value: type of pulse to read: either -`HIGH `_ or -`LOW `_. (*int*) - - - -timeout (optional): the number of microseconds to wait for the -pulse to start; default is one second (*unsigned long*) - - - -Returns -------- - -the length of the pulse (in microseconds) or 0 if no pulse started -before the timeout (*unsigned long*) - - - -Example -------- - -:: - - - - int pin = 7; - unsigned long duration; - - void setup() - { - pinMode(pin, INPUT); - } - - void loop() - { - duration = pulseIn(pin, HIGH); - } - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/pwmwrite.rst b/source/lang/pwmwrite.rst index acc0240..7a1d51f 100644 --- a/source/lang/pwmwrite.rst +++ b/source/lang/pwmwrite.rst @@ -23,9 +23,7 @@ Example ------- Sets the output to the LED proportional to the value read from the -potentiometer (adapted for Maple from the Arduino `analogWrite() -reference `_):: - +potentiometer:: int ledPin = 13; // LED connected to pin 13 (Maple) int analogPin = 3; // potentiometer connected to analog pin 3 diff --git a/source/lang/random.rst b/source/lang/random.rst index 51bee67..f2a9762 100644 --- a/source/lang/random.rst +++ b/source/lang/random.rst @@ -1,95 +1,73 @@ +.. highlight:: cpp + .. _lang-random: random() ======== -Description ------------ - -The random function generates pseudo-random numbers. - - - -Syntax ------- - -random(max) -random(min, max) - - - -Parameters ----------- - -min - lower bound of the random value, inclusive *(optional)* - +The ``random()`` function generates pseudo-random numbers. +.. TODO keep tracking Sphinx/Breathe's ability to reference overloaded +.. functions so we can use doxygenfunction instead of manually +.. documenting this. -max - upper bound of the random value, exclusive +Library Documentation +--------------------- +.. cpp:function:: random(long max) + Same as a call to ``random(0, max)``. -Returns -------- - -a random number between min and max-1 (*long*) +.. cpp:function:: random(long min, long max) + Generate a pseudo-random number with given lower and upper bounds. + *Parameters* -Note: ------ + - ``min`` - Lower bound on the returned value, inclusive + - ``max`` - Upper bound on the returned value, exclusive -If it is important for a sequence of values generated by random() -to differ, on subsequent executions of a sketch, use randomSeed() -to initialize the random number generator with a fairly random -input, such as analogRead() on an unconnected pin. + *Returns*: A pseudo-random number in the range [min, max). +Discussion +---------- +If it is important for a sequence of values generated by +:ref:`random() ` to differ, on subsequent executions of a +sketch, use :ref:`randomSeed() ` to initialize the +random number generator with a fairly random input, such as +:ref:`analogRead() ` on an unconnected pin. -Conversely, it can occasionally be useful to use pseudo-random +Conversely, it can occasionally be useful to use pseudorandom sequences that repeat exactly. This can be accomplished by calling -randomSeed() with a fixed number, before starting the random +``randomSeed()`` with a fixed number, before starting the random sequence. - - Example ------- -:: +The following sketch initializes the random seed based on an :ref:`ADC +` reading of pin 0. If this pin is unconnected, the Sketch +should print different values to the :ref:`serial monitor +` each time it is run:: long randNumber; - void setup(){ - Serial.begin(9600); - - // if analog input pin 0 is unconnected, random analog - // noise will cause the call to randomSeed() to generate - // different seed numbers each time the sketch runs. - // randomSeed() will then shuffle the random function. + void setup() { + pinMode(0, INPUT_ANALOG); randomSeed(analogRead(0)); } void loop() { - // print a random number from 0 to 299 randNumber = random(300); - Serial.println(randNumber); - - // print a random number from 10 to 19 - randNumber = random(10, 20); - Serial.println(randNumber); + SerialUSB.println(randNumber); delay(50); } - - -See also +See Also -------- - -- `randomSeed `_\ () - - +- :ref:`randomSeed() ` .. include:: cc-attribution.txt diff --git a/source/lang/randomseed.rst b/source/lang/randomseed.rst index 3dcf4db..d0a15b7 100644 --- a/source/lang/randomseed.rst +++ b/source/lang/randomseed.rst @@ -1,73 +1,60 @@ -.. _lang-randomseed: +.. highlight:: cpp -randomSeed(seed) -================ +.. _lang-randomseed: -Description ------------ +randomSeed() +============ -randomSeed() initializes the pseudo-random number generator, +``randomSeed()`` initializes the `pseudorandom number generator +`_, causing it to start at an arbitrary point in its random sequence. This sequence, while very long, and random, is always the same. +Library Documentation +--------------------- -If it is important for a sequence of values generated by random() -to differ, on subsequent executions of a sketch, use randomSeed() -to initialize the random number generator with a fairly random -input, such as analogRead() on an unconnected pin. +.. doxygenfunction:: randomSeed +Discussion +---------- +If it is important for a sequence of values generated by +:ref:`random() ` to differ, on subsequent executions of a +sketch, use ``randomSeed()`` to initialize the random number generator +with a fairly random input, such as :ref:`analogRead() +` on an unconnected pin. -Conversely, it can occasionally be useful to use pseudo-random +Conversely, it can occasionally be useful to use pseudorandom sequences that repeat exactly. This can be accomplished by calling -randomSeed() with a fixed number, before starting the random +``randomSeed()`` with a fixed number, before starting the random sequence. - - -Parameters ----------- - -long, int - pass a number to generate the seed. - - - -Returns -------- - -no returns - - - Example ------- -:: +The following sketch initializes the random seed based on an :ref:`ADC +` reading of pin 0. If this pin is unconnected, the Sketch +should print different values to the :ref:`serial monitor +` each time it is run:: long randNumber; - void setup(){ - Serial.begin(9600); + void setup() { + pinMode(0, INPUT_ANALOG); randomSeed(analogRead(0)); } - void loop(){ + void loop() { randNumber = random(300); - Serial.println(randNumber); + SerialUSB.println(randNumber); delay(50); } - - -See also +See Also -------- - -- `random `_ - - - +- :ref:`random() ` .. include:: cc-attribution.txt diff --git a/source/lang/return.rst b/source/lang/return.rst index e1b2924..7b5039e 100644 --- a/source/lang/return.rst +++ b/source/lang/return.rst @@ -2,11 +2,11 @@ .. _lang-return: -return -====== +``return`` +========== -(Keyword) Terminates a function and return a value from a function to -the calling function, if the function has non-``void`` return type. +Terminates a function and return a value from a function to the +calling function, if the function has non-``void`` return type. Syntax: ------- diff --git a/source/lang/scope.rst b/source/lang/scope.rst index 8e8bb13..7b65bab 100644 --- a/source/lang/scope.rst +++ b/source/lang/scope.rst @@ -2,8 +2,8 @@ .. _lang-scope: -Variable Scope -============== +Scope +===== Variables in the C++ programming language, which Maple uses (all of your sketches are C++ programs in disguise), have a property called @@ -25,8 +25,8 @@ of a function (like :ref:`setup() ` and :ref:`loop() A local variable can only be "seen" inside of a particular function. You can declare a variable to be local to a function by declaring it -inside of the :ref:`curly braces ` which enclose that -function. +inside of the :ref:`curly braces ` which enclose +that function. When programs start to get larger and more complex, local variables are a useful way to ensure that a function has exclusive access to its diff --git a/source/lang/semicolon.rst b/source/lang/semicolon.rst index 4cf7b9f..8164616 100644 --- a/source/lang/semicolon.rst +++ b/source/lang/semicolon.rst @@ -2,8 +2,8 @@ .. _lang-semicolon: -Semicolon (;) -============= +Semicolon (``;``) +================= Used to end a line of code. Example:: diff --git a/source/lang/serial.rst b/source/lang/serial.rst index 743f921..f96547d 100644 --- a/source/lang/serial.rst +++ b/source/lang/serial.rst @@ -1,68 +1,219 @@ .. _lang-serial: -Serial -====== +Serial Ports (``Serial1``, ``Serial2``, ``Serial3``) +==================================================== -Used for communication between the Arduino board and a computer or -other devices. All Arduino boards have at least one serial port -(also known as a UART or USART): **Serial**. It communicates on -digital pins 0 (RX) and 1 (TX) as well as with the computer via -USB. Thus, if you use these functions, you cannot also use pins 0 -and 1 for digital input or output. +Used for communication between the Maple board and a computer or other +devices. +.. contents:: Contents + :local: +Introduction +------------ -You can use the Arduino environment's built-in serial monitor to -communicate with an Arduino board. Click the serial monitor button -in the toolbar and select the same baud rate used in the call to -begin(). +The Maple has three serial ports (also known as a UARTs or USARTs): +``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the +pins summarized in the following table: +.. list-table:: + :header-rows: 1 + * - Serial port + - Pins (TX, RX) -The Arduino Mega has three additional serial ports: **Serial1** on -pins 19 (RX) and 18 (TX), **Serial2** on pins 17 (RX) and 16 (TX), -**Serial3** on pins 15 (RX) and 14 (TX). To use these pins to -communicate with your personal computer, you will need an -additional USB-to-serial adaptor, as they are not connected to the -Mega's USB-to-serial adaptor. To use them to communicate with an -external TTL serial device, connect the TX pin to your device's RX -pin, the RX to your device's TX pin, and the ground of your Mega to -your device's ground. (Don't connect these pins directly to an -RS232 serial port; they operate at +/- 12V and can damage your -Arduino board.) + * - ``Serial1`` + - 7, 8 + * - ``Serial2`` + - 1, 0 + * - ``Serial3`` + - 29, 30 -Functions ---------- +Thus, if you use a particular serial port, you cannot also use its +communication pins for other purposes at the same time. +Unlike the Arduino, none of these serial ports is connected to the USB +port on the Maple board. Thus, to use these pins to communicate with +your personal computer, you will need an additional USB-to-serial +adaptor. -- `begin `_\ () -- `end `_\ () -- `available `_\ () -- `read `_\ () -- `flush `_\ () -- `print `_\ () +If you want to communicate with the Maple using the provided USB port, +use :ref:`SerialUSB ` instead. + +To use them to communicate with an external TTL serial device, connect +the TX pin to your device's RX pin, the RX to your device's TX pin, +and the ground of your Maple to your device's ground. + +.. warning:: Don't connect these pins directly to an RS232 serial + port; they operate at +/- 12V and can damage your board. + + +Library Documentation +--------------------- + +All of the ``Serial[1,2,3]`` objects are instances of the +``HardwareSerial`` class, which is documented in this section. (This +means that you can use any of these functions on any of ``Serial1``, +``Serial2``, and ``Serial3``). + +.. cpp:class:: HardwareSerial + + Serial port class. Predefined instances are Serial1, Serial2, and + Serial3. + +.. cpp:function:: HardwareSerial::begin(unsigned int baud) + + Set up a ``HardwareSerial`` object for communications. This method + must be called before attempting to use the ``HardwareSerial`` + object (typically, you call this in your :ref:`setup() + ` function). + +.. cpp:function:: HardwareSerial::end() + + Disables the USART associated with this object, allowing any + associated TX and RX pins to be used for other purposes. + +.. cpp:function:: unsigned int HardwareSerial::available() + + Returns the number of bytes available for reading. + +.. cpp:function:: unsigned char HardwareSerial::read() + + Returns the next available, unread character. If there are no + available characters (you can check this with :cpp:func:`available + `), the call will block until one + becomes available. + +.. cpp:function:: HardwareSerial::flush() + + Removes the contents of the Serial's associated USART RX FIFO. + That is, clears any buffered characters, so that the next character + read is guaranteed to be new. + +.. cpp:function:: HardwareSerial::print(unsigned char b) + + Print the given byte over the USART. + +.. cpp:function:: HardwareSerial::print(char c) + + Print the given character over the USART. 7-bit clean characters + are typically interpreted as ASCII text. + +.. cpp:function:: HardwareSerial::print(const char *str) + + Print the given null-terminated string over the USART. + +.. cpp:function:: HardwareSerial::print(int n) + + Print the argument's digits over the USART, in decimal format. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: HardwareSerial::print(unsigned int n) + + Print the argument's digits over the USART, in decimal format. + +.. cpp:function:: HardwareSerial::print(long n) + + Print the argument's digits over the USART, in decimal format. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: HardwareSerial::print(unsigned long n) + + Print the argument's digits over the USART, in decimal format. + +.. cpp:function:: HardwareSerial::print(long n, int base) + + Print the digits of ``n`` over the USART, in base ``base`` (which + may be between 2 and 16). The ``base`` value 2 corresponds to + binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative + values will be prefixed with a ``'-'`` character. + +.. cpp:function:: HardwareSerial::print(double n) + + Print ``n``, accurate to 2 digits after the decimal point. .. _lang-serial-println: -- `println `_\ () -- `write `_\ () +.. cpp:function:: HardwareSerial::println(char c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(const char *c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(unsigned char b) + + Like ``print(b)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(unsigned int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(unsigned long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(long n, int base) + + Like ``print(n, b)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(double n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println() + + Prints ``"\r\n"`` over the USART. + +.. cpp:function:: HardwareSerial::write(unsigned char ch) + + Sends one character over the USART. This function is currently + blocking, although nonblocking writes are a planned future + extension. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +.. cpp:function:: HardwareSerial::write(const char* str) + + Send the given null-terminated character string over the USART. + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. +.. cpp:function:: HardwareSerial::write(void *buf, unsigned int size) -Examples --------- + Writes the first ``size`` bytes of ``buf`` over the USART. Each + byte is transmitted as an individual character. + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. -- `ASCII Table `_ -- `Dimmer `_ -- `Graph `_ -- `Physical Pixel `_ -- `Virtual Color Mixer `_ -- `Serial Call Response `_ -- `Serial Call Response ASCII `_ +.. TODO LATER port these examples over +.. Examples +.. -------- +.. - `ASCII Table `_ +.. - `Dimmer `_ +.. - `Graph `_ +.. - `Physical Pixel `_ +.. - `Virtual Color Mixer `_ +.. - `Serial Call Response `_ +.. - `Serial Call Response ASCII `_ .. include:: cc-attribution.txt diff --git a/source/lang/serialusb.rst b/source/lang/serialusb.rst index 730fb07..9beee82 100644 --- a/source/lang/serialusb.rst +++ b/source/lang/serialusb.rst @@ -1,8 +1,240 @@ +.. highlight:: cpp + .. _lang-serialusb: -Serial over USB Communications -============================== +``SerialUSB`` +============= + +Used for communication between the Maple board and a computer. + +.. contents:: Contents + :local: + +Introduction +------------ + +In addition to three :ref:`serial ports `, the Maple's +STM32 microprocessor includes a dedicated USB peripheral. This +peripheral is used to emulate a regular serial port for use as a +terminal (text read/write). The emulated terminal is relatively slow +and inefficient; it is best for transferring data at regular serial +speeds (kilobaud). + +Library access to the emulated serial port is provided through the +``SerialUSB`` object. You can mostly use ``SerialUSB`` as a drop-in +replacement for ``Serial1``, ``Serial2``, and ``Serial3``. + +.. warning:: The ``SerialUSB`` functionality includes a 50 millisecond + timeout for writes, and does not try to detect if the USB host is + "really" connected, or just enumerated and initialized. + + This means that if you have a number of calls to one of the + ``SerialUSB`` ``write()`` or ``print()`` functions in your code, + and you are not monitoring the emulated on a computer, your program + will run much, much slower than if it is being monitored or totally + disconnected (run off of a battery). + + You can avoid this behavior by :ref:`deciphering the port status + using the DTR and RTS line status `; the + behavior of these control lines is platform dependent and we no + longer interpret them by default. + +Library Documentation +--------------------- + +The ``SerialUSB`` object is an instance of the ``USBSerial`` class, +which is documented in this section. This means that you can use any +of these functions by writing +``SerialUSB.functionName(arguments...)``. For example, to print the +message "hello, world!", you can write ``USBSerial.println("hello, +world!")``. + +.. cpp:class:: USBSerial + + Emulated serial-over-USB class. ``SerialUSB`` is the predefined + instance. + +.. cpp:function:: USBSerial::begin() + + Set up the USB peripheral for emulated serial communication. The + peripheral is configured this way by default; calling this function + should only be necessary if you have disabled the peripheral using + ``SerialUSB.end()``. + +.. _lang-serialusb-end: + +.. cpp:function:: USBSerial::end() + + Disables the USB peripheral. + +.. cpp:function:: unsigned int USBSerial::available() + + Returns the number of bytes available for reading. + +.. cpp:function:: unsigned char USBSerial::read() + + Returns the next available, unread character. If there are no + available characters (you can check this with :cpp:func:`available + `), the call will block until one + becomes available. + +.. cpp:function:: USBSerial::flush() + + Removes the contents of the Serial's associated input buffer. That + is, clears any buffered characters, so that the next character read + is guaranteed to be new. + +.. cpp:function:: USBSerial::print(unsigned char b) + + Print the given byte over the USB connection. + +.. cpp:function:: USBSerial::print(char c) + + Print the given character over the USB connection. 7-bit clean characters + are typically interpreted as ASCII text. + +.. cpp:function:: USBSerial::print(const char *str) + + Print the given null-terminated string over the USB connection. + +.. cpp:function:: USBSerial::print(int n) + + Print the argument's digits over the USB connection, in decimal format. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: USBSerial::print(unsigned int n) + + Print the argument's digits over the USB connection, in decimal format. + +.. cpp:function:: USBSerial::print(long n) + + Print the argument's digits over the USB connection, in decimal + format. Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: USBSerial::print(unsigned long n) + + Print the argument's digits over the USB connection, in decimal + format. + +.. cpp:function:: USBSerial::print(long n, int base) + + Print the digits of ``n`` over the USB connection, in base ``base`` + (which may be between 2 and 16). The ``base`` value 2 corresponds + to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: USBSerial::print(double n) + + Print ``n``, accurate to 2 digits after the decimal point. .. _lang-serialusb-println: -Stub. +.. cpp:function:: USBSerial::println(char c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(const char *c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(unsigned char b) + + Like ``print(b)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(unsigned int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(unsigned long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(long n, int base) + + Like ``print(n, b)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(double n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println() + + Prints ``"\r\n"`` over the USB connection. + +.. cpp:function:: USBSerial::write(unsigned char ch) + + Sends one character over the USB connection. This function is + currently blocking, although nonblocking writes are a planned + future extension. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +.. cpp:function:: USBSerial::write(const char* str) + + Send the given null-terminated character string over the USB + connection. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +.. cpp:function:: USBSerial::write(void *buf, unsigned int size) + + Writes the first ``size`` bytes of ``buf`` over the USB connection. + Each byte is transmitted as an individual character. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +Examples +-------- + +.. _lang-serialusb-safe-print: + +**Safe print**: This function should run smoothly and not block; the +LED should blink at roughly the same speed whether being monitored, +running from battery, or connected but not monitored. You may need to +experiment with the DTR/RTS logic for your platform and device +configuration. :: + + #define LED_PIN 13 + + void setup() { + /* Set up the LED to blink */ + pinMode(LED_PIN, OUTPUT); + } + + void loop() { + // LED will stay off if we are disconnected; + // will blink quickly if USB is unplugged (battery etc) + if(SerialUSB.isConnected()) { + digitalWrite(LED_PIN, 1); + } + delay(100); + + // If this logic fails to detect if bytes are going to + // be read by the USB host, then the println() will fully + // many times, causing a very slow LED blink. + // If the characters are printed and read, the blink will + // only slow a small amount when "really" connected, and fast + // when the virtual port is only configured. + if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) { + for(int i=0; i<10; i++) { + SerialUSB.println(123456,BIN); + } + } + digitalWrite(LED_PIN, 0); + delay(100); + } + diff --git a/source/lang/setup.rst b/source/lang/setup.rst index 6b142d2..837ddd6 100644 --- a/source/lang/setup.rst +++ b/source/lang/setup.rst @@ -1,34 +1,29 @@ +.. highlight:: cpp + .. _lang-setup: setup() ======= -The setup() function is called when a sketch starts. Use it to -initialize variables, pin modes, start using libraries, etc. The -setup function will only run once, after each powerup or reset of -the Arduino board. - - +The ``setup()`` function is called when a sketch starts. Use it to +initialize :ref:`variables `, :ref:`pin modes +`, start using :ref:`libraries `, etc. The +``setup()`` function will only run once, after each power-up or reset +of the Maple board. Example -~~~~~~~ +------- :: + int buttonPin = 38; - int buttonPin = 3; - - void setup() - { - Serial.begin(9600); + void setup() { pinMode(buttonPin, INPUT); } - void loop() - { + void loop() { // ... } - - .. include:: cc-attribution.txt diff --git a/source/lang/shiftout.rst b/source/lang/shiftout.rst deleted file mode 100644 index e76cc01..0000000 --- a/source/lang/shiftout.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. _lang-shiftout: - -shiftOut() -========== - -Description ------------ - -Shifts out a byte of data one bit at a time. Starts from either the -most (i.e. the leftmost) or least (rightmost) significant bit. Each -bit is written in turn to a data pin, after which a clock pin is -pulsed to indicate that the bit is available. - - - -This is a software implementation; Arduino (as of 0019) also -provides an `SPI library `_ -that uses the hardware implementation. - - - -Syntax ------- - -shiftOut(dataPin, clockPin, bitOrder, value) - - - -Parameters ----------- - -dataPin: the pin on which to output each bit (*int*) - - - -clockPin: the pin to toggle once the **dataPin** has been set to -the correct value (*int*) - - - -bitOrder: which order to shift out the bits; either **MSBFIRST** or -**LSBFIRST**. -(Most Significant Bit First, or, Least Significant Bit First) - - - -value: the data to shift out. (*byte*) - - - -Returns -------- - -None - - - -Note ----- - -The **dataPin** and **clockPin** must already be configured as -outputs by a call to -`pinMode `_\ (). - - - -**shiftOut** is currently written to output 1 byte (8 bits) so it -requires a two step operation to output values larger than 255. - -:: - - // Do this for MSBFIRST serial - int data = 500; - // shift out highbyte - shiftOut(dataPin, clock, MSBFIRST, (data >> 8)); - // shift out lowbyte - shiftOut(data, clock, MSBFIRST, data); - - // Or do this for LSBFIRST serial - data = 500; - // shift out lowbyte - shiftOut(dataPin, clock, LSBFIRST, data); - // shift out highbyte - shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); - - - -Example -------- - -*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register `_.* - - - -:: - - //**************************************************************// - // Name : shiftOutCode, Hello World // - // Author : Carlyn Maw,Tom Igoe // - // Date : 25 Oct, 2006 // - // Version : 1.0 // - // Notes : Code for using a 74HC595 Shift Register // - // : to count from 0 to 255 // - //**************************************************************** - - //Pin connected to ST_CP of 74HC595 - int latchPin = 8; - //Pin connected to SH_CP of 74HC595 - int clockPin = 12; - ////Pin connected to DS of 74HC595 - int dataPin = 11; - - void setup() { - //set pins to output because they are addressed in the main loop - pinMode(latchPin, OUTPUT); - pinMode(clockPin, OUTPUT); - pinMode(dataPin, OUTPUT); - } - - void loop() { - //count up routine - for (int j = 0; j < 256; j++) { - //ground latchPin and hold low for as long as you are transmitting - digitalWrite(latchPin, LOW); - shiftOut(dataPin, clockPin, LSBFIRST, j); - //return the latch pin high to signal chip that it - //no longer needs to listen for information - digitalWrite(latchPin, HIGH); - delay(1000); - } - } - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/sizeof.rst b/source/lang/sizeof.rst index 409a6d7..eae509c 100644 --- a/source/lang/sizeof.rst +++ b/source/lang/sizeof.rst @@ -2,8 +2,8 @@ .. _lang-sizeof: -sizeof() -======== +``sizeof()`` +============ The ``sizeof`` operator on the Maple returns the number of bytes needed to store a value of a given type\ [#fcharsize]_. This can be diff --git a/source/lang/sq.rst b/source/lang/sq.rst index a14817f..bd32648 100644 --- a/source/lang/sq.rst +++ b/source/lang/sq.rst @@ -2,14 +2,18 @@ .. _lang-sq: -sq(a) -===== - -Description ------------ +sq() +==== (Macro) computes the square of a number. +Syntax +------ + +:: + + sq(a) + Parameters ---------- diff --git a/source/lang/static.rst b/source/lang/static.rst index 4646db1..5d1802e 100644 --- a/source/lang/static.rst +++ b/source/lang/static.rst @@ -2,8 +2,8 @@ .. _lang-static: -Static -====== +``static`` +========== The ``static`` keyword can be used to create variables that are visible to only one function. However, unlike local variables that get diff --git a/source/lang/string.rst b/source/lang/string.rst index 92c3f69..0a270da 100644 --- a/source/lang/string.rst +++ b/source/lang/string.rst @@ -5,9 +5,6 @@ Strings ======= -Description ------------ - Text strings can be represented in two ways. You can 1. Use the :ref:`String ` data type, which is diff --git a/source/lang/stringclass.rst b/source/lang/stringclass.rst deleted file mode 100644 index 5e53f08..0000000 --- a/source/lang/stringclass.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _lang-stringclass: - -String Class -============ - -Stub. - - -.. include:: cc-attribution.txt diff --git a/source/lang/stringobject.rst b/source/lang/stringobject.rst deleted file mode 100644 index d7f287c..0000000 --- a/source/lang/stringobject.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _lang-stringobject: - -String -====== - -Description ------------ - -The String class, part of the core as of version 0019, allows you -to use and manipulate strings of text in more complex ways than -`character arrays `_ do. You -can concatenate Strings, append to them, search for and replace -substrings, and more. It takes more memory than a simple character -array, but it is also more useful. - - - -For reference, character arrays are referred to as strings with a -small s, and instances of the String class are referred to as -Strings with a capital S. Note that constant strings, specified in -"double quotes" are treated as char arrays, not instances of the -String class. - - - -Functions ---------- - - -- `String `_\ () -- `charAt `_\ () -- `compareTo `_\ () -- `concat `_\ () -- `endsWith `_\ () -- `equals `_\ () -- `equalsIgnoreCase `_\ () -- `getBytes `_\ () -- `indexOf `_\ () -- `lastIndexOf `_\ () -- `length `_\ () -- `replace `_\ () -- `setCharAt `_\ () -- `startsWith `_\ () -- `substring `_\ () -- `toCharArray `_\ () -- `toLowerCase `_\ () -- `toUpperCase `_\ () -- `trim `_\ () - - - -Operators ---------- - - -- `[] (element access) `_ -- `+ (concatenation) `_ -- `== (comparison) `_ - - - -Examples --------- - - -- `StringConstructors `_ -- `StringAdditionOperator `_ -- `StringIndexOf `_ -- `StringAppendOperator `_ -- `StringLengthTrim `_ -- `StringCaseChanges `_ -- `StringReplace `_ -- `StringCharacters `_ -- `StringStartsWithEndsWith `_ -- `StringComparisonOperators `_ -- `StringSubstring `_ - - - -See Also --------- - - -- `string `_: character - arrays -- `Variable Declaration `_ - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/switchcase.rst b/source/lang/switchcase.rst index 46c47d8..b484bc5 100644 --- a/source/lang/switchcase.rst +++ b/source/lang/switchcase.rst @@ -2,12 +2,12 @@ .. _lang-switchcase: -switch / case statements -======================== +``switch``\ /\ ``case`` +======================= -Like :ref:`if/else ` blocks, A ``switch`` statement -controls program flow by allowing you to specify different code that -should be executed under various cases. +Like :ref:`if ` statements, A ``switch`` statement controls +program flow by allowing you to specify different code that should be +executed under various cases. The general syntax looks like this:: @@ -27,7 +27,6 @@ Where ``var`` is a variable whose value to investigate, and the ``val1``, ``val2`` after each ``case`` are constant values that ``var`` might be. - Description ----------- @@ -80,6 +79,8 @@ a ``break`` has been reached, so the program continues by calling ``afterTheSwitch()``. This is usually not what you want, which is why each ``case`` usually has a ``break`` at the end. +.. _lang-switchcase-default: + Writing "``default:``" instead of a ``case`` statement allows you to specify what to do if none of the ``case`` statements matches. Having a ``default`` is optional (you can leave it out), but if you have one, @@ -104,14 +105,14 @@ two, ``doThing2()`` gets called. If ``var`` is anything else, optional. If you're missing one and none of the ``case`` statements match, the ``switch`` does nothing at all, as if it weren't there. -``switch`` statements are often used with an ``enum`` value as the -variable to compare. In this case, you can write down all of the -values the ``enum`` takes as ``case`` statements, and be sure you've -covered all the possibilities. +``switch`` statements are often used with an :ref:`enum ` +value as the variable to compare. In this case, you can write down +all of the values the ``enum`` takes as ``case`` statements, and be +sure you've covered all the possibilities. See also: --------- -- :ref:`if...else ` +- :ref:`if/else ` .. include:: cc-attribution.txt diff --git a/source/lang/tone.rst b/source/lang/tone.rst deleted file mode 100644 index 96f0a7c..0000000 --- a/source/lang/tone.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. _lang-tone: - -tone() -====== - -Description ------------ - -Generates a square wave of the specified frequency (and 50% duty -cycle) on a pin. A duration can be specified, otherwise the wave -continues until a call to -`noTone `_\ (). The pin can be -connected to a piezo buzzer or other speaker to play tones. - - - -Only one tone can be generated at a time. If a tone is already -playing on a different pin, the call to tone() will have no effect. -If the tone is playing on the same pin, the call will set its -frequency. - - - -Use of the tone() function will interfere with PWM output on pins 3 -and 11 (on boards other than the Mega). - - - -**NOTE:** if you want to play different pitches on multiple pins, -you need to call noTone() on one pin before calling tone() on the -next pin. - - - -Syntax ------- - -tone(pin, frequency) -tone(pin, frequency, duration) - - - -Parameters ----------- - -pin: the pin on which to generate the tone - - - -frequency: the frequency of the tone in hertz - - - -duration: the duration of the tone in milliseconds (optional) - - - -Returns -------- - -nothing - - - -See also --------- - - -- `noTone `_\ () -- `analogWrite `_\ () -- `Tutorial:Tone `_ -- `Tutorial:Pitch follower `_ -- `Tutorial:Simple Keyboard `_ -- `Tutorial: multiple tones `_ - - -- `Tutorial: PWM `_ - - - -.. include:: cc-attribution.txt diff --git a/source/lang/types.rst b/source/lang/types.rst deleted file mode 100644 index d095da1..0000000 --- a/source/lang/types.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _lang-types: - -Built-in types -============== - -Stub. (explain all built-in integral and floating-point types, -including ``uint8`` style ones). diff --git a/source/lang/unimplemented/interrupts.rst b/source/lang/unimplemented/interrupts.rst new file mode 100644 index 0000000..55b8e93 --- /dev/null +++ b/source/lang/unimplemented/interrupts.rst @@ -0,0 +1,59 @@ +.. _lang-interrupts: + +interrupts() +============ + +Re-enables interrupts (after they've been disabled by +`noInterrupts `_\ ()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None + + + +Returns +------- + +None + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `noInterrupts `_\ () +- `attachInterrupt `_\ () +- `detachInterrupt `_\ () + + + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/nointerrupts.rst b/source/lang/unimplemented/nointerrupts.rst new file mode 100644 index 0000000..fb2e5f9 --- /dev/null +++ b/source/lang/unimplemented/nointerrupts.rst @@ -0,0 +1,59 @@ +.. _lang-nointerrupts: + +noInterrupts() +============== + +Description +----------- + +Disables interrupts (you can re-enable them with interrupts()). +Interrupts allow certain important tasks to happen in the +background and are enabled by default. Some functions will not work +while interrupts are disabled, and incoming communication may be +ignored. Interrupts can slightly disrupt the timing of code, +however, and may be disabled for particularly critical sections of +code. + + + +Parameters +---------- + +None. + + + +Returns +------- + +None. + + + +Example +------- + +:: + + void setup() {} + + void loop() + { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + + + +See Also +-------- + + +- `interrupts `_\ () + + + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/notone.rst b/source/lang/unimplemented/notone.rst new file mode 100644 index 0000000..485c9c5 --- /dev/null +++ b/source/lang/unimplemented/notone.rst @@ -0,0 +1,50 @@ +.. _lang-notone: + +noTone() +======== + +Description +----------- + +Stops the generation of a square wave triggered by +`tone `_\ (). Has no effect if +no tone is being generated. + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +noTone(pin) + + + +Parameters +---------- + +pin: the pin on which to stop generating the tone + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `tone `_ () + + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/pulsein.rst b/source/lang/unimplemented/pulsein.rst new file mode 100644 index 0000000..2b52428 --- /dev/null +++ b/source/lang/unimplemented/pulsein.rst @@ -0,0 +1,82 @@ +.. _lang-pulsein: + +pulseIn() +========= + +Description +----------- + +Reads a pulse (either HIGH or LOW) on a pin. For example, if +**value** is **HIGH**, **pulseIn()** waits for the pin to go +**HIGH**, starts timing, then waits for the pin to go **LOW** and +stops timing. Returns the length of the pulse in microseconds. +Gives up and returns 0 if no pulse starts within a specified time +out. + + + +The timing of this function has been determined empirically and +will probably show errors in longer pulses. Works on pulses from 10 +microseconds to 3 minutes in length. + + + +Syntax +------ + +pulseIn(pin, value) +pulseIn(pin, value, timeout) + + + +Parameters +---------- + +pin: the number of the pin on which you want to read the pulse. +(*int*) + + + +value: type of pulse to read: either +`HIGH `_ or +`LOW `_. (*int*) + + + +timeout (optional): the number of microseconds to wait for the +pulse to start; default is one second (*unsigned long*) + + + +Returns +------- + +the length of the pulse (in microseconds) or 0 if no pulse started +before the timeout (*unsigned long*) + + + +Example +------- + +:: + + + + int pin = 7; + unsigned long duration; + + void setup() + { + pinMode(pin, INPUT); + } + + void loop() + { + duration = pulseIn(pin, HIGH); + } + + + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/shiftout.rst b/source/lang/unimplemented/shiftout.rst new file mode 100644 index 0000000..ff3852f --- /dev/null +++ b/source/lang/unimplemented/shiftout.rst @@ -0,0 +1,136 @@ +.. _lang-shiftout: + +shiftOut() +========== + +Description +----------- + +Shifts out a byte of data one bit at a time. Starts from either the +most (i.e. the leftmost) or least (rightmost) significant bit. Each +bit is written in turn to a data pin, after which a clock pin is +pulsed to indicate that the bit is available. + + + +This is a software implementation; Arduino (as of 0019) also +provides an `SPI library `_ +that uses the hardware implementation. + + + +Syntax +------ + +shiftOut(dataPin, clockPin, bitOrder, value) + + + +Parameters +---------- + +dataPin: the pin on which to output each bit (*int*) + + + +clockPin: the pin to toggle once the **dataPin** has been set to +the correct value (*int*) + + + +bitOrder: which order to shift out the bits; either **MSBFIRST** or +**LSBFIRST**. +(Most Significant Bit First, or, Least Significant Bit First) + + + +value: the data to shift out. (*byte*) + + + +Returns +------- + +None + + + +Note +---- + +The **dataPin** and **clockPin** must already be configured as +outputs by a call to +`pinMode `_\ (). + + + +**shiftOut** is currently written to output 1 byte (8 bits) so it +requires a two step operation to output values larger than 255. + +:: + + // Do this for MSBFIRST serial + int data = 500; + // shift out highbyte + shiftOut(dataPin, clock, MSBFIRST, (data >> 8)); + // shift out lowbyte + shiftOut(data, clock, MSBFIRST, data); + + // Or do this for LSBFIRST serial + data = 500; + // shift out lowbyte + shiftOut(dataPin, clock, LSBFIRST, data); + // shift out highbyte + shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); + + + +Example +------- + +*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register `_.* + + + +:: + + //**************************************************************// + // Name : shiftOutCode, Hello World // + // Author : Carlyn Maw,Tom Igoe // + // Date : 25 Oct, 2006 // + // Version : 1.0 // + // Notes : Code for using a 74HC595 Shift Register // + // : to count from 0 to 255 // + //**************************************************************** + + //Pin connected to ST_CP of 74HC595 + int latchPin = 8; + //Pin connected to SH_CP of 74HC595 + int clockPin = 12; + ////Pin connected to DS of 74HC595 + int dataPin = 11; + + void setup() { + //set pins to output because they are addressed in the main loop + pinMode(latchPin, OUTPUT); + pinMode(clockPin, OUTPUT); + pinMode(dataPin, OUTPUT); + } + + void loop() { + //count up routine + for (int j = 0; j < 256; j++) { + //ground latchPin and hold low for as long as you are transmitting + digitalWrite(latchPin, LOW); + shiftOut(dataPin, clockPin, LSBFIRST, j); + //return the latch pin high to signal chip that it + //no longer needs to listen for information + digitalWrite(latchPin, HIGH); + delay(1000); + } + } + + + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/stringclass.rst b/source/lang/unimplemented/stringclass.rst new file mode 100644 index 0000000..cdd385d --- /dev/null +++ b/source/lang/unimplemented/stringclass.rst @@ -0,0 +1,9 @@ +.. _lang-stringclass: + +String Class +============ + +Stub. + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/stringobject.rst b/source/lang/unimplemented/stringobject.rst new file mode 100644 index 0000000..e47ed7e --- /dev/null +++ b/source/lang/unimplemented/stringobject.rst @@ -0,0 +1,89 @@ +.. _lang-stringobject: + +String +====== + +Description +----------- + +The String class, part of the core as of version 0019, allows you to +use and manipulate strings of text in more complex ways than character +arrays do. You can concatenate Strings, append to them, search for and +replace substrings, and more. It takes more memory than a simple +character array, but it is also more useful. + + + +For reference, character arrays are referred to as strings with a +small s, and instances of the String class are referred to as +Strings with a capital S. Note that constant strings, specified in +"double quotes" are treated as char arrays, not instances of the +String class. + + + +Functions +--------- + + +- `String `_\ () +- `charAt `_\ () +- `compareTo `_\ () +- `concat `_\ () +- `endsWith `_\ () +- `equals `_\ () +- `equalsIgnoreCase `_\ () +- `getBytes `_\ () +- `indexOf `_\ () +- `lastIndexOf `_\ () +- `length `_\ () +- `replace `_\ () +- `setCharAt `_\ () +- `startsWith `_\ () +- `substring `_\ () +- `toCharArray `_\ () +- `toLowerCase `_\ () +- `toUpperCase `_\ () +- `trim `_\ () + + + +Operators +--------- + + +- `[] (element access) `_ +- `+ (concatenation) `_ +- `== (comparison) `_ + + + +Examples +-------- + + +- `StringConstructors `_ +- `StringAdditionOperator `_ +- `StringIndexOf `_ +- `StringAppendOperator `_ +- `StringLengthTrim `_ +- `StringCaseChanges `_ +- `StringReplace `_ +- `StringCharacters `_ +- `StringStartsWithEndsWith `_ +- `StringComparisonOperators `_ +- `StringSubstring `_ + + + +See Also +-------- + + +- `Character array strings `_ +- `Variable Declaration `_ + + + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/tone.rst b/source/lang/unimplemented/tone.rst new file mode 100644 index 0000000..f83bf6b --- /dev/null +++ b/source/lang/unimplemented/tone.rst @@ -0,0 +1,81 @@ +.. _lang-tone: + +tone() +====== + +Description +----------- + +Generates a square wave of the specified frequency (and 50% duty +cycle) on a pin. A duration can be specified, otherwise the wave +continues until a call to +`noTone `_\ (). The pin can be +connected to a piezo buzzer or other speaker to play tones. + + + +Only one tone can be generated at a time. If a tone is already +playing on a different pin, the call to tone() will have no effect. +If the tone is playing on the same pin, the call will set its +frequency. + + + +Use of the tone() function will interfere with PWM output on pins 3 +and 11 (on boards other than the Mega). + + + +**NOTE:** if you want to play different pitches on multiple pins, +you need to call noTone() on one pin before calling tone() on the +next pin. + + + +Syntax +------ + +tone(pin, frequency) +tone(pin, frequency, duration) + + + +Parameters +---------- + +pin: the pin on which to generate the tone + + + +frequency: the frequency of the tone in hertz + + + +duration: the duration of the tone in milliseconds (optional) + + + +Returns +------- + +nothing + + + +See also +-------- + + +- `noTone `_\ () +- `analogWrite `_\ () +- `Tutorial:Tone `_ +- `Tutorial:Pitch follower `_ +- `Tutorial:Simple Keyboard `_ +- `Tutorial: multiple tones `_ + + +- `Tutorial: PWM `_ + + + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unsignedchar.rst b/source/lang/unsignedchar.rst index c49690d..5b946ed 100644 --- a/source/lang/unsignedchar.rst +++ b/source/lang/unsignedchar.rst @@ -2,11 +2,8 @@ .. _lang-unsignedchar: -unsigned char -============= - -Description ------------ +``unsigned char`` +================= An unsigned version of the :ref:`char ` data type. An ``unsigned char`` occupies 1 byte of memory; it stores an integer from diff --git a/source/lang/unsignedint.rst b/source/lang/unsignedint.rst index aa5cc1b..f6311da 100644 --- a/source/lang/unsignedint.rst +++ b/source/lang/unsignedint.rst @@ -2,11 +2,8 @@ .. _lang-unsignedint: -unsigned int -============ - -Description ------------ +``unsigned int`` +================ An ``unsigned int`` (unsigned integer) is the same as an :ref:`int ` in that it stores a 4 byte integer value. However, diff --git a/source/lang/unsignedlong.rst b/source/lang/unsignedlong.rst index 2ca49f8..14a4fc3 100644 --- a/source/lang/unsignedlong.rst +++ b/source/lang/unsignedlong.rst @@ -2,11 +2,8 @@ .. _lang-unsignedlong: -unsigned long -============= - -Description ------------ +``unsigned long`` +================= An unsigned version of the :ref:`long ` data type. An ``unsigned long`` occupies 8 bytes of memory; it stores an integer @@ -19,8 +16,8 @@ won't store negative numbers; it is also subject to the same Here is an example of declaring an ``unsigned long`` variable named ``c``, then giving it value 299,792,458,000,000,000 (see :ref:`integer -constants ` for an explanation of the "L" at the -end of the number):: +constants ` for an explanation of the "L" +at the end of the number):: // Speed of light in nanometers per second (approximate). unsigned long c = 299792458000000000L; diff --git a/source/lang/variables.rst b/source/lang/variables.rst index 05a4f96..9094cd5 100644 --- a/source/lang/variables.rst +++ b/source/lang/variables.rst @@ -37,8 +37,8 @@ named ``inputVariable2``, with an initial value of ``0``:: int inputVariable2 = 0; The Maple environment comes ready to use with many useful types of -variables. See the :ref:`built-in types ` page for more -information. +variables. See the :ref:`built-in types ` page +for more information. Here are a few examples of declaring variables of different types:: @@ -116,8 +116,8 @@ he goes past the left side of the screen, he reappears on the right:: x = x + 1; // x now contains -2,147,483,648; rolled over "right to left" Each numeric type's reference page includes its range. See the -:ref:`built-in types ` reference for links to each type's -reference page. +:ref:`built-in types ` reference for links to each +type's reference page. Using Variables --------------- @@ -149,7 +149,7 @@ See Also -------- - :ref:`lang-scope` -- :ref:`lang-types` +- :ref:`lang-numeric-types` .. rubric:: Footnotes diff --git a/source/lang/void.rst b/source/lang/void.rst index bc7a3dc..88bd448 100644 --- a/source/lang/void.rst +++ b/source/lang/void.rst @@ -1,40 +1,31 @@ +.. highlight:: cpp + .. _lang-void: -void -==== +``void`` +======== -The void keyword is used only in function declarations. It +The ``void`` keyword is used only in function declarations. It indicates that the function is expected to return no information to -the function from which it was called. - - +the function from which it was called, or that it expects no arguments +from its caller. -Example: --------- +Example +------- :: // actions are performed in the functions "setup" and "loop" // but no information is reported to the larger program - void setup() - { + void setup() { // ... } - void loop() - { + void loop() { // ... } - - - -See also --------- - -`function declaration `_ - - +.. TODO doc page on function declaration? .. include:: cc-attribution.txt diff --git a/source/lang/volatile.rst b/source/lang/volatile.rst index a0ef671..276bb6a 100644 --- a/source/lang/volatile.rst +++ b/source/lang/volatile.rst @@ -1,37 +1,31 @@ -.. _lang-volatile: - -volatile keyword -================ - -volatile is a keyword known as a variable *qualifier*, it is -usually used before the datatype of a variable, to modify the way -in which the compiler and subsequent program treats the variable. - - - -Declaring a variable volatile is a directive to the compiler. The -compiler is software which translates your C/C++ code into the -machine code, which are the real instructions for the Atmega chip -in the Arduino. - - +.. highlight:: cpp -Specifically, it directs the compiler to load the variable from RAM -and not from a storage register, which is a temporary memory -location where program variables are stored and manipulated. Under -certain conditions, the value for a variable stored in registers -can be inaccurate. +.. _lang-volatile: +``volatile`` +============ +The ``volatile`` keyword known is a variable *qualifier*. It is +usually used before the datatype of a variable, to modify the way in +which the compiler treats the variable. -A variable should be declared volatile whenever its value can be -changed by something beyond the control of the code section in -which it appears, such as a concurrently executing thread. In the -Arduino, the only place that this is likely to occur is in sections -of code associated with interrupts, called an interrupt service -routine. +Declaring a variable ``volatile`` is a directive to the compiler. The +compiler is software which translates your C++ code into the machine +code, which are the real instructions for the STM32 chip in the +Maple. (The particular compiler we provide for use with the Maple is a +version of :ref:`GCC `). +Specifically, it directs the compiler to read the variable's value +fresh every time it is used, rather than "backing up" the value and +reading from its backup copy. (Compilers often "back up" a variable's +value in RAM into a storage location called a *register*; this is done +for efficiency). +A variable should be declared ``volatile`` whenever its value can be +changed by something beyond the control of the code section in which +it appears, such as an :ref:`external interrupt +`. On the Maple, the only place that this is +likely to occur is in sections of code associated with interrupts. Example ------- @@ -43,31 +37,29 @@ Example int pin = 13; volatile int state = LOW; - void setup() - { + void setup() { pinMode(pin, OUTPUT); attachInterrupt(0, blink, CHANGE); } - void loop() - { + void loop() { digitalWrite(pin, state); } - void blink() - { - state = !state; + void blink() { + if (state == HIGH) { + state = LOW; + } else { + // state must be HIGH + state = HIGH; + } } - - See also -------- - -- `AttachInterrupt `_ - - - +- :ref:`External Interrupts ` +- :ref:`lang-attachinterrupt` +- :ref:`lang-detachinterrupt` .. include:: cc-attribution.txt diff --git a/source/lang/while.rst b/source/lang/while.rst index be1ea14..9047d05 100644 --- a/source/lang/while.rst +++ b/source/lang/while.rst @@ -1,37 +1,28 @@ -.. _lang-while: - -while Loops -=========== - -Description ------------ - -**while** loops will loop continuously, and infinitely, until the -expression inside the parenthesis, () becomes false. Something must -change the tested variable, or the **while** loop will never exit. -This could be in your code, such as an incremented variable, or an -external condition, such as testing a sensor. +.. highlight:: cpp +.. _lang-while: +``while`` +========= Syntax ------ :: - while(expression){ - // statement(s) + while (expression) { + // block of code } +Description +----------- - -Parameters ----------- - -expression - a (boolean) C statement that evaluates to true or -false - - +``while`` loops will repeat the statements inside their associated +block of code until the expression inside the parentheses becomes +:ref:`false `. Something must change the tested +expressions' value, or the ``while`` loop will never exit. This could +be in your code, such as an incremented variable, or an external +condition, such as testing a sensor. Example ------- @@ -39,11 +30,9 @@ Example :: var = 0; - while(var < 200){ + while(var < 200) { // do something repetitive 200 times var++; } - - .. include:: cc-attribution.txt diff --git a/source/language-index.rst b/source/language-index.rst index 90b3d79..ddc7849 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -6,126 +6,23 @@ Language Reference Index This is the index of the :ref:`language reference ` documentation. -Not converted Arduino docs: - .. toctree:: :maxdepth: 1 + :glob: - lang/pwmwrite - lang/types - lang/serialusb + lang/* -Finished: +.. Unfinished, unimplemented in libmaple: .. toctree:: - :maxdepth: 1 - - lang/abs - lang/analogread - lang/pinmode - lang/arithmetic - lang/array - lang/assignment - lang/attachinterrupt - lang/bit - lang/bitclear - lang/bitread - lang/bitset - lang/bitshift - lang/analogwrite - lang/bitwisemath - lang/bitwisecompound - lang/bitwrite - lang/boolean - lang/booleanvariables - lang/braces - lang/break - lang/byte - lang/bytecast - lang/char - lang/charcast - lang/comments - lang/const - lang/constrain - lang/continue - lang/cos - lang/define - lang/delay - lang/delaymicroseconds - lang/detachinterrupt - lang/digitalread - lang/double - lang/doublecast - lang/dowhile - lang/else - lang/float - lang/floatcast - lang/for - lang/goto - lang/highbyte - lang/if - lang/comparison - lang/include - lang/increment - lang/arithmeticcompound - lang/int - lang/intcast - lang/long - lang/longcast - lang/loop - lang/max - lang/min - lang/modulo - lang/pointer - lang/pow - lang/return - lang/scope - lang/semicolon - lang/sin - lang/sizeof - lang/sqrt - lang/sq - lang/static - lang/string - lang/switchcase - lang/tan - lang/unsignedchar - lang/unsignedint - lang/unsignedlong - lang/variables + :hidden: -Unfinished; straightforward to convert: - -.. toctree:: - :maxdepth: 1 - - lang/void - lang/volatile - lang/while - lang/keywords - lang/enum - -Unfinished, requires libmaple/Arduino knowledge: - -.. toctree:: - :maxdepth: 1 + lang/unimplemented/interrupts.rst + lang/unimplemented/nointerrupts.rst + lang/unimplemented/notone.rst + lang/unimplemented/pulsein.rst + lang/unimplemented/shiftout.rst + lang/unimplemented/stringclass.rst + lang/unimplemented/stringobject.rst + lang/unimplemented/tone.rst - lang/constants - lang/digitalwrite - lang/notone - lang/serial - lang/interrupts - lang/analogwrite - lang/nointerrupts - lang/pulsein - lang/stringobject - lang/tone - lang/random - lang/randomseed - lang/setup - lang/map - lang/shiftout - lang/micros - lang/millis - lang/lowbyte - lang/stringclass diff --git a/source/language.rst b/source/language.rst index 0a79fb0..350b0c3 100644 --- a/source/language.rst +++ b/source/language.rst @@ -52,6 +52,9 @@ Unique Maple Additions Maple Language Reference ------------------------ +The following table summarizes the available language features. A +more exhaustive index is available at the :ref:`language-index`. + +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | | | | | @@ -63,151 +66,154 @@ Maple Language Reference | | |* :ref:`digitalWrite() ` | |**Control Structures** |* :ref:`INPUT ` | | | | | :ref:`OUTPUT ` |* :ref:`digitalRead() ` | -|* :ref:`if ` | | | +|* :ref:`if/else ` | | | | |* :ref:`true ` | | | -|* :ref:`if...else ` | :ref:`false ` |**Analog I/O** | -| | | | -|* :ref:`for ` |* :ref:`integer constants |* :ref:`analogRead() ` | -| | ` | | -|* :ref:`switch/case ` | |* :ref:`pwmWrite() ` | -| |* :ref:`floating point constants | (:ref:`analogWrite() ` is | -|* :ref:`while ` | ` | also available, though its use is discouraged) | +|* :ref:`for ` | :ref:`false ` |**Analog I/O** | | | | | -|* :ref:`do...while ` | | | -| |**Data Types** |**Advanced I/O** | +|* :ref:`switch/case ` |* :ref:`Constants |* :ref:`analogRead() ` | +| | ` (:ref:`integers | | +|* :ref:`while ` | `, :ref:`floating |* :ref:`pwmWrite() ` | +| | point `) | (:ref:`analogWrite() ` is | +|* :ref:`do...while ` | | also available, though its use is discouraged) | +| |**Data Types** | | |* :ref:`break ` | | | -| | The size of each datatype, in bytes, is |* tone(): TODO | +| | The size of each datatype, in bytes, is |**Advanced I/O** | |* :ref:`continue ` | given in parentheses where appropriate. | | -| | |* noTone(): TODO | +| | |* tone(): TODO | |* :ref:`return ` | *Note*: The ``word`` type is (deliberately) | | -| | :ref:`not supported `. |* shiftOut(): TODO | +| | :ref:`not supported `. |* noTone(): TODO | |* :ref:`goto ` | | | -| |* :ref:`void ` |* pulseIn(): TODO | +| |* :ref:`void ` |* shiftOut(): TODO | +| | | | +|**Further syntax** |* :ref:`boolean ` (1 byte) |* pulseIn(): TODO | | | | | -|**Further syntax** |* :ref:`boolean ` (1 byte) | | -| | |**Time** | |* :ref:`; (semicolon) ` |* :ref:`char ` (1 byte) | | -| | |* :ref:`millis() ` | -|* :ref:`{} (curly braces) ` |* :ref:`unsigned char | | -| | ` (1 byte) |* :ref:`micros() ` | -|* :ref:`// (single-line comment) | | | -| ` |* :ref:`byte ` (1 byte) |* :ref:`delay() ` | +| | |**Time** | +|* :ref:`{} (curly braces) |* :ref:`unsigned char | | +| ` | ` (1 byte) |* :ref:`millis() ` | | | | | -|* :ref:`/\* \*/ (multi-line comment) |* :ref:`int ` (4 bytes) |* :ref:`delayMicroseconds() | -| ` | | ` | -| |* :ref:`unsigned int ` | | -|* :ref:`#define ` | (4 bytes) | | -| | |**Math** | -|* :ref:`#include ` |* :ref:`long ` (8 bytes) | | -| | |* :ref:`min() ` | +|* :ref:`// (single-line comment) |* :ref:`byte ` (1 byte) |* :ref:`micros() ` | +| ` | | | +| |* :ref:`int ` (4 bytes) |* :ref:`delay() ` | +|* :ref:`/\* \*/ (multi-line comment) | | | +| ` |* :ref:`unsigned int ` |* :ref:`delayMicroseconds() | +| | (4 bytes) | ` | +|* :ref:`#define ` | | | +| |* :ref:`long ` (8 bytes) | | +|* :ref:`#include ` | |**Math** | | |* :ref:`unsigned long ` | | -|**Arithmetic Operators** | (8 bytes) |* :ref:`max() ` | +| | (8 bytes) |* :ref:`min() ` | +|**Arithmetic Operators** | | | +| |* :ref:`float ` (4 bytes) |* :ref:`max() ` | +|* :ref:`= ` | | | +| (assignment operator) |* :ref:`double ` (8 bytes) |* :ref:`abs() ` | | | | | -|* :ref:`= ` |* :ref:`float ` (4 bytes) |* :ref:`abs() ` | -| (assignment operator) | | | -| |* :ref:`double ` (8 bytes) |* :ref:`constrain() ` | -|* :ref:`+ ` (addition) | | | -| |* :ref:`string ` |* :ref:`map() ` | -|* :ref:`- ` | | | -| (subtraction) |* :ref:`array ` |* :ref:`pow() ` | +|* :ref:`+ ` (addition) |* :ref:`Strings ` |* :ref:`constrain() ` | | | | | -|* :ref:`* ` |* See also: :ref:`built-in types reference |* :ref:`sqrt() ` | -| (multiplication) | `. | | +|* :ref:`- ` |* :ref:`Arrays ` |* :ref:`map() ` | +| (subtraction) | | | +| |* :ref:`enum ` |* :ref:`pow() ` | +|* :ref:`* ` | | | +| (multiplication) |* :ref:`Numeric types ` |* :ref:`sqrt() ` | | | | | -|* :ref:`/ ` (division) | |**Trigonometry** | -| |**Conversion** | | -|* :ref:`% ` (modulo) | |* :ref:`sin() ` | -| |* :ref:`char() ` | | -| | |* :ref:`cos() ` | -|**Comparison Operators** |* :ref:`byte() ` | | -| | |* :ref:`tan() ` | -|* :ref:`== ` (equal to) |* :ref:`int() ` | | +|* :ref:`/ ` (division) |**Conversion** | | +| | |**Trigonometry** | +|* :ref:`% ` (modulo) |* :ref:`char() ` | | +| | |* :ref:`sin() ` | +| |* :ref:`byte() ` | | +|**Comparison Operators** | |* :ref:`cos() ` | +| |* :ref:`int() ` | | +|* :ref:`== ` (equal to) | |* :ref:`tan() ` | +| |* :ref:`long() ` | | +|* :ref:`\!= ` | | | +| (not equal to) |* :ref:`float() ` |**Random Numbers** | | | | | -|* :ref:`\!= ` |* :ref:`long() ` |**Random Numbers** | -| (not equal to) | | | -| |* :ref:`float() ` |* :ref:`randomSeed() ` | -|* :ref:`< ` (less than) | | | -| |* :ref:`double() ` |* :ref:`random() ` | -|* :ref:`> ` | | | -| (greater than) | | | -| |**Variable Scope & Qualifiers** |**Bits and Bytes** | -|* :ref:`<= ` | | | -| (less than or equal to) |* :ref:`variables `, |* :ref:`lowByte() ` | -| | :ref:`scope ` | | -|* :ref:`>= ` | |* :ref:`highByte() ` is | -| (greater than or equal to) |* :ref:`static ` | provided, though its use is discouraged. | +|* :ref:`< ` (less than) |* :ref:`double() ` |* :ref:`randomSeed() ` | | | | | -| |* :ref:`volatile ` |* :ref:`bitRead() ` | -|**Boolean Operators** | | | -| |* :ref:`const ` |* :ref:`bitWrite() ` | -|* :ref:`&& ` (and) | | | -| | |* :ref:`bitSet() ` | -|* :ref:`|| ` (or) |**Utilities** | | -| | |* :ref:`bitClear() ` | -|* :ref:`\! ` (not) |* :ref:`sizeof() ` | | -| | (``sizeof`` operator) |* :ref:`bit() ` | +|* :ref:`> ` | |* :ref:`random() ` | +| (greater than) |**Variable Scope & Qualifiers** | | | | | | -|**Pointer Operators** | | | -| | |**External Interrupts** | -|* :ref:`* dereference operator | | | -| ` | |* :ref:`Reference Page ` | +|* :ref:`<= ` |* :ref:`variables `, |**Bits and Bytes** | +| (less than or equal to) | :ref:`scope ` | | +| | |* :ref:`lowByte() ` | +|* :ref:`>= ` |* :ref:`static ` | | +| (greater than or equal to) | |* :ref:`highByte() ` is | +| |* :ref:`volatile ` | provided, though its use is discouraged. | | | | | -|* :ref:`& reference operator | |* :ref:`attachInterrupt() | -| ` | | ` | +|**Boolean Operators** |* :ref:`const ` |* :ref:`bitRead() ` | | | | | -| | |* :ref:`detachInterrupt() | -|**Bitwise Operators** | | ` | +|* :ref:`&& ` (and) | |* :ref:`bitWrite() ` | +| |**Utilities** | | +|* :ref:`|| ` (or) | |* :ref:`bitSet() ` | +| |* :ref:`sizeof() ` | | +|* :ref:`\! ` (not) | |* :ref:`bitClear() ` | | | | | +| | |* :ref:`bit() ` | +|**Pointer Operators** | | | +| | | | +|* :ref:`* dereference operator | |**External Interrupts** | +| ` | | | +| | |* :ref:`Reference Page ` | +|* :ref:`& reference operator | | | +| ` | |* :ref:`attachInterrupt() | +| | | ` | +| | | | +|**Bitwise Operators** | |* :ref:`detachInterrupt() | +| | | ` | |* :ref:`& ` | | | -| (bitwise and) | |**Interrupts** | +| (bitwise and) | | | +| | |**Interrupts** | +|* :ref:`| ` | | | +| (bitwise or) | |* interrupts(): TODO | | | | | -|* :ref:`| ` | |* interrupts(): TODO | -| (bitwise or) | | | -| | |* noInterrupts(): TODO | -|* :ref:`^ ` | | | +|* :ref:`^ ` | |* noInterrupts(): TODO | | (bitwise xor) | | | -| | |**Communication** | -|* :ref:`~ ` | | | -| (bitwise not) | |* :ref:`SerialUSB ` | | | | | -|* :ref:`\<\< ` | |* :ref:`Serial ` | -| (shift left) | | | -| | |**Looking for something else?** | -|* :ref:`>> ` | | | -| (shift right) | | See the :ref:`libraries` page for interfacing with| +|* :ref:`~ ` | |**Communication** | +| (bitwise not) | | | +| | |* :ref:`SerialUSB ` | +|* :ref:`\<\< ` | | | +| (shift left) | |* :ref:`Serial ` | +| | | | +|* :ref:`>> ` | |**Looking for something else?** | +| (shift right) | | | +| | | See the :ref:`libraries` page for interfacing with| | | | particular types of hardware. Maple links | -| | | against `newlib `_ | -|**Compound Operators** | | and allows the use of any of its functions; see | -| | | its documentation for more details. | -|* :ref:`++ ` | | | +|**Compound Operators** | | against `newlib `_ | +| | | and allows the use of any of its functions; see | +|* :ref:`++ ` | | its documentation for more details. | | (increment) | | | | | | | |* :ref:`- - ` | | | | (decrement) | | | | | | | -|* :ref:`+= ` | | | +|* :ref:`+= ` | | | | (compound add) | | | | | | | |* :ref:`-= | | | -| ` (compound | | | +| ` (compound | | | | subtract) | | | | | | | |* :ref:`*= | | | -| ` (compound | | | +| ` (compound | | | | multiply) | | | | | | | |* :ref:`/= | | | -| ` (compound | | | +| ` (compound | | | | divide) | | | | | | | |* :ref:`&= | | | -| ` (compound | | | +| ` (compound | | | | bitwise and) | | | | | | | |* :ref:`|= | | | -| ` (compound | | | +| ` (compound | | | | bitwise or) | | | | | | | +|**Keywords** | | | +| | | | +|* :ref:`C++ Keywords ` | | | +| | | | | | | | +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ diff --git a/source/libraries.rst b/source/libraries.rst index 6a97b0e..6ecdf07 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -18,7 +18,7 @@ in the description of the library. .. contents:: Contents :local: -.. _liquid_crystal: +.. _libraries-liquid-crystal: LiquidCrystal ------------- @@ -32,7 +32,7 @@ At this time, no incompatibilities between the Maple and Arduino versions are known. Any observed differences should be considered bugs, and reported on the forums. -.. _wire: +.. _libraries-wire: Wire ---- diff --git a/source/spi.rst b/source/spi.rst index 4cfd7e7..ca9415c 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -35,7 +35,7 @@ Function Reference ``Spi.begin(freq, endianness, mode)`` - ``begin`` is usually called in `setup()`_ to configure the + ``begin`` is usually called in :ref:`lang-setup` to configure the baudrate of the given SPI port and to set up the header pins appropriately. ``freq`` is one of the set listed :ref:`above `; ``endianness`` is either ``LSBFIRST`` or diff --git a/source/timers.rst b/source/timers.rst index fe6ea4a..948805b 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -2,9 +2,8 @@ .. _timers: -======== - Timers -======== +Timers +====== There are four general purpose timers in the Maple microcontroller that can be configured to generate periodic or delayed events with @@ -52,7 +51,7 @@ configuration being the same. **Jitter:** other interrupts (USB, Serial, SysTick, or other timers) can and will get called before or during the timer - interrupt routines, causing pseudo-random delays and other + interrupt routines, causing pseudorandom delays and other frustrations. Disabling the USB port (by calling ``SerialUSB.end()``, or just @@ -90,7 +89,7 @@ General Timer Modes :ref:`PWM docs ` for more information on this mode. .. note:: - + ``Timer1.setChannel1Mode(TIMER_PWM)`` may not work as expected; if you want PWM functionality on a channel, make sure you don't set it to something else. @@ -240,7 +239,7 @@ LED blink void setup() { - // Set up the LED to blink + // Set up the LED to blink pinMode(LED_PIN, OUTPUT); // Setup Timer @@ -251,13 +250,13 @@ LED blink } void loop() { - // Nothing! It's all in the interrupts + // Nothing! It's all in the interrupts } void handler_led(void) { toggle ^= 1; digitalWrite(LED_PIN, toggle); - } + } Racing Counters ^^^^^^^^^^^^^^^ @@ -287,7 +286,7 @@ Racing Counters Timer3.setOverflow(30000); Timer4.setOverflow(30000); Timer3.setCompare1(1000); // somewhere in the middle - Timer4.setCompare1(1000); + Timer4.setCompare1(1000); Timer3.attachCompare1Interrupt(handler1); Timer4.attachCompare1Interrupt(handler2); Timer3.resume(); @@ -296,9 +295,9 @@ Racing Counters void loop() { // Display the running counts - SerialUSB.print("Count 1: "); + SerialUSB.print("Count 1: "); SerialUSB.print(count1); - SerialUSB.print("\t\tCount 2: "); + SerialUSB.print("\t\tCount 2: "); SerialUSB.println(count2); // Run... while BUT is held, pause Count2 @@ -314,7 +313,7 @@ Racing Counters void handler1(void) { count1++; - } + } void handler2(void) { count2++; - } + } diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 9d452d1..7b80a3f 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -30,10 +30,8 @@ use :ref:`perpetual bootloader mode My board is bricked! I can't upload via the bootloader no matter what! ---------------------------------------------------------------------- -Use the hardcoded serial STM32 serial bootloader to re-flash the -bootloader. - -.. TODO insert docs on reflashing the bootloader +Use the hardcoded serial STM32 serial bootloader to :ref:`re-flash the +bootloader `. If it really is bricked, and you think it's our fault, `contact us `_\ ! @@ -100,18 +98,18 @@ a board selected. The work-around is to restart the IDE. Mysterious! ``NullPointerException`` ------------------------ -A classic! Make sure you have selected a board from the pulldown menu. +A classic! Make sure you have selected a board from the pulldown menu. .. TODO: remove when Python version is released ``undefined reference to setup()/loop()`` ----------------------------------------- -Your sketch/program either does not include one of the `setup -`_ or `loop `_ functions, or it was not found by the -compiler. Your program must include both ``void setup()`` and ``void -loop()`` functions; they don't have to do anything, but they **must** -be there. +Your sketch/program either does not include one of the :ref:`setup() +` or `loop() ` functions, or it was not found +by the compiler. Your program must include both ``void setup()`` and +``void loop()`` functions; they don't have to do anything, but they +**must** be there. You can start with an example program (to see one in the IDE, click on File > Examples > Stubs > BareMinimum) to get the basic structure. @@ -152,7 +150,7 @@ is several times more FLASH memory available for user programs. ``No DFU capable USB device found`` ----------------------------------- -This probably means you don't have a Maple plugged in or powered on! +This probably means you don't have a Maple plugged in or powered on! I have multiple Maples installed; how do I know which one will get flashed? --------------------------------------------------------------------------- diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 2bb584a..e6039a2 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -97,12 +97,12 @@ This step is fairly straightforward: do a git clone of the `libmaple repository `_ to some directory, then download and extract the ARM compiler toolchain. -The :file:`arm/bin/` directory will need to be added to -:envvar:`PATH`; you can check that this worked by entering -``arm-none-`` and hitting tab to auto-complete (bash should show a -bunch of results). Regardless of where you put the toolchain, make -sure to preserve its internal directory layout, as the binaries make -relative path calls and references. +The :file:`arm/bin/` directory will need to be added to ``PATH``; you +can check that this worked by entering ``arm-none-`` and hitting tab +to auto-complete (bash should show a bunch of results). Regardless of +where you put the toolchain, make sure to preserve its internal +directory layout, as the binaries make relative path calls and +references. .. _toolchain-udev: @@ -176,7 +176,7 @@ You will need the following tools to get started: :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` To get access to it from the command line, just make a symbolic link - to the binary from some place on your :envvar:`PATH`:: + to the binary from some place on your ``PATH``:: $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ /somewhere/on/your/PATH/dfu-util @@ -241,7 +241,7 @@ live with :: $ export PATH=$PATH:~/libmaple/arm/bin After that's done, you'll probably want to update your shell startup -script so :file:`~/libmaple/arm/bin` stays in your :envvar:`PATH`. +script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. **So far, so good?** @@ -350,8 +350,8 @@ Starting your own projects -------------------------- So everything worked, and you want to start your own project? Great! -It's easy. Just set the environment variable :envvar:`LIB_MAPLE_HOME` -in your shell startup script to point to the libmaple repository you +It's easy. Just set the environment variable ``LIB_MAPLE_HOME`` in +your shell startup script to point to the libmaple repository you cloned (this tutorial assumes you put it in :file:`~/libmaple`). For example, if you use bash as your shell, just put this line in your :file:`~/.bashrc` or :file:`~/.bash_profile`:: @@ -417,10 +417,9 @@ but it might be helpful for people who are allergic to `vim `_. The simple configuration described here just calls down to the :file:`Makefile`, so follow the above directions to get the command line tools configured (you'll -definitely need the arm-none-eabi-* tools on your :envvar:`PATH`), -then `install Code::Blocks -`_. You can do this on Linux -with:: +definitely need the arm-none-eabi-* tools on your ``PATH``), then +`install Code::Blocks `_. You +can do this on Linux with:: $ sudo aptitude install codeblocks @@ -434,8 +433,8 @@ to get a feel for how it all works. To create your own "libmaple" project, start with an "Empty Project" with the "Folder to create project in" set to your -:envvar:`LIB_MAPLE_HOME`. Make sure that the "Resulting filename" is -in the top level directory as well. +``LIB_MAPLE_HOME``. Make sure that the "Resulting filename" is in the +top level directory as well. .. image:: /_static/img/codeblocks_newproject.png :align: center diff --git a/source/usb.rst b/source/usb.rst index baabde5..5494b06 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -6,21 +6,6 @@ USB ===== -.. note:: Changes and Caveats - - The SerialUSB functionality was modified for the 0.0.6 IDE - release. It now includes a 50 millisecond timeout for writes and - does not try to detect if the USB host is "really" connected or - just enumerated and initialized. This means that if you have a - number of SerialUSB writes or prints in your code and you are not - monitoring on a computer your program will run much, much slower - than if it is being monitored or totally disconnected (battery). - - You can avoid this behavior by :ref:`deciphering the port status - ` using the DTR and RTS line status; the behavior - of these control lines is platform dependent and we no longer - interpret them by default. - The Maple STM32 microprocessor includes a dedicated USB peripheral which can be configured to act as a general USB slave device with transfer rates up to 12Mbps (it unfortunately can't be configured as a @@ -30,152 +15,21 @@ and second, to emulate a regular serial port for use as a terminal (text read/write). The emulated terminal is relatively slow and inefficient; it is best -for transferring data at regular serial speeds (kilobaud). Users -requiring faster data transfer should consider implementing a -different communications protocol; the Maple could be reprogrammed to -appear as a mass storage device (thumb drive), human interface device -(mouse or keyboard), microphone, or any other USB device. +for transferring data at regular serial speeds (kilobaud). Library +support for accessing the emulated terminal is available at the +:ref:`SerialUSB ` reference. -The SerialUSB channel is also used as part of the auto-reset feature -of the IDE to program the board (on Maple Rev3): a :ref:`magic +The SerialUSB channel is used as part of the auto-reset feature of the +IDE to program the board on Maple Rev 3 and Rev 5: a :ref:`magic sequence of control line toggles and transmitted data ` causes the Maple to reset itself and enter bootloader mode. As an unfortunate consequence, the auto-reset will not work if the IDE can not access the serial port, either due to a conflict with another program (serial monitor) or because the interface has been disabled from the Maple side (through -``SerialUSB.end()``). - -Function Reference ------------------- - -``SerialUSB.print(...)``/\ ``SerialUSB.println(...)`` - - Writes data into the port buffer to be transmitted as soon as - possible. Accepts strings (``char*``). If a raw integer is passed - the corresponding ASCII character will be transmitted; to print - out a number in human readable form add a second parameter with - the base system. For example, to print out the decimal number - "1234", use ``SerialUSB.print(1234, DEC)``; to print out the - binary number "1001", use ``SerialUSB.print(9, BIN)``. - -.. _usb-write: - -``SerialUSB.write(bytes)`` - - ``write`` is a lower-level function that writes bytes directly - into the buffer. :ref:`print() ` often calls this - function dozens of times to write out a single formatted number; - user code can optimize raw data speed by calling this function - with 64-byte chunks instead. - -``SerialUSB.available()``/\ ``SerialUSB.read()`` - - ``SerialUSB.read()`` will return the next available character - (``byte``) that has been received over the port. - ``SerialUSB.available()`` returns how many such bytes are actually - available. If there is no data, ``read`` will block/fail, so the - usual program structure is to poll with ``available`` and only - ``read`` if there are data to read. - -``SerialUSB.read(buffer, length)`` - - An alternative version of ``SerialUSB.read``; will write the next - ``length`` available characters into the array ``buffer``. - -``SerialUSB.pending()`` - - Returns the number of bytes waiting in the transmit - buffer. Usercode can use this to prevent any blocking/waiting when - using the direct :ref:`write ` functions, or to check - if data was actually requested/received by the host. - -``SerialUSB.getRTS()`` - - Returns the state (1 or 0) of the virtual RTS ("ready to send") - line. This can be used to guess if the USB host is actively - waiting for data (e.g., if a serial monitor program is running) or - just "configured" (i.e., the virtual serial port is configured, - but no program is reading data). - -``SerialUSB.getDTR()`` - - Returns the state (1 or 0) of the virtual DTR ("data terminal - ready") line. This can be used to guess if the USB host is - actively waiting for data (e.g., if a serial monitor program is - running) or just "configured" (i.e., the virtual serial port is - configured, but no program is reading data). - -.. TODO deprecate crap out of above two functions; write a sane API - -``SerialUSB.isConnected()`` - - Returns 1 if the USB host is connected and the virtual serial - interface is initialized (though not necessarily active). - Otherwise, returns 0. - -``SerialUSB.end()``/\ ``SerialUSB.begin()`` - - The USB peripheral is enabled by default so that the auto-reset - feature will work, but it can be disabled/restarted at any time - with the ``SerialUSB.end()`` and ``SerialUSB.begin()`` - functions. - - ``SerialUSB.end()`` is a relatively hard shutdown, similar to - unplugging the board; this may crash or confuse any programs - running host-side. Note that calling this function will require - the Maple to be put into :ref:`perpetual bootloader mode - ` before another program can - be uploaded onto it, unless ``SerialUSB.begin()`` is called before - the upload is attempted. - - It's probably wise to wait a few seconds between calls to - ``SerialUSB.end()`` and ``SerialUSB.begin()`` (or to - ``SerialUSB.begin()`` and ``SerialUSB.print()``) to let the - computer reconfigure. - -Code Examples -------------- - -.. _usb-safe-print: - -Safe Print -^^^^^^^^^^ - -This function should run smoothly and not block; the LED should blink -at roughly the same speed whether being monitored, running from -battery, or connected but not monitored. You may need to experiment -with the DTR/RTS logic for your platform and device configuration. :: - - #define LED_PIN 13 - - void setup() { - /* Set up the LED to blink */ - pinMode(LED_PIN, OUTPUT); - } - - void loop() { - // LED will stay off if we are disconnected; - // will blink quickly if USB is unplugged (battery etc) - if(SerialUSB.isConnected()) { - digitalWrite(LED_PIN, 1); - } - delay(100); - - // If this logic fails to detect if bytes are going to - // be read by the USB host, then the println() will fully - // many times, causing a very slow LED blink. - // If the characters are printed and read, the blink will - // only slow a small amount when "really" connected, and fast - // when the virtual port is only configured. - if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) { - for(int i=0; i<10; i++) { - SerialUSB.println(123456,BIN); - } - } - digitalWrite(LED_PIN, 0); - delay(100); - } +:ref:`SerialUSB.end() `). A solution to the +second problem is the use of :ref:`perpetual bootloader mode +`. Recommended Reading ------------------- -- cgit v1.2.3 From 8e42d34c8d3c81c037a3acaca553ea8c5e4f25aa Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 29 Nov 2010 18:08:04 -0500 Subject: New documentation content is done. Next step is to theme. --- source/_static/img/button-new.png | Bin 0 -> 234 bytes source/_static/img/button-open.png | Bin 0 -> 259 bytes source/_static/img/button-save.png | Bin 0 -> 253 bytes source/_static/img/button-serial-monitor.png | Bin 0 -> 249 bytes source/_static/img/button-stop.png | Bin 0 -> 294 bytes source/_static/img/button-upload.png | Bin 0 -> 291 bytes source/_static/img/button-verify.png | Bin 0 -> 326 bytes source/_static/img/ide-blinky.png | Bin 0 -> 29213 bytes source/_static/img/serial-monitor.png | Bin 0 -> 55975 bytes source/arm-gcc.rst | 72 ++++++++--- source/bootloader.rst | 105 ++++++++++++++- source/compatibility.rst | 187 ++++++++++++++++++++++----- source/epilog.rst | 53 -------- source/errata.rst | 144 ++++++++++++++++++++- source/hardware.rst | 24 ---- source/ide.rst | 123 ++++++++++++++++-- source/index.rst | 21 ++- source/jtag.rst | 5 +- source/lang/analogwrite.rst | 2 + source/lang/serial.rst | 31 +++-- source/lang/serialusb.rst | 2 + source/lang/unimplemented/stringclass.rst | 3 - source/language.rst | 16 ++- source/libmaple-api.rst | 11 -- source/libmaple.rst | 22 ++-- source/libraries.rst | 3 + source/maple-quickstart.rst | 4 +- source/pwm.rst | 23 ++-- source/troubleshooting.rst | 4 +- source/usart.rst | 80 ++---------- 30 files changed, 663 insertions(+), 272 deletions(-) create mode 100644 source/_static/img/button-new.png create mode 100644 source/_static/img/button-open.png create mode 100644 source/_static/img/button-save.png create mode 100644 source/_static/img/button-serial-monitor.png create mode 100644 source/_static/img/button-stop.png create mode 100644 source/_static/img/button-upload.png create mode 100644 source/_static/img/button-verify.png create mode 100644 source/_static/img/ide-blinky.png create mode 100644 source/_static/img/serial-monitor.png delete mode 100644 source/hardware.rst delete mode 100644 source/libmaple-api.rst diff --git a/source/_static/img/button-new.png b/source/_static/img/button-new.png new file mode 100644 index 0000000..3fd98be Binary files /dev/null and b/source/_static/img/button-new.png differ diff --git a/source/_static/img/button-open.png b/source/_static/img/button-open.png new file mode 100644 index 0000000..466fc10 Binary files /dev/null and b/source/_static/img/button-open.png differ diff --git a/source/_static/img/button-save.png b/source/_static/img/button-save.png new file mode 100644 index 0000000..7eba286 Binary files /dev/null and b/source/_static/img/button-save.png differ diff --git a/source/_static/img/button-serial-monitor.png b/source/_static/img/button-serial-monitor.png new file mode 100644 index 0000000..aec9741 Binary files /dev/null and b/source/_static/img/button-serial-monitor.png differ diff --git a/source/_static/img/button-stop.png b/source/_static/img/button-stop.png new file mode 100644 index 0000000..4812ae9 Binary files /dev/null and b/source/_static/img/button-stop.png differ diff --git a/source/_static/img/button-upload.png b/source/_static/img/button-upload.png new file mode 100644 index 0000000..0f41eeb Binary files /dev/null and b/source/_static/img/button-upload.png differ diff --git a/source/_static/img/button-verify.png b/source/_static/img/button-verify.png new file mode 100644 index 0000000..95abeb8 Binary files /dev/null and b/source/_static/img/button-verify.png differ diff --git a/source/_static/img/ide-blinky.png b/source/_static/img/ide-blinky.png new file mode 100644 index 0000000..3cccdb4 Binary files /dev/null and b/source/_static/img/ide-blinky.png differ diff --git a/source/_static/img/serial-monitor.png b/source/_static/img/serial-monitor.png new file mode 100644 index 0000000..6162dab Binary files /dev/null and b/source/_static/img/serial-monitor.png differ diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 8435a1f..ef745f5 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -1,34 +1,70 @@ .. _arm-gcc: -============ - GCC on ARM -============ +GCC for Maple +============= -This document provides an introduction to using -:command:`arm-none-eabi-gcc`\ , the `CodeSourcery -`_ version of the GNU `GCC -`_ compilers used to compile programs for the -Maple. +This document provides notes on the current usage of +``arm-none-eabi-gcc``, the `CodeSourcery `_ +version of the GNU `GCC `_ compilers used to +compile programs for the Maple. It is not intended as a reference +manual for GCC; such manuals are available `elsewhere +`_. -Stub. +Obtaining ``arm-none-eabi-gcc`` +------------------------------- +Recent versions of ``arm-none-eabi-gcc`` and associated tools are +included with the :ref:`Maple IDE `. -.. _arm-gcc-avr-gcc-diff: +Users who wish to use ``arm-none-eabi-gcc`` in concert with a standard +Unix toolchain are referred to our :ref:`unix-toolchain` reference, +which describes how to set up such an environment. +LeafLabs mirrors some of the more recent versions of the compiler +under http://static.leaflabs.com/pub/codesourcery/\ , including +versions for OS X, win32, and 32-bit Linux. -Differences with AVR-GCC ------------------------- +Compiler Flags Used by libmaple +------------------------------- -people coming from arduino and other Atmel AVR powered microcontroller -platforms are likely to be used to AVR-GCC. our compiler is -different. explain why (stub). +This section documents the flags passed to ``arm-none-eabi-gcc`` by +the :ref:`Maple IDE ` and the default Makefile provided with +:ref:`libmaple `. The information in this section is +subject to change without notice. +.. highlight:: sh + +The following flags are among those passed to the C compiler:: + + -Os -g -mcpu=cortex-m3 -mthumb -march=armv7-m -nostdlib + -ffunction-sections -fdata-sections -Wl,--gc-sections + +The following flags are among those passed to the C++ compiler:: + + -fno-rtti -fno-exceptions -Wall + +The following flags are among those passed to the assembler:: + + -mcpu=cortex-m3 -march=armv7-m -mthumb + +.. highlight:: cpp + +.. _arm-gcc-avr-gcc: + +Switching from AVR-GCC +---------------------- + +This section, which is expected to grow over time, describes +techniques for porting code which uses AVR-GCC features (AVR-GCC is +the compiler used by many Atmel AVR-based microcontroller boards, +including Arduino) for use on the Maple. .. _arm-gcc-attribute-flash: -Tips and Tricks ---------------- +- Replacing ``PROGMEM``: You can direct the linker script provided + with libmaple to store a variable in flash by using + ``__attribute__((section (".USER_FLASH")))``, like so:: -* you can use ``__attribute__`` to stick things in flash (stub) + uint32 arr[] __attribute__((section (".USER_FLASH"))) = {...}; diff --git a/source/bootloader.rst b/source/bootloader.rst index 1cfd17f..d42c050 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -95,8 +95,8 @@ platforms to make everything work this way. .. _bootloader-rev3: -Maple Rev3/Rev5 ---------------- +Maple Rev3/Rev5 - DFU +--------------------- Maple Rev 3 takes a completely different tack, more along the lines of Arduino. In Rev 3, the device resets into bootloader mode, which @@ -143,6 +143,11 @@ bringing up the USB serial. Maple Rev6 - The Serial Bootloader (Tentative) ---------------------------------------------- +.. note:: This section documents an in-progress version of the Maple + bootloader. **No Maples yet sold use this bootloader protocol**. + It has not been yet been publicly released, and its interface is + not stable. + The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac, but was unsatisfactory on Windows. Unlike the other operating systems, Windows needed to be manually pointed to both the driver to use for @@ -580,4 +585,98 @@ SOFT_RESET response: Flashing A Custom Bootloader ---------------------------- -Stub (flashing a custom bootloader) +The STM32 microprocessor on the Maple comes with a built-in hardware +bootloader that can be used to flash a new (software) bootloader onto +the chip. This section describes how to go about this, using a Maple +Rev 3 or higher (if you have a Maple Rev 1; you don't have a BUT +button, and won't be able to follow these directions. A workaround is +detailed in `this forum posting +`_). + +.. warning:: This section is directed at users wishing to write a + custom bootloader for the Maple, or update their bootloader to a + more recent version. It's generally not necessary to do so, and it + is possible to make a mistake and e.g. render your Maple unable to + communicate with the IDE. Know what you're doing, and proceed with + caution. + +.. highlight:: sh + +Setup +^^^^^ + +In order to follow these instructions, you will need: + +- A binary of the bootloader you want to upload +- Hardware for communicating between the Maple and your computer over + serial. +- `Python `_ version 2.5 or higher, with the + `PySerial `_ library installed. + +**Step 1: Obtain a bootloader binary**. The first thing you'll need to +do is to compile your bootloader binary. Note that an ASCII +representation of the binary, such as the Intel .hex format, will not +suffice. For example, you can run (on a :ref:`suitably configured +system `) the following to obtain a binary of the +bootloader currently used on the Maple:: + + $ git checkout git://github.com/leaflabs/maple-bootloader.git + $ cd maple-bootloader + $ make + $ ls -lh build/maple-boot.bin # this is the compiled bootloader binary + +**Step 2: Connect Maple Serial1 to your computer**. +There are a variety of ways of doing this. We use Sparkfun's `FTDI +breakout boards `_, but you +could use another Maple, an Arduino, etc. -- anything that allows your +computer to communicate with the Maple you want to reprogram over a +serial interface. + +If you do use an FTDI breakout board, first make sure your Maple is +disconnected from an external power source, be it battery, USB, or +barrel jack. Then, connect the FTDI board's TX pin to ``Serial1``\ 's +RX pin (pin 8), FTDI RX to ``Serial1`` TX (pin 7), FTDI ground to +Maple's GND, and its 3.3V pin to Maple's Vin (use the Maple's +silkscreen for help locating these pins). At this point, you're ready +to plug the FTDI board into your computer (via USB). + +The ``Serial1`` pins are documented :ref:`here `. + +**Step 3: Put your Maple into serial bootloader mode**. Do this by +pressing the RESET button, then *while RESET is held down*, pressing +and holding the BUT button. Next, *making sure to keep BUT held +down*, release the RESET button and wait for a few seconds before +releasing BUT. + +**Step 4: Obtain stm32loader.py**. The +script ``stm32loader.py`` is provided with libmaple. If you have set +up the :ref:`Unix toolchain `, it is available in +libmaple/support/stm32loader.py. Otherwise, you can download it +directly from `github +`_ +(click the link, then save the file somewhere on your system). + +Flashing the new Bootloader +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We'll use ``new-boot.bin``, ``ser-port``, and ``stm32loader.py`` to +respectively refer to the absolute paths to the bootloader binary +(from Step 1), the serial port device file or COMM port (from Steps 2 +and 3), and the stm32loader.py script. + +.. highlight:: sh + +You can run :: + + $ python stm32loader.py -h + +to obtain usage information. The incantation for uploading a +bootloader binary ``new-bootloader.bin`` is :: + + $ python stm32loader.py -p ser-port -evw new-boot.bin + +If all goes well, you'll see a bunch of output, then "Verification +OK". If something goes wrong, the `forum`_ is probably your best bet +for obtaining help, with IRC (irc.freenode.net, #leafblowers) being +another option. If all else fails, you can always `contact us +directly`_! diff --git a/source/compatibility.rst b/source/compatibility.rst index 7eb0a8f..a070b42 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -17,10 +17,13 @@ that the Maple uses a 32-bit ARM Cortex-M3 architecture chip while the Arduinos have 8-bit Atmel AVR chips. The different instruction set means that machine code (executable binary programs) is incompatible between the two, and a different compiler (actually just a different -version of `gcc `_) is required. The compiler for -the regular Arduino IDE is the popular :command:`avr-gcc` package; the -compiler for the Maple version of the IDE is CodeSourcery's edition of -gcc for the ARM EABI target (:command:`arm-non-eabi-gcc`). +version of `gcc `_) is required. + +The compiler for the regular Arduino IDE is the popular +:command:`avr-gcc` package; the compiler for the Maple version of the +IDE is CodeSourcery's edition of gcc for the ARM EABI target +(:command:`arm-non-eabi-gcc`). A (preliminary) reference on +:ref:`using arm-none-eabi-gcc ` is available. The bitwidth of the processor means that the Maple can process 32-bit operations (like adding two 32-bit integers) in a single instruction, @@ -45,8 +48,8 @@ numbered separately (A0-A5) from the digital pins (D0\ -D13). The incompatible hardware differences are: -* |i2c| port: on most Arduinos, the |i2c| port is Analog Input - 4 (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5 +* **I2C port**: on most Arduinos, the |i2c| port is Analog Input 4 + (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5 (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 (SDA). It should be possible to skywire, sacrificing signal quality (due to @@ -54,21 +57,22 @@ The incompatible hardware differences are: reasonably well in software. This peripheral could potentially be rerouted internally, but we haven't looked into it. -* :ref:`PWM ` on D10: all the other standard Arduino PWM headers have PWM - functionality on the Maple (D2,D3,D6,D9,D11), but not D10. We did - our best! It may be possible to reroute this peripheral internally - using low level configuration, but we haven't looked in to it. +* :ref:`PWM ` **on D10**: all the other standard Arduino PWM + headers have PWM functionality on the Maple (D2,D3,D6,D9,D11), but + not D10. We did our best! It may be possible to reroute this + peripheral internally using low level configuration, but we haven't + looked in to it. -* No External Voltage Reference: The Arduino has an Aref pin which +* **No External Voltage Reference**: The Arduino has an Aref pin which allows the use of an external ADC voltage reference; the Maple has an extra GPIO pin (14) with PWM capability in this spot, and does not allow an external voltage reference to be configured. -* EEPROM: the Maple does not have any internal EEPROM. This +* **EEPROM**: the Maple does not have any internal EEPROM. This functionality can be emulated with regular persistent flash memory, or with an external EEPROM chip. -* ISP Programming: the Maple does not use an ISP/ICSP bus for +* **ISP Programming**: the Maple does not use an ISP/ICSP bus for debugging; it uses :ref:`JTAG `. @@ -76,14 +80,18 @@ Software Language/Library Changes --------------------------------- With :ref:`a few exceptions `, the entire -Arduino language is supported. However, there are some subtle +Wiring/Arduino language is supported. However, there are some subtle differences, most of which are improvements: -* 32-bit integers: many standard functions either expect or return +* **32-bit integers**: many standard functions either expect or return full 32-bit (4 byte) integer values instead of the regular 16-bit (2 byte) Arduino values. -* :ref:`pinMode() ` types: any :ref:`GPIO ` +* **64-bit doubles**: The :ref:`double ` type is a full + double-precision floating point type on the Maple; it is a + single-precision floating point value on the Arduino. + +* :ref:`pinMode() ` **types**: any :ref:`GPIO ` (including analog pins) can be configured into one of the following modes with a single call to ```pinMode()``: ``OUTPUT``, ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``, @@ -91,41 +99,162 @@ differences, most of which are improvements: be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the :ref:`GPIO documentation ` for more information. -* ``Serial1`` syntax: like the `Arduino Mega +* :ref:`Serial port ` **syntax**: like the `Arduino Mega `_, the Maple has multiple :ref:`USART ports `. By default, ``Serial`` is not mapped to any of them, use ``Serial1`` through ``Serial3`` instead. -* 16-bit :ref:`PWM `: Arduino boards support 8-bit PWM, which +* **16-bit** :ref:`PWM `: Arduino boards support 8-bit PWM, which means that calls to :ref:`analogWrite() ` take values between 0 (always off) and 255 (always on). The Maple supports 16-bit PWM, so the corresponding values should be between 0 (always off) and 65535 (always on). -* 12-bit :ref:`ADC `: Arduino boards support 10-bit ADC, which +* **12-bit** :ref:`ADC `: Arduino boards support 10-bit ADC, which means that calls to :ref:`analogRead() ` will return values between 0 and 1023. The Maple supports 12-bit ADC, so the same call will instead return values between 0 and 4095. -Stub (unfinished) +Shield and Device Compatibility +------------------------------- + +.. TODO update for 0.0.9 + +.. list-table:: + :header-rows: 1 + + * - Shield/Device + - Compatible? + - Notes + + * - Ethernet shield + - Yes! + - Tested; no library yet + + * - WiFi Shield + - Yes! + - Tested; no library yet (expected for 0.0.9) + + * - MIDI shield + - Yes! + - Tested; no library yet + + * - XBee shield + - Unknown + - + + * - Bluetooth shield + - Unknown + - + + * - Cellular shield + - Unknown + - + +Library Porting Status +---------------------- + +The state of currently ported Arduino libraries is the +:ref:`libraries`. + +.. TODO update for 0.0.9; update as libraries are ported. + +.. list-table:: + :header-rows: 1 + + * - Library + - Ported? + - Notes + + * - Wire + - Preliminary + - In progress; see :ref:`library reference `. + + * - LiquidCrystal + - **Yes** + - :ref:`Included since IDE 0.0.7 ` + + * - Ethernet + - Not yet + - Planned -.. class:: ported-feature + * - EEPROM + - No + - The Maple doesn't have EEPROM; use flash instead. Perhaps this + library could be emulated? -I am supported! + * - Firmata + - Not yet + - Planned -This should be ordinary + * - Matrix + - Not yet + - Planned -.. class:: non-ported-feature + * - SoftwareSerial + - Not yet + - Planned -I can't do it :( + * - Sprite + - Not yet + - Planned -Also ordinary + * - Stepper + - Not yet + - Planned -.. class:: partly-ported-feature +Sketch and Library Porting HOWTO +-------------------------------- -I sorta work +In addition to the suggestions in this section, you may find many of +the individual :ref:`language reference ` pages useful. As +appropriate, these have "Arduino Compatibility" sections; one good +example is the :ref:`analogWrite() ` +function. -And I am also ordinary +- Check the hardware and header differences above, and see if your + project or shield needs to be modified (eg, add 3.3V level + converters or reroute PWM to header D10). +- Check for ported library functionality. We intend to port all of the + core and popular libraries (like Wire, Ethernet, and the LCD screen + driver), but this task is not yet finished. (Patches are welcome!) +- Check for peripheral conflicts; changing the configuration of timers + and bus speeds for a feature on one header may impact all the + features on that hardware "port". For example, changing the timer + prescaler to do long PWM pulses could impact |i2c| communications on + nearby headers. + +- Rewrite any low-level code. This could potentially be very + difficult, but hopefully you've used the Arduino libraries to + abstract away the registers and other hardware-specific + details. Your sketch probably doesn't have any low-level code; a + library which wraps a particular peripheral very well may. Some + help is available in the :ref:`arm-gcc` reference. + +- Redeclare variable sizes if necessary: generics like ``int`` will + probably work unless you depend on side-effects like rollover. + +- Check every ``pinMode()``: the Maple has more modes for GPIO + pins. For example, make sure to set analog pins to ``INPUT_ANALOG`` + before reading and PWM pins to ``PWM`` before writing. The full set + of pin modes is documented in the :ref:`lang-pinmode` reference. + +- Modify PWM writes: ``pinMode()`` must be set to ``PWM``, the + frequency of the PWM pulse configured, and the duty cycle written + with up to 16-bit resolution. + +- Modify ADC reads: :ref:`lang-analogread` takes the full pin number + (not 0-5) and returns a full 12-bit reading. The ADC pin must have + its ``pinMode()`` set to ``INPUT_ANALOG``. + +- Possibly convert all Serial-over-USB communications to use + :ref:`lang-serialusb` instead of a USART :ref:`serial port + `. The Maple has a dedicated USB port which is not + connected to the USART TX/RX pins in any way. + +- Check timing: Maple clock cycles are just 13.9 nanoseconds, though + the peripheral bus speeds (which limit GPIO output) are clocked + slower. diff --git a/source/epilog.rst b/source/epilog.rst index 4234dd9..e64103c 100644 --- a/source/epilog.rst +++ b/source/epilog.rst @@ -6,56 +6,3 @@ .. _forum: http://forums.leaflabs.com .. _contact: http://leaflabs.com/contact/ .. _contact us directly: http://leaflabs.com/contact/ - -.. Arduino built-in functions - -.. _setup(): http://arduino.cc/en/Reference/Setup -.. _loop(): http://arduino.cc/en/Reference/Loop - -.. _pinMode(): http://arduino.cc/en/Reference/PinMode -.. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite -.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead - -.. _analogReference(): http://arduino.cc/en/Reference/AnalogReference -.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead -.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite - -.. _tone(): http://arduino.cc/en/Reference/Tone -.. _noTone(): http://arduino.cc/en/Reference/NoTone -.. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut -.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn - -.. _millis(): http://arduino.cc/en/Reference/Millis -.. _micros(): http://arduino.cc/en/Reference/Micros -.. _delay(): http://arduino.cc/en/Reference/Delay -.. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds - -.. _min(): http://arduino.cc/en/Reference/Min -.. _max(): http://arduino.cc/en/Reference/Max -.. _abs(): http://arduino.cc/en/Reference/Abs -.. _constrain(): http://arduino.cc/en/Reference/Constrain - -.. _map(): http://arduino.cc/en/Reference/Map -.. _pow(): http://arduino.cc/en/Reference/Pow -.. _sqrt(): http://arduino.cc/en/Reference/Sqrt - -.. _sin(): http://arduino.cc/en/Reference/Sin -.. _cos(): http://arduino.cc/en/Reference/Cos -.. _tan(): http://arduino.cc/en/Reference/Tan - -.. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed -.. _random(): http://arduino.cc/en/Reference/Random - -.. _lowByte(): http://arduino.cc/en/Reference/LowByte -.. _highByte(): http://arduino.cc/en/Reference/HighByte -.. _bitRead(): http://arduino.cc/en/Reference/BitRead -.. _bitWrite(): http://arduino.cc/en/Reference/BitWrite -.. _bitSet(): http://arduino.cc/en/Reference/BitSet -.. _bitClear(): http://arduino.cc/en/Reference/BitClear -.. _bit(): http://arduino.cc/en/Reference/Bit - -.. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt -.. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt - -.. _interrupts(): http://arduino.cc/en/Reference/Interrupts -.. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts diff --git a/source/errata.rst b/source/errata.rst index 4b03513..a3bb66a 100644 --- a/source/errata.rst +++ b/source/errata.rst @@ -7,10 +7,148 @@ This page is a collection of known issues and warnings for each revision of the Maple board. The failure modes aren't design errors, but are easy ways to break or damage your board permanently. For a -list of differences between the Maple and Arduinos, see the page on -:ref:`compatibility `. +list of differences between the Maple and Arduinos, see the +:ref:`compatibility reference `. .. contents:: Contents :local: -Stub. +Maple Rev 5 +----------- + +These boards went on sale in November 2010. They have white buttons, +and "r5" in small print near the "LeafLabs Maple" text next to the +"infinity-leaf" logo, among other changes: + +.. figure:: /_static/img/maple_rev5.png + :align: center + :alt: Maple Rev 5 + +Known issues: + +* **GPIO 39-43 not configured**: this is really more of a software + "TODO" item. Some of the JTAG header pins are numbered 39-43. These + STM32 pins are indeed fully functional :ref:`GPIO ` when the a + :ref:`JTAG ` device is not connected, but we have not enabled + them in software and thus they can not be accessed with the regular + :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. + +Potential failure modes: + +* **TTL voltage on non-tolerant pins**: not all header pins are 5V + compatible; connecting certain serial devices in the wrong way could + over voltage the pins. The :ref:`Pin-Mapping Mega Table + ` details which pins are 5V-tolerant. + +Maple Rev 3 +----------- + +This batch of boards went on sale beginning in May 2010. They have a +darker red silkscreen and the "infinity-leaf" logo: + +.. figure:: /_static/img/maple_rev3.png + :align: center + :alt: Maple Rev 3 + +Known issues: + +* **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 + have questionable RESET and BUT buttons. + + What seems to have happened is that the flux remover we used to + clean the boards before shipping eroded the plastic internals, which + resulted in intermittent functionality. All buttons on all shipped + boards did function in testing, but some may have been unreliable in + regular use. + + If you have this problem, we will be happy to ship you new buttons + if you think you can re-solder them yourself, or you can ship us + your board and we will swap out that part. + + For reference, the button part number is KMR211GLFS and the flux + remover we used is "Precision Electronics Cleaner" from RadioShack, + which is "Safe on most plastics" and contains Dipropylene glycol + monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol + methyl ether acetate (really?), and carbon dioxide. + +* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on + USART2 (:ref:`Serial2 `), have resistors in-line + between the STM32 and the headers. These resistors increase the + impedance of the lines for ADC reads and affect the open drain GPIO + functionality of the pins. + + These resistors were accidentally copied over from older Arduino USB + designs, where they appear to protect the USB-Serial converter from + TTL voltage on the headers. + +* **GPIO 39-43 not configured**: this is really more of a software + "TODO" item. Some of the JTAG header pins are numbered 39-43. These + STM32 pins are indeed fully functional :ref:`GPIO ` when the a + :ref:`JTAG ` device is not connected, but we have not enabled + them in software and thus they can not be accessed with the regular + :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. + +* **Silkscreen Errors**: the silkscreen on the bottom indicated PWM + functionality on pin 25 and listen the external header GND pin as + number 38 (actually 38 is connected to the BUT button). We manually + sharpied over both of these mistakes. + +* **PWM Marketing Mistake**: We originally sold the Maple advertising + 22 channels of 16-bit hardware PWM; actually the Maple only has 15. + +Potential failure modes: + +* **TTL voltage on non-tolerant pins**: not all header pins are 5V + compatible; connecting certain serial devices in the wrong way could + over voltage the pins. The :ref:`Pin-Mapping Mega Table + ` details which pins are 5V-tolerant. + +Maple Rev 1 +----------- + +This batch of 100 boards shipped in later 2009. They have a red +silkscreen and the logo is a single pixelated leaf: + +.. figure:: /_static/img/maple_rev1.png + :align: center + :alt: Maple Rev 1 + +Known issues: + +* **ADC noise**: generally very high, in particular when the USB port + is being used for communications (including keep-alive pings when + connected to a computer). + + This issue was resolved in Rev 3 with a 4-layer design and a + geometrically isolated ADC V\ :sub:`ref` plane. + +* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on + USART2 (:ref:`Serial2 `), have resistors in-line + between the STM32 and the headers. These resistors increase the + impedance of the lines for ADC reads and affect the open drain GPIO + functionality of the pins. + + These resistors were accidentally copied over from older Arduino USB + designs, where they appear to protect the USB-Serial converter from + TTL voltage on the headers. + +* **Silkscreen Differences**: the pin numbering scheme on Rev 1 is + different from Rev 3, and thus Rev 3 software is difficult to use + with Rev 1 boards. Notably, the analog input bank is labeled A0-A4 + on Rev 1 but 15-20 on Rev 3, and the extra header bank does not have + a pinout table on the bottom. + +* **No BUT Button**: the BUT button, useful for serial bootloading, + was only added in Rev 3. As a workaround, you can directly short the + appropriate MCU pin to Vcc; see `this forum posting + `_. + +* **PWM Marketing Mistake**: We originally sold the Maple advertising + 22 channels of 16-bit hardware PWM; actually the Maple only has 15. + +Potential failure modes: + +* **TTL voltage on non-tolerant pins**: not all header pins are 5v + compatible; connecting certain serial devices in the wrong way could + over voltage the pins. The :ref:`Pin-Mapping Mega Table + ` details which pins are 5V-tolerant. diff --git a/source/hardware.rst b/source/hardware.rst deleted file mode 100644 index 1fa3554..0000000 --- a/source/hardware.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _hardware: - -================================= - Hardware-Specific Documentation -================================= - -This page indexes the Maple's capabilities for interacting with -external hardware peripherals. For information about a particular -device or protocol, see its individual reference page. - -Individual reference pages: - -.. toctree:: - :maxdepth: 2 - - i2c - pwm - gpio - usb - jtag - adc - spi - usart - timers diff --git a/source/ide.rst b/source/ide.rst index 00dcf03..f38f6cd 100644 --- a/source/ide.rst +++ b/source/ide.rst @@ -1,23 +1,130 @@ .. _ide: -Maple IDE Documentation -======================= +Maple IDE +========= -Stub. +.. figure:: /_static/img/ide-blinky.png + :align: center + :alt: Maple IDE -.. TODO stub sections for all the other buttons, etc. +This page documents the basic functionality of the Maple IDE. +Specifically, it describes the operation of the buttons on the main +toolbar. It is expected to become more comprehensive over time. -.. _ide-serial-monitor: - -Serial Monitor --------------- +The :ref:`Maple Quickstart ` is another source of +information on the IDE; it is especially useful for setting up a +computer for the first time. .. _ide-verify: Verify ------ +.. image:: /_static/img/button-verify.png + :align: left + +Click Verify to compile the current sketch. + +.. _ide-stop: + +Stop +---- + +.. image:: /_static/img/button-stop.png + +Click Stop to cancel a compilation. + +.. _ide-new: + +New +--- + +.. image:: /_static/img/button-new.png + +Click New to begin a fresh sketch. + +.. _ide-open: + +Open +---- + +.. image:: /_static/img/button-open.png + +Click Open to open a new sketch. By default, this will look in you +*sketchbook*, which is a directory on your system which contains all +of your sketches. The default directory of your sketchbook varies by +operating system; you can change it in the IDE preferences. + +.. _ide-save: + +Save +---- + +.. image:: /_static/img/button-save.png + +Click Save to save the currently opened sketch. + .. _ide-upload: Upload ------ + +.. image:: /_static/img/button-upload.png + +Click Upload to send the compiled sketch to your Maple to run. Before +you click Upload, you must have a memory location and serial port +selected. The memory location, either Flash or RAM, determines +whether the compiled sketch binary will be stored on the Maple. You +can choose this using the Tools > Board menu. The serial port +corresponds to the Serial-over-USB connection the Maple has +established with your computer. This looks like "COM1", "COM2", +etc. on Windows, "/dev/tty.usbmodemXXX" on Mac (where "XXX" is some +sequence of letters and numbers), or "/dev/ttyACMXXX" on Linux (again, +where "XXX" is some sequence of letters and numbers). You can choose +a serial port using the Tools > Serial Port menu. + +If you click Upload without having made these choices; The IDE +*should* prompt you to do so. However, if you're trying to upload and +are unsuccessful, make sure you've made choices for both board and +serial port. + +For more help, the upload process is documented in more detail (with +screenshots) in the :ref:`quickstart `. + +If all else fails, try putting your Maple in :ref:`perpetual +bootloader mode ` before +uploading. + +In any case, you can always find us on the `forum`_ or `contact us +directly`_. + +.. _ide-serial-monitor: + +Serial Monitor +-------------- + +.. image:: /_static/img/button-serial-monitor.png + +Click Serial Monitor to open up a communications channel between your +PC and the Maple's :ref:`Serial-over-USB ` +(``SerialUSB``) virtual serial port. + +If the serial monitor is open, any information sent to the computer +(e.g. using :ref:`SerialUSB.println() ` will +be displayed in the large text area. You can send data to the Maple +(to be read with e.g. :ref:`SerialUSB.read() `) +by typing into the small text box and either hitting the Enter key or +pressing the Send button. + +Here is an example serial monitor session with the InteractiveTest +sketch (which you can load in the IDE by choosing menu item File > +Examples > Maple > InteractiveTest): + +.. image:: /_static/img/serial-monitor.png + +This is the result of typing "?" in the text box and clicking Send. + +.. note:: You cannot upload a sketch while the serial monitor is open. + If you click :ref:`Upload ` while the serial monitor is + open, the IDE will close it for you before proceeding with the + upload. diff --git a/source/index.rst b/source/index.rst index 32fa28f..42d1bd0 100644 --- a/source/index.rst +++ b/source/index.rst @@ -17,7 +17,7 @@ If you're having problems, you might want to visit the `_ to ask questions to the LeafLabs team and other Maple users. Good luck, and have fun! -Table of contents: +General documentation: .. toctree:: :maxdepth: 1 @@ -30,15 +30,24 @@ Table of contents: Library Reference Command-Line Tools and APIs Troubleshooting - Hardware-Specific Documentation External Interrupts Bootloader Known Problems Language Reference Index -Indices and tables -================== +.. _index-hardware: -* :ref:`genindex` -* :ref:`search` +Hardware features: +.. toctree:: + :maxdepth: 1 + + i2c + pwm + gpio + usb + jtag + adc + spi + usart + timers diff --git a/source/jtag.rst b/source/jtag.rst index 9b8ee14..7cfba5f 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -32,7 +32,7 @@ Wiring Diagram JTAG wiring diagram to connect a standard 20-pin ARM JTAG device to the 8-pin JTAG port on the Maple. -.. TODO jtag wiring diagram (above) looks terrible; replace it +.. FIXME jtag wiring diagram (above) looks terrible; replace it The Maple has holes for a 8-pin JTAG header but that header is not soldered on by default. If you know ahead of time that you'll be @@ -56,8 +56,7 @@ Compatible Devices We have had good experience with the `Olimex ARM-USB-OCD `_ device, which costs -about 55 euro plus shipping (as of October 2010). - +about 55 euro plus shipping (as of November 2010). Recommended Reading ------------------- diff --git a/source/lang/analogwrite.rst b/source/lang/analogwrite.rst index 3d05f44..2c50a42 100644 --- a/source/lang/analogwrite.rst +++ b/source/lang/analogwrite.rst @@ -25,6 +25,8 @@ analogWrite() .. contents:: Contents :local: +.. _lang-analogwrite-compatibility: + Arduino Compatibility --------------------- diff --git a/source/lang/serial.rst b/source/lang/serial.rst index f96547d..ca89b31 100644 --- a/source/lang/serial.rst +++ b/source/lang/serial.rst @@ -20,25 +20,24 @@ pins summarized in the following table: :header-rows: 1 * - Serial port - - Pins (TX, RX) + - TX, RX, CK + - CTS, RTS (if present) * - ``Serial1`` - - 7, 8 + - 7, 8, 6 + - * - ``Serial2`` - - 1, 0 + - 1, 0, 10 + - 2, 3 * - ``Serial3`` - - 29, 30 + - 29, 30, 31 + - 32, 33 Thus, if you use a particular serial port, you cannot also use its communication pins for other purposes at the same time. -Unlike the Arduino, none of these serial ports is connected to the USB -port on the Maple board. Thus, to use these pins to communicate with -your personal computer, you will need an additional USB-to-serial -adaptor. - If you want to communicate with the Maple using the provided USB port, use :ref:`SerialUSB ` instead. @@ -60,8 +59,8 @@ means that you can use any of these functions on any of ``Serial1``, .. cpp:class:: HardwareSerial - Serial port class. Predefined instances are Serial1, Serial2, and - Serial3. + Serial port class. Predefined instances are ``Serial1``, + ``Serial2``, and ``Serial3``. .. cpp:function:: HardwareSerial::begin(unsigned int baud) @@ -73,7 +72,7 @@ means that you can use any of these functions on any of ``Serial1``, .. cpp:function:: HardwareSerial::end() Disables the USART associated with this object, allowing any - associated TX and RX pins to be used for other purposes. + associated communication pins to be used for other purposes. .. cpp:function:: unsigned int HardwareSerial::available() @@ -203,6 +202,14 @@ means that you can use any of these functions on any of ``Serial1``, ``println()`` functions is likely to be more useful when printing multiple characters, when formatting numbers for printing, etc. +Arduino Compatibility Note +-------------------------- + +Unlike the Arduino, none of the Maple's serial ports is connected to +the USB port on the Maple board (for that, use :ref:`SerialUSB +`). Thus, to use these pins to communicate with your +personal computer, you will need an additional USB-to-serial adaptor. + .. TODO LATER port these examples over .. Examples diff --git a/source/lang/serialusb.rst b/source/lang/serialusb.rst index 9beee82..af3a7e0 100644 --- a/source/lang/serialusb.rst +++ b/source/lang/serialusb.rst @@ -71,6 +71,8 @@ world!")``. Returns the number of bytes available for reading. +.. _lang-serialusb-read: + .. cpp:function:: unsigned char USBSerial::read() Returns the next available, unread character. If there are no diff --git a/source/lang/unimplemented/stringclass.rst b/source/lang/unimplemented/stringclass.rst index cdd385d..b893e83 100644 --- a/source/lang/unimplemented/stringclass.rst +++ b/source/lang/unimplemented/stringclass.rst @@ -3,7 +3,4 @@ String Class ============ -Stub. - - .. include:: /lang/cc-attribution.txt diff --git a/source/language.rst b/source/language.rst index 350b0c3..463041e 100644 --- a/source/language.rst +++ b/source/language.rst @@ -222,8 +222,6 @@ more exhaustive index is available at the :ref:`language-index`. Missing Arduino Features ------------------------ -Stub TODO: fill in other missing features - **analogReference()** It is not possible to implement this function on the Maple @@ -252,6 +250,20 @@ Stub TODO: fill in other missing features typedef uint16 word; +Unimplemented Arduino Features +------------------------------ + +The following Wiring/Arduino features are currently unimplemented on +the Maple. However, they will be present in future versions: + +- `interrupts() `_ +- `noInterrupts() `_ +- `noTone() `_ +- `pulseIn() `_ +- `shiftOut() `_ +- `String `_ +- `tone() `_ + .. _our reference page: http://leaflabs.com/docs/external-interrupts/ .. _newlib: http://sourceware.org/newlib/ diff --git a/source/libmaple-api.rst b/source/libmaple-api.rst deleted file mode 100644 index d5b90b6..0000000 --- a/source/libmaple-api.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _libmaple_api: - -======================== - libmaple API reference -======================== - -This page documents the lower-level features of libmaple, which may be -of use to programmers who don't wish to use the Arduino-style -environment provided by the `Maple IDE `_. - -Stub. diff --git a/source/libmaple.rst b/source/libmaple.rst index b161afb..b76c7c8 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -2,19 +2,19 @@ .. _libmaple: -==================== - libmaple Reference -==================== +``libmaple`` Reference +====================== .. image:: /_static/img/libmaple-screenshot-small.png :align: center :alt: libmaple screenshot -`LeafLabs libmaple `_ is the low level library we have developed for for the ARM -Cortex-M3 chips manufactured by STMicroelectronics used in the Maple -boards (the `STM32F103x`_ series). We found the generic peripheral -libraries too painful to build on top of, and reimplemented the -functionality we needed in a simpler (and less general) form. +`LeafLabs libmaple `_ is the low level library we +have developed for for the ARM Cortex-M3 chips manufactured by +STMicroelectronics used in the Maple boards (the `STM32F103x`_ +series). We found the generic peripheral libraries too painful to +build on top of, and reimplemented the functionality we needed in a +simpler (and less general) form. .. _libmaple-libmaple: http://github.com/leaflabs/libmaple .. _STM32F103x: http://www.st.com/stonline/stappl/productcatalog/app?path=/pages/stcom/PcStComPartNumberSearch.searchPartNumber&search=stm32f103 @@ -22,7 +22,7 @@ functionality we needed in a simpler (and less general) form. This library is transparently included in the `Maple IDE `_, but we develop it separately using good old Unix command line tools and release it for advanced -users who might chafe at the “sketch” programming model of the +users who might chafe at the "sketch" programming model of the IDE. Included are some examples, a Makefile, and the compatibility wrappers and code to imitate the Arduino programming library. @@ -36,5 +36,7 @@ wrappers and code to imitate the Arduino programming library. :maxdepth: 2 Unix Toolchain Quickstart - libmaple API reference Guide to using GCC's ARM target + +.. TODO LATER create, style, and host a pure Doxygen libmaple +.. reference docs. This implies determining a stable API. diff --git a/source/libraries.rst b/source/libraries.rst index 6ecdf07..4c87539 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -7,6 +7,9 @@ Maple Library Reference ========================= +.. Note: if you port an Arduino library and document it here, be sure +.. to update compatibility.rst to reflect that fact. + This page briefly summarizes the Arduino libraries that have been ported to Maple. You can use a library from within a sketch by going to Sketch > Import Library... from within the IDE, then choosing the diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 6d99a4a..ca902f3 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -66,6 +66,8 @@ bottom window, and then a confirmation message will appear: :align: center :alt: Code verified successfully. +.. _maple-quickstart-upload: + Upload that program! -------------------- @@ -127,7 +129,7 @@ OS X: :alt: Board type and serial port for the OS X Then press the "Upload" button to upload your program to the -Maple. +Maple. .. image:: /_static/img/upload-button.png :align: center diff --git a/source/pwm.rst b/source/pwm.rst index 42dc1a5..fd72842 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -1,10 +1,9 @@ .. _pwm: -============================== - Pulse-Width Modulation (PWM) -============================== +PWM +=== -Pulse Width Modulation is a basic technique to create repeated square +Pulse Width Modulation (PWM) is a basic technique to create repeated square waves (digital high/low voltage transitions) of user defined length and duty cycle. It can be used as a way to encode an "analog" signal on a single digital (high/low) line using the time between transitions @@ -42,7 +41,7 @@ to track down exactly which timer *channel* corresponds to each pin. Timer1 | D6,D7,D8 Timer2 | D0,D1,D2,D3 Timer3 | D11,D12,D27,D28 - Timer4 | D5,D9,D14,D24 + Timer4 | D5,D9,D14,D24 Background ---------- @@ -96,11 +95,11 @@ Function Reference ``pinMode(pin_num, PWM)`` - This command is usually called from `setup()`_ to tell the - microcontroller that pin_num should be configured to PWM - output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` is - also available (see the list of :ref:`GPIO modes ` for - more information). + This command is usually called from :ref:`setup() ` to + tell the microcontroller that pin_num should be configured to PWM + output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` + is also available (see the list of :ref:`GPIO modes ` + for more information). .. _pwm-pwmwrite: @@ -144,8 +143,8 @@ Function Reference For instance, an 8MHz frequency can be achieved by setting ``prescale`` to 9, since 72MHz / 9 = 8MHz. - This function is normally called once from, `setup()`_, but the - timer can be reconfigured with a new prescaler at any time. + This function is normally called once from, :ref:`lang-setup`, but + the timer can be reconfigured with a new prescaler at any time. * Configure the prescaler and overflow values to generate a timer * reload with a period as close to the given number of diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 7b80a3f..0c10d01 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -41,8 +41,8 @@ My 5v peripheral doesn't work! (I2C, SPI, USART, etc) Yup, the Maple is a 3.3v board. You may need to use a level converter. See the :ref:`compatibility `, :ref:`GPIO -`, or other :ref:`hardware specific documentation ` -for more information. +`, or other :ref:`hardware specific documentation +` for more information. The reset and D38/serial buttons don't seem to work reliably! ------------------------------------------------------------- diff --git a/source/usart.rst b/source/usart.rst index 19b054f..c0334a9 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -10,82 +10,18 @@ Hardware/Circuit Design ----------------------- -The Maple has 3 separate USART devices: ``Serial1``, ``Serial2``, and -``Serial3``. In the most simple use case, the RX and TX pins are used -to send data at a predetermined baudrate with the line voltage level -relative to ground. - -+-----------+--------+-----+ -|Port |Function|Pin | -+===========+========+=====+ -|``Serial1``|TX |D7 | -| | | | -| |RX |D8 | -| | | | -| |CK |D6 | -+-----------+--------+-----+ -|``Serial2``|TX |D1 | -| | | | -| |RX |D0 | -| | | | -| |CK |D10 | -| | | | -| |CTS |D2 | -| | | | -| |RTS |D3 | -+-----------+--------+-----+ -|``Serial3``|TX |D29 | -| | | | -| |RX |D30 | -| | | | -| |CK |D31 | -| | | | -| |CTS |D32 | -| | | | -| |RTS |D33 | -+-----------+--------+-----+ - -.. TODO make above less ugly +The Maple has 3 separate USART devices. In the most simple use case, +the RX and TX pins are used to send data at a predetermined baudrate +with the line voltage level relative to ground. Their usage is +documented in the :ref:`Serial Ports ` language reference +page. Compatible Devices and Specifications ------------------------------------- -We have successfully used the Maple USART ports with an FT232R-based USB-serial converter at up to 115200 baud; higher speeds should certainly be possible. - -Function Reference ------------------- - -In the following, you may replace ``SerialN`` with ``Serial1``, -``Serial2``, or ``Serial3``. - -``SerialN.begin(baudrate)`` - - ``SerialN.begin`` is usually called in `setup()`_ to configure the - baudrate of the given serial port and to set up the header pins - appropriately. It can be called at any time to reconfigure a port - or to change the baudrate. 9600 baud is the generic speed most - widely supported by other devices and terminals. - -``SerialN.print(...)``/\ ``SerialN.println(...)`` - - Writes data into the port buffer to be transmitted as soon as - possible. Accepts strings (``char*``). If a raw integer is - passed, the corresponding ASCII character will be transmitted; to - print out a number in human readable form add a second parameter - with the base system. - - For example, to print out the decimal number '1234' use - ``SerialN.print(1234, DEC)``; to print out the binary number - '1001', use ``SerialN.print(9, BIN)``. - -``SerialN.available()``/\ ``SerialN.read()`` - - ``SerialN.read()`` will return the next unread character that has - been received over the port. ``SerialN.available()`` returns how - many such bytes are available (or zero if none are). If none are - available, ``SerialN.read()`` will block/fail, so the usual - program structure is to poll with ``SerialN.available`` and only - read if a nonzero value is returned. +We have successfully used the Maple USART ports with an FT232R-based +USB-serial converter at up to 115200 baud; higher speeds should +certainly be possible. Recommended Reading ------------------- -- cgit v1.2.3 From 5a7dd1bea32458a4afc038984a903959134b82d3 Mon Sep 17 00:00:00 2001 From: Hanna Mendes Levitin Date: Wed, 1 Dec 2010 03:37:07 -0600 Subject: docs, now with style --- source/_static/apilist.html | 5 + source/_static/img/round_logo_32x32.ico | Bin 0 -> 4286 bytes source/_static/img/round_logo_60x60.png | Bin 0 -> 5552 bytes source/conf.py | 45 +++-- source/confDefaultGreen.txt | 250 ++++++++++++++++++++++++++ source/cpp.rst | 13 ++ source/home.rst | 33 ++++ source/home.rtf | 43 +++++ source/ide.rst | 16 +- source/index.rst | 61 ++++--- source/lang/api/abs.rst | 49 +++++ source/lang/api/analogread.rst | 154 ++++++++++++++++ source/lang/api/analogwrite.rst | 169 ++++++++++++++++++ source/lang/api/attachinterrupt.rst | 102 +++++++++++ source/lang/api/bit.rst | 44 +++++ source/lang/api/bitclear.rst | 44 +++++ source/lang/api/bitread.rst | 46 +++++ source/lang/api/bitset.rst | 46 +++++ source/lang/api/bitwrite.rst | 46 +++++ source/lang/api/cc-attribution.txt | 9 + source/lang/api/constants.rst | 304 ++++++++++++++++++++++++++++++++ source/lang/api/constrain.rst | 69 ++++++++ source/lang/api/cos.rst | 32 ++++ source/lang/api/delay.rst | 72 ++++++++ source/lang/api/delaymicroseconds.rst | 65 +++++++ source/lang/api/detachinterrupt.rst | 37 ++++ source/lang/api/digitalread.rst | 58 ++++++ source/lang/api/digitalwrite.rst | 68 +++++++ source/lang/api/highbyte.rst | 59 +++++++ source/lang/api/loop.rst | 45 +++++ source/lang/api/lowbyte.rst | 25 +++ source/lang/api/map.rst | 68 +++++++ source/lang/api/max.rst | 65 +++++++ source/lang/api/micros.rst | 46 +++++ source/lang/api/millis.rst | 52 ++++++ source/lang/api/min.rst | 66 +++++++ source/lang/api/pinmode.rst | 77 ++++++++ source/lang/api/pow.rst | 23 +++ source/lang/api/pwmwrite.rst | 49 +++++ source/lang/api/random.rst | 73 ++++++++ source/lang/api/randomseed.rst | 60 +++++++ source/lang/api/serial.rst | 226 ++++++++++++++++++++++++ source/lang/api/serialusb.rst | 242 +++++++++++++++++++++++++ source/lang/api/setup.rst | 29 +++ source/lang/api/sin.rst | 32 ++++ source/lang/api/sq.rst | 46 +++++ source/lang/api/tan.rst | 31 ++++ source/lang/api/volatile.rst | 65 +++++++ source/lang/cpp/arithmetic.rst | 127 +++++++++++++ source/lang/cpp/array.rst | 123 +++++++++++++ source/lang/cpp/assignment.rst | 70 ++++++++ source/lang/cpp/bitshift.rst | 144 +++++++++++++++ source/lang/cpp/bitwisemath.rst | 186 +++++++++++++++++++ source/lang/cpp/boolean.rst | 91 ++++++++++ source/lang/cpp/booleanvariables.rst | 54 ++++++ source/lang/cpp/break.rst | 35 ++++ source/lang/cpp/byte.rst | 34 ++++ source/lang/cpp/bytecast.rst | 50 ++++++ source/lang/cpp/cc-attribution.txt | 9 + source/lang/cpp/char.rst | 50 ++++++ source/lang/cpp/charcast.rst | 36 ++++ source/lang/cpp/comments.rst | 67 +++++++ source/lang/cpp/comparison.rst | 87 +++++++++ source/lang/cpp/compoundarithmetic.rst | 44 +++++ source/lang/cpp/compoundbitwise.rst | 231 ++++++++++++++++++++++++ source/lang/cpp/const.rst | 52 ++++++ source/lang/cpp/continue.rst | 32 ++++ source/lang/cpp/curly-braces.rst | 109 ++++++++++++ source/lang/cpp/define.rst | 56 ++++++ source/lang/cpp/double.rst | 48 +++++ source/lang/cpp/doublecast.rst | 27 +++ source/lang/cpp/dowhile.rst | 27 +++ source/lang/cpp/enum.rst | 53 ++++++ source/lang/cpp/float.rst | 50 ++++++ source/lang/cpp/floatcast.rst | 28 +++ source/lang/cpp/for.rst | 142 +++++++++++++++ source/lang/cpp/goto.rst | 130 ++++++++++++++ source/lang/cpp/if.rst | 121 +++++++++++++ source/lang/cpp/include.rst | 72 ++++++++ source/lang/cpp/increment.rst | 37 ++++ source/lang/cpp/int.rst | 64 +++++++ source/lang/cpp/intcast.rst | 29 +++ source/lang/cpp/keywords.rst | 205 +++++++++++++++++++++ source/lang/cpp/long.rst | 52 ++++++ source/lang/cpp/longcast.rst | 27 +++ source/lang/cpp/modulo.rst | 70 ++++++++ source/lang/cpp/numeric-types.rst | 79 +++++++++ source/lang/cpp/pointer.rst | 31 ++++ source/lang/cpp/return.rst | 61 +++++++ source/lang/cpp/scope.rst | 120 +++++++++++++ source/lang/cpp/semicolon.rst | 25 +++ source/lang/cpp/sizeof.rst | 64 +++++++ source/lang/cpp/sqrt.rst | 25 +++ source/lang/cpp/static.rst | 57 ++++++ source/lang/cpp/string.rst | 128 ++++++++++++++ source/lang/cpp/switchcase.rst | 118 +++++++++++++ source/lang/cpp/unsignedchar.rst | 33 ++++ source/lang/cpp/unsignedint.rst | 55 ++++++ source/lang/cpp/unsignedlong.rst | 41 +++++ source/lang/cpp/variables.rst | 170 ++++++++++++++++++ source/lang/cpp/void.rst | 31 ++++ source/lang/cpp/while.rst | 38 ++++ source/language-index.rst | 34 ++-- source/language.rst | 10 +- source/libraries.rst | 4 +- source/specs.rst | 28 +++ 106 files changed, 7224 insertions(+), 56 deletions(-) create mode 100644 source/_static/apilist.html create mode 100644 source/_static/img/round_logo_32x32.ico create mode 100644 source/_static/img/round_logo_60x60.png create mode 100644 source/confDefaultGreen.txt create mode 100644 source/cpp.rst create mode 100644 source/home.rst create mode 100644 source/home.rtf create mode 100644 source/lang/api/abs.rst create mode 100644 source/lang/api/analogread.rst create mode 100644 source/lang/api/analogwrite.rst create mode 100644 source/lang/api/attachinterrupt.rst create mode 100644 source/lang/api/bit.rst create mode 100644 source/lang/api/bitclear.rst create mode 100644 source/lang/api/bitread.rst create mode 100644 source/lang/api/bitset.rst create mode 100644 source/lang/api/bitwrite.rst create mode 100644 source/lang/api/cc-attribution.txt create mode 100644 source/lang/api/constants.rst create mode 100644 source/lang/api/constrain.rst create mode 100644 source/lang/api/cos.rst create mode 100644 source/lang/api/delay.rst create mode 100644 source/lang/api/delaymicroseconds.rst create mode 100644 source/lang/api/detachinterrupt.rst create mode 100644 source/lang/api/digitalread.rst create mode 100644 source/lang/api/digitalwrite.rst create mode 100644 source/lang/api/highbyte.rst create mode 100644 source/lang/api/loop.rst create mode 100644 source/lang/api/lowbyte.rst create mode 100644 source/lang/api/map.rst create mode 100644 source/lang/api/max.rst create mode 100644 source/lang/api/micros.rst create mode 100644 source/lang/api/millis.rst create mode 100644 source/lang/api/min.rst create mode 100644 source/lang/api/pinmode.rst create mode 100644 source/lang/api/pow.rst create mode 100644 source/lang/api/pwmwrite.rst create mode 100644 source/lang/api/random.rst create mode 100644 source/lang/api/randomseed.rst create mode 100644 source/lang/api/serial.rst create mode 100644 source/lang/api/serialusb.rst create mode 100644 source/lang/api/setup.rst create mode 100644 source/lang/api/sin.rst create mode 100644 source/lang/api/sq.rst create mode 100644 source/lang/api/tan.rst create mode 100644 source/lang/api/volatile.rst create mode 100644 source/lang/cpp/arithmetic.rst create mode 100644 source/lang/cpp/array.rst create mode 100644 source/lang/cpp/assignment.rst create mode 100644 source/lang/cpp/bitshift.rst create mode 100644 source/lang/cpp/bitwisemath.rst create mode 100644 source/lang/cpp/boolean.rst create mode 100644 source/lang/cpp/booleanvariables.rst create mode 100644 source/lang/cpp/break.rst create mode 100644 source/lang/cpp/byte.rst create mode 100644 source/lang/cpp/bytecast.rst create mode 100644 source/lang/cpp/cc-attribution.txt create mode 100644 source/lang/cpp/char.rst create mode 100644 source/lang/cpp/charcast.rst create mode 100644 source/lang/cpp/comments.rst create mode 100644 source/lang/cpp/comparison.rst create mode 100644 source/lang/cpp/compoundarithmetic.rst create mode 100644 source/lang/cpp/compoundbitwise.rst create mode 100644 source/lang/cpp/const.rst create mode 100644 source/lang/cpp/continue.rst create mode 100644 source/lang/cpp/curly-braces.rst create mode 100644 source/lang/cpp/define.rst create mode 100644 source/lang/cpp/double.rst create mode 100644 source/lang/cpp/doublecast.rst create mode 100644 source/lang/cpp/dowhile.rst create mode 100644 source/lang/cpp/enum.rst create mode 100644 source/lang/cpp/float.rst create mode 100644 source/lang/cpp/floatcast.rst create mode 100644 source/lang/cpp/for.rst create mode 100644 source/lang/cpp/goto.rst create mode 100644 source/lang/cpp/if.rst create mode 100644 source/lang/cpp/include.rst create mode 100644 source/lang/cpp/increment.rst create mode 100644 source/lang/cpp/int.rst create mode 100644 source/lang/cpp/intcast.rst create mode 100644 source/lang/cpp/keywords.rst create mode 100644 source/lang/cpp/long.rst create mode 100644 source/lang/cpp/longcast.rst create mode 100644 source/lang/cpp/modulo.rst create mode 100644 source/lang/cpp/numeric-types.rst create mode 100644 source/lang/cpp/pointer.rst create mode 100644 source/lang/cpp/return.rst create mode 100644 source/lang/cpp/scope.rst create mode 100644 source/lang/cpp/semicolon.rst create mode 100644 source/lang/cpp/sizeof.rst create mode 100644 source/lang/cpp/sqrt.rst create mode 100644 source/lang/cpp/static.rst create mode 100644 source/lang/cpp/string.rst create mode 100644 source/lang/cpp/switchcase.rst create mode 100644 source/lang/cpp/unsignedchar.rst create mode 100644 source/lang/cpp/unsignedint.rst create mode 100644 source/lang/cpp/unsignedlong.rst create mode 100644 source/lang/cpp/variables.rst create mode 100644 source/lang/cpp/void.rst create mode 100644 source/lang/cpp/while.rst create mode 100644 source/specs.rst diff --git a/source/_static/apilist.html b/source/_static/apilist.html new file mode 100644 index 0000000..e9eb8e3 --- /dev/null +++ b/source/_static/apilist.html @@ -0,0 +1,5 @@ +{# Filename: .static/apilist.html #} +{% set parents = parents.pop() %} +{% if parents %} +{{ parents.title }} +{% endif %} \ No newline at end of file diff --git a/source/_static/img/round_logo_32x32.ico b/source/_static/img/round_logo_32x32.ico new file mode 100644 index 0000000..29fb2bf Binary files /dev/null and b/source/_static/img/round_logo_32x32.ico differ diff --git a/source/_static/img/round_logo_60x60.png b/source/_static/img/round_logo_60x60.png new file mode 100644 index 0000000..dacd36a Binary files /dev/null and b/source/_static/img/round_logo_60x60.png differ diff --git a/source/conf.py b/source/conf.py index 74090f6..755f4ce 100644 --- a/source/conf.py +++ b/source/conf.py @@ -37,7 +37,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', 'breathe'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['_templates', '_static'] # The suffix of source filenames. source_suffix = '.rst' @@ -69,7 +69,7 @@ release = '0.0.9' # 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' +today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -116,26 +116,46 @@ 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 = {} +html_theme_options = { + ## Sidebar placement options + #'stickysidebar' : 'true', + 'rightsidebar' : 'true', + #'collapsiblesidebar' : 'true', + + ## Color + 'sidebarbgcolor' : '#C8C8C8', + 'sidebarlinkcolor' : 'green', + 'sidebartextcolor' : 'black', + #'sidebarbtncolor' : 'black', + 'footerbgcolor' : 'green', + 'relbarbgcolor' : 'green', + 'headlinkcolor' : '#000000', + 'linkcolor' : 'green', + 'visitedlinkcolor' : 'green', + + ## Font + 'headfont' : 'Georgia', + 'bodyfont' : 'Lucidia' +} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +#html_theme_path = ['_static'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = 'LeafLabs' + project + ' v' + release + ' Documentation' # 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 +html_logo = '_static/img/round_logo_60x60.png' # 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 +html_favicon = '_static/img/round_logo_32x32.ico' # 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, @@ -144,14 +164,19 @@ html_static_path = ['_static'] # 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' +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 = {} +# re-add commented line when custom template for api finished +html_sidebars = { + '**': ['globaltoc.html', 'searchbox.html'], + #'lang/api**':['searchbox.html', 'apilist.html'], +} + # Additional templates that should be rendered to pages, maps page names to # template names. @@ -161,7 +186,7 @@ html_static_path = ['_static'] #html_domain_indices = True # If false, no index is generated. -#html_use_index = True +html_use_index = False # If true, the index is split into individual pages for each letter. #html_split_index = False diff --git a/source/confDefaultGreen.txt b/source/confDefaultGreen.txt new file mode 100644 index 0000000..789a5a0 --- /dev/null +++ b/source/confDefaultGreen.txt @@ -0,0 +1,250 @@ +# -*- coding: utf-8 -*- +# +# libmaple documentation build configuration file, created by +# sphinx-quickstart on Thu Oct 7 06:42:30 2010. +# +# 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 sys, os + + +# 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. +# +# We rely on Michael Jones's breathe as a Doxygen-to-Sphinx bridge. +# See libmaple/docs/README for information on obtaining it and letting +# Sphinx know where it is. +sys.path.append(os.environ['BREATHE_HOME']) + +# -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.todo', + 'sphinx.ext.coverage', 'breathe'] + +# 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'Maple' +copyright = u'2010, LeafLabs, LLC' + +# 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. +# +# The short X.Y version. +version = '0.0' +# The full version, including alpha/beta/rc tags. +release = '0.0.9' + +# 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 = ['epilog.rst', 'prolog.rst'] + +# Included at the end of every source file that is read. +with open('epilog.rst', 'r') as ep: + rst_epilog = ep.read() + +# Included at the beginning of every source file that is read. +with open('prolog.rst', 'r') as pr: + rst_prolog = pr.read() + +# 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 = [] + +# Warn about all references where the target cannot be found. +nitpicky = True + +# -- 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 = 'nature' + +# 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. + +# 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 +# " v documentation". +html_title = project + ' v' + release + ' Documentation' + +# 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 = '_static/img/round_logo_60x60.png' + +# 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 = '_static/img/round_logo_32x32.ico' + +# 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'] + +# 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 = { + '**': ['globaltoc.html', 'searchbox.html'], +} + + +# 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 = False + +# 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 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 = 'mapledoc' + + +# -- Options for LaTeX output ------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target file, title, author, documentclass [howto/manual]) +latex_documents = [ + ('index', 'maple.tex', u'Maple Documentation', + u'LeafLabs, LLC', '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 + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# 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', 'maple', u'Maple Documentation', + [u'LeafLabs, LLC'], 1) +] + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} + + +# -- Options for breathe integration ------------------------------------------ + +breathe_projects = {'libmaple' : os.path.join(os.environ['LIB_MAPLE_HOME'], + 'docs', 'doxygen', 'xml')} + +breathe_default_project = 'libmaple' diff --git a/source/cpp.rst b/source/cpp.rst new file mode 100644 index 0000000..a20578e --- /dev/null +++ b/source/cpp.rst @@ -0,0 +1,13 @@ +.. _cpp: + +============== +C++ for Maple +============== + +.. _index-language-index-cpp-index: + +.. toctree:: + :maxdepth: 1 + :glob: + + lang/cpp/* \ No newline at end of file diff --git a/source/home.rst b/source/home.rst new file mode 100644 index 0000000..9193e90 --- /dev/null +++ b/source/home.rst @@ -0,0 +1,33 @@ +.. _home: + +======================== +Maple Documentation Home +======================== + + +Welcome! + +Maple is a user-friendly prototyping platform developed by LeafLabs in Cambridge, MA. Using Maple, creators with any level of experience can implement beautiful ideas that require the power of a 32-bit processor. For more details about Maple's hardware, please see its :ref:`technical specifications `. To start using your Maple, keep reading. + +.. contents:: Contents + :local: + +.. _home-Getting-Started: + +Getting Started +^^^^^^^^^^^^^^^ + +:ref:`Quickstart ` + +:ref:`Basic Language Reference ` + +:ref:`Full Documentation ` + +.. _home-Problem-Solving: + +Problem Solving +^^^^^^^^^^^^^^^ + +Check out our :ref:`troubleshooting ` and :ref:`known problems` pages. + +If you don't find what you're looking for, hit the `forums `_ to ask the LeafLabs team and other Maple users questions. Good luck, and have fun! diff --git a/source/home.rtf b/source/home.rtf new file mode 100644 index 0000000..dda3ecd --- /dev/null +++ b/source/home.rtf @@ -0,0 +1,43 @@ +.. _home: + +=================== +Maple Documentation +=================== + +.. image:: /_static/img/maple_rev3.jpg + :align: left + +Welcome! + +Maple is a user-friendly prototyping platform developed by LeafLabs in Cambridge, MA. Using Maple, creators with any level of experience can implement beautiful ideas that require the power of a 32-bit processor. + +Based on a ARM Cortex M3 (STFM32F103RB) chip, Maple runs at up to 72 MHz and has 39 digital input/out pins, 16 analog inputs, native full speed USB, 3 USARTs, integrated SPI/I2C support, and is Arduino compatible. + +Getting Started +^^^^^^^^^^^^^^^ +.. sidebar:: Tech Specs + + Microcontroller: STM32 F103RB + Clock Speed: 72 MHz + Operating Voltage: 3.3V + Input Voltage (recommended): 3.0V-12V + Digital I/O Pins: 39 + Analog Input Pins: 16 + Flash Memory: 128 KB + SRAM: 20KB + 64 Channel nested vector interrupt handler (including external interrupt on GPIO’s) + Integrated SPI/I2C and 7 Channels of Direct Memory Access (DMA) + Supplies up to 800mA @ 3.3v + Support for low power and sleep modes (<500uA) + Dimensions: 2.05″x2.1″ + +:ref:`Quickstart ` + +:ref:`Basic Language Reference ` Program your Maple. + +:ref:`Full Documentation ` + +Problem Solving +^^^^^^^^^^^^^^^^^ + +Check out our :ref:`troubleshooting guide ` and :ref:`known problems` page. If you don't find what you're looking for, hit the `forums `_ to ask questions to the LeafLabs team and other Maple users. Good luck, and have fun! \ No newline at end of file diff --git a/source/ide.rst b/source/ide.rst index f38f6cd..b3ef653 100644 --- a/source/ide.rst +++ b/source/ide.rst @@ -3,18 +3,18 @@ Maple IDE ========= -.. figure:: /_static/img/ide-blinky.png - :align: center - :alt: Maple IDE - This page documents the basic functionality of the Maple IDE. Specifically, it describes the operation of the buttons on the main toolbar. It is expected to become more comprehensive over time. -The :ref:`Maple Quickstart ` is another source of +The :ref:`Maple Quickstart ` is another good source of information on the IDE; it is especially useful for setting up a computer for the first time. +.. figure:: /_static/img/ide-blinky.png + :align: center + :alt: Maple IDE + .. _ide-verify: Verify @@ -31,6 +31,7 @@ Stop ---- .. image:: /_static/img/button-stop.png + :align: left Click Stop to cancel a compilation. @@ -40,6 +41,7 @@ New --- .. image:: /_static/img/button-new.png + :align: left Click New to begin a fresh sketch. @@ -49,6 +51,7 @@ Open ---- .. image:: /_static/img/button-open.png + :align: left Click Open to open a new sketch. By default, this will look in you *sketchbook*, which is a directory on your system which contains all @@ -61,6 +64,7 @@ Save ---- .. image:: /_static/img/button-save.png + :align: left Click Save to save the currently opened sketch. @@ -70,6 +74,7 @@ Upload ------ .. image:: /_static/img/button-upload.png + :align: left Click Upload to send the compiled sketch to your Maple to run. Before you click Upload, you must have a memory location and serial port @@ -104,6 +109,7 @@ Serial Monitor -------------- .. image:: /_static/img/button-serial-monitor.png + :align: left Click Serial Monitor to open up a communications channel between your PC and the Maple's :ref:`Serial-over-USB ` diff --git a/source/index.rst b/source/index.rst index 42d1bd0..9fee4d2 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,47 +1,44 @@ .. _index: -Maple Documentation Index -========================= +Maple Documentation Contents +============================= -Welcome! This is the Maple documentation index. It contains -tutorials, quickstarts, and technical documentation. +.. _index-usage: -If you just got a new Maple, you probably want to begin with the -:ref:`quickstart `. You can then move on to reading -about the programming language you use with the Maple at the -:ref:`language reference `. +**Usage Guides:** -If you're having problems, you might want to visit the -:ref:`troubleshooting ` and :ref:`known problems -` pages. Finally, you can always hit the `forums -`_ to ask questions to the LeafLabs team -and other Maple users. Good luck, and have fun! +.. toctree:: + :maxdepth: 2 + + Quickstart + IDE Installation + IDE Anatomy -General documentation: +.. _index-maple-programming: + +**Maple Programming:** .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - Quickstart Guide - IDE Installation Guide - IDE Documentation - Language Reference - Arduino Compatibility Reference - Library Reference - Command-Line Tools and APIs - Troubleshooting + Maple Language + Maple Libraries + Arduino Compatibility External Interrupts + Command-Line Tools & APIs Bootloader + + + Troubleshooting Known Problems - Language Reference Index .. _index-hardware: -Hardware features: +**Hardware Features:** .. toctree:: :maxdepth: 1 - + i2c pwm gpio @@ -51,3 +48,15 @@ Hardware features: spi usart timers + +.. _index-reference: + +**Reference:** + +.. toctree:: + :maxdepth: 1 + + Technical Specifications + Complete Language Index + + diff --git a/source/lang/api/abs.rst b/source/lang/api/abs.rst new file mode 100644 index 0000000..0cc6c23 --- /dev/null +++ b/source/lang/api/abs.rst @@ -0,0 +1,49 @@ +.. highlight:: cpp + +.. _lang-abs: + + +abs() +====== + +(Macro) computes the absolute value of a number. + +Syntax +------ + +:: + + abs(x) + +Parameters +---------- + +**x**: the number. + +Returns +------- + +**x**: if **x** is greater than or equal to 0. + +**-x**: if **x** is less than 0. + +Warning +------- + +Because of the way ``abs()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + abs(a++); // avoid this - yields incorrect results + + abs(a); // use this instead - + a++; // keep other operations outside abs() + + +Arduino Compatibility +--------------------- + +Maple's implementation of ``abs()`` is compatible with Arduino. + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/analogread.rst b/source/lang/api/analogread.rst new file mode 100644 index 0000000..c614aca --- /dev/null +++ b/source/lang/api/analogread.rst @@ -0,0 +1,154 @@ +.. highlight:: cpp + +.. _lang-analogread: + +.. _lang-api-analogread: + +analogRead() +============ + +Used to perform ADC conversion. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: analogRead + +Discussion +---------- + +Reads the value from the specified analog pin. The Maple board +contains a 16-channel, 12-bit analog to digital converter. This means +that it will map input voltages between 0 and 3.3 volts into integer +values between 0 and 4095. This yields a resolution between readings +of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors +interfere with getting full accuracy and precision. For more +information, see :ref:`adc`. + +Before calling analogRead() on a pin, that pin must first be +configured for analog input, using :ref:`lang-pinMode` (you only +have to do this once, so it's usually done in :ref:`lang-setup`\ ). + +It takes about 0.8 microseconds (.0000008 seconds) to read an analog +input, so the maximum sample rate using this function is approximately +1.3 million samples per second\ [#fsamp]_. + + +Parameter Discussion +-------------------- + +The pin parameter is the number of the analog input pin to read from. +Header pins on the Maple with ADC functionality (marked as "AIN" on +the silkscreen) are: + + 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 + +Note that pins 3, 27, and 28 are not marked AIN on the silkscreen +for Maple revisions through Rev 5, however, they **do work** as +analog input pins. + +Note +---- + +If the analog input pin is not connected to anything, the value +returned by analogRead() will fluctuate based on a number of factors +(e.g. the values of the other analog inputs, how close your hand is to +the board, etc.) in a seemingly random way. + + +Example +------- + + :: + + + int analogPin = 3; // potentiometer wiper (middle terminal) connected + // to analog pin 3. outside leads to ground and +3.3V + int val = 0; // variable to store the value read + + void setup() { + pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input + SerialUSB.begin(); // set up usb virtual COM port + } + + void loop() { + val = analogRead(analogPin); // read the input pin + SerialUSB.println(val); // print the value, for debugging with + // a serial monitor + } + + +Arduino Compatibility +--------------------- + +The Arduino board contains a 6 channel (8 channels on the Mini and +Nano, 16 on the Mega), 10-bit analog to digital converter with an +input voltage range of 0V--5V. This means that it will map input +voltages between 0 and 5 volts (which is **larger** than Maple's range +of 0V-3.3V) into integer values between 0 and 1023 (which is +**smaller** than the Maple's range of 0--4095). + +This yields a theoretical resolution between readings of: 5 volts / +1024 units or .0049 volts (4.9 mV) per unit on Arduino boards, which +is larger, and thus less precise, than Maple's 0.0008 volts (0.8 mV). + +If your program expects Arduino-style 10-bit ADC, you can :ref:`right +shift ` the value of a Maple readout by 2, like so:: + + // right shift means that the result will be between 0 and 1023; + // be aware that you're losing a lot of precision if you do this + int adc_reading = analogRead(pin) >> 2; + +On the Arduino, the input range and resolution can be changed using +their implementation of `analogReference() +`_\ . Because of the +way its hardware (as of Rev 5) was designed, it's not possible to +implement analogReference on the Maple, so this function doesn't +exist. If your inputs lie in a different voltage range than 0V--3.3V, +you'll need to bring them into that range before using analogRead. +Some basic tools to accomplish this are `resistor dividers +`_ and `Zener diodes +`_\ +. However, opamps and other powered components can also be used if +greater precision is required. + +Finally, On the Arduino, it takes significantly longer to read analog +input: about 100 microseconds (0.0001 s), so the maximum reading rate +is 10,000 times a second. + + +See also +-------- + +- :ref:`ADC note ` +- `(Arduino) Tutorial: Analog Input Pins `_ + + +.. rubric:: Footnotes + +.. [#fsamp] This is based on the current configuration of a 55.5 cycle + sample time, at 72 MHz. However, the minimum sample time *possible* + is 1.5 cycles, leading to a theoretical maximum of approximately 48 + million samples per second (of course, doing anything with the + readings also consumes cycles, so this maximum can't be reached in + practice). + + See the `STM32 Reference Manual `_, §§11.12.4--5 + (pp. 225--226), for more information on the low-level bit twiddling + currently necessary to change the sample time. For examples of how + the ADCs are configured in libmaple, see `adc.h + `_ + and `adc.c + `_\ + . Be aware that changing the sample time has important + consequences related to the impedance of the device connected to + the input pin. If you want to make changes, as a minimum, you + should first read ST's application notes on `ADC modes + `_ and `ADC oversampling + `_. + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst new file mode 100644 index 0000000..01820ef --- /dev/null +++ b/source/lang/api/analogwrite.rst @@ -0,0 +1,169 @@ +.. highlight:: cpp + +.. _lang-analogwrite: + +.. _lang-api-analogwrite: + + +analogWrite() +============= + +.. note:: + + On the Maple, calling analogWrite() is the same as calling + :ref:`lang-pwmwrite`\ ; see that function's documentation for more + information. + + This is because PWM is not true analog output (i.e., is not the + output of a `DAC + `_\ ), so + the function is badly named. For instance, **analogWrite() has + absolutely nothing to do with** :ref:`lang-analogread`\ , which is + potentially confusing. + + The alias of analogWrite() to pwmWrite() is provided (sigh) for the + sake of compatibility with Arduino, but we recommend using + :ref:`lang-pwmwrite` when writing new software, for clarity. + +.. contents:: Contents + :local: + +.. _lang-analogwrite-compatibility: + +Arduino Compatibility +--------------------- + +There are a few important differences between Arduino's `analogWrite() +`_ and Maple's +:ref:`lang-pwmwrite` that you should keep in mind. In each case, we +have some recommendations you can use to help converting from Arduino +to Maple. + +Difference 1: Duty cycle range is different +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first and most important difference is that the largest possible +value for the duty cycle is much bigger on the Maple. Using Arduino's +analogWrite(), the duty cycle ranges between 0--255 (always off -- +always on)\ [#fbytemax]_\ . Using Maple's pwmWrite(), the duty cycle +ranges from 0--65,535 by default\ [#fuint16max]_\ . + +This is a good thing! The greater range of values on the Maple gives +you much more precise control over the duty cycle of your PWM output. + +If you're porting code from the Arduino and want a quick-and-dirty +fix, one solution is to :ref:`map ` the argument to +analogWrite into the right range:: + + // Arduino code: + analogWrite(pin, duty); + + // Becomes Maple code: + analogWrite(pin, map(duty, 0, 255, 0, 65535)); + +This will convert values in the range 0-255 to values in the range +0--65,635, which is the correct default range for all of the timers +which control PWM output. See the :ref:`timers reference ` +for more information. + +Another fix is to consult the :ref:`pin mapping mega table +` to find the timer which controls PWM on the +pin you're using, then set that Timer's overflow to 255. Subsequent +calls to analogWrite() should work as on the Arduino (with the same +loss of precision). Note, however, that that affects the overflow for +the **entire timer**, so other code relying on that timer (such as any +:ref:`interrupts ` the timer controls) will +likely need to be modified as well. + +Difference 2: You must use pinMode() to set up PWM +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The second difference is that on the Maple, you **must** set up the pin +for PWM output using :ref:`lang-pinmode`\ , with argument ``PWM``. +This should just be one extra line of code in your +:ref:`lang-setup` function. Example:: + + void setup() { + // set up pin 9 for PWM + pinMode(9, PWM); + } + +This also means that you can't later call :ref:`lang-digitalread` +or :ref:`lang-digitalwrite` on that pin (unless some time in +between, you use pinMode() to reconfigure that pin for ``INPUT`` or +``OUTPUT``; see the :ref:`lang-pinmode` page for more information). + +Difference 3: No PWM on pin 10 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, +9, 11, 12, and 14, or twelve pins in total. That is at least as +*many* PWM pins as any Arduino board, but there are differences in +*which* pins support it. + +* On **most Arduino boards** (those with the ATmega168 or ATmega328; + this includes the **Arduino Uno**), this function works on pins 3, + 5, 6, 9, 10, and 11, or six pins total. Note that these boards + support PWM on pin 10, while Maple does not. + +* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins + total. Note that this board supports PWM on pins 4, 10, and 13, + while the Maple does not. Maple supports PWM on pins 0, 1, and 14, + which the Mega does not, making the total number of pins supporting + PWM equal on these boards. + +* **Older Arduino boards** with an ATmega8 only support analogWrite() on + pins 9, 10, and 11. Maple does not support PWM on pin 10. + +In all cases, Arduino boards support PWM on pin 10, unlike Maple. We +did our best to make PWM as pin-compatible as possible; however, +circuit layout constraints prevented us from achieving perfect +compatibility. + +The "safest" pins to use for PWM output are pins 9 and 11. These pins +work on any Arduino board and on Maple. The "safe" pins, which work +on most recent Arduino boards, the Arduino Mega and the Maple, are +pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as +portable as possible between Maple and Arduino, we recommend using the +"safest" pins first, then the "safe" pins, as necessary. + +Difference 4: PWM frequency +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The frequency of the PWM signal (i.e., the frequency of a complete +on/off cycle) on the Arduino is approximately 490 Hz. + +On the Maple, the frequency is configurable, defaulting to about 1100 +Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of +the timer which controls PWM output on the particular pin (\ +:ref:`the PWM tutorial has the details `\ ). + +If your application absolutely requires Arduino's PWM frequency (it +probably doesn't), then the steps are: + +1. Figure out which timer controls PWM output on your pin (\ :ref:`this table ` is your friend here). Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4. + +2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of approximately 490 Hz. + +Be aware that this will change the period for the **entire timer**\ , +and will affect anything else in your program that depends on that +timer. One example is :ref:`interrupts `\ . +You've been :ref:`warned `\ . + +See also +-------- + +- :ref:`Maple PWM tutorial ` + +.. rubric:: Footnotes + +.. [#fbytemax] This is because the value for the duty cycle on Arduino + must fit in 1 byte of memory, and an unsigned (i.e., nonnegative) + integer with size 1 byte can hold the values between 0 and 255. + +.. [#fuint16max] This is because the value for the duty cycle on the + Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) + integer with size 2 bytes can hold the values between 0 and 65,535. + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst new file mode 100644 index 0000000..0b8907f --- /dev/null +++ b/source/lang/api/attachinterrupt.rst @@ -0,0 +1,102 @@ +.. highlight:: cpp + +.. _lang-attachinterrupt: + +attachInterrupt() +================= + +Used to specify a function to call when an external interrupt (like an +GPIO changing from LOW to HIGH, a button getting pressed, etc.) +occurs. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: attachInterrupt + +.. doxygenenum:: ExtIntTriggerMode + +.. doxygentypedef:: voidFuncPtr + +Discussion +---------- + +Because the function will run in interrupt context, inside of it, +:ref:`lang-delay` won't work, and the value returned by +:ref:`lang-millis` will not increment. Serial data received while +in the function may be lost. You should declare as ``volatile`` any +global variables that you modify within the attached function. + +There are a few constraints you should be aware of if you're using +more than one interrupt at a time; the :ref:`external-interrupts` page +has the details. + + +Using Interrupts +---------------- + +Interrupts are useful for making things happen automatically in +microcontroller programs, and can help solve timing problems. A +good task for using an interrupt might be reading a rotary encoder, +or monitoring user input. + + +If you wanted to insure that a program always caught the pulses +from a rotary encoder, never missing a pulse, it would make it very +tricky to write a program to do anything else, because the program +would need to constantly poll the sensor lines for the encoder, in +order to catch pulses when they occurred. Other sensors have a +similar interface dynamic too, such as trying to read a sound +sensor that is trying to catch a click, or an infrared slot sensor +(photo-interrupter) trying to catch a coin drop. In all of these +situations, using an interrupt can free the microcontroller to get +some other work done while not missing the doorbell. + + +Example +------- + +:: + + int maple_led_pin = 13; + volatile int state = LOW; // must declare volatile, since it's + // modified within the blink handler + + void setup() { + pinMode(maple_led_pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() { + digitalWrite(maple_led_pin, state); + } + + void blink() { + state = !state; + } + + +Arduino Compatibility +--------------------- + +Most Arduino boards have two external interrupts: numbers 0 (on +digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an +additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 +(pin 18). On the Maple, you don't have to remember which interrupt +number goes with which pin -- just tell ``attachInterrupt()`` the pin +you want. + + +See also +-------- + + +- :ref:`detachInterrupt ` +- :ref:`external-interrupts` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/bit.rst b/source/lang/api/bit.rst new file mode 100644 index 0000000..dd5c050 --- /dev/null +++ b/source/lang/api/bit.rst @@ -0,0 +1,44 @@ +.. _lang-bit: + +bit() +===== + +(Macro) Computes the value of an (unsigned) integer with the specified +bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8, +16, 32, etc.). + +Syntax +------ + +``bit(n)`` + + +Parameters +---------- + +* **n** the bit to set. + + +Value +----- + +The value of an integer with the given bit set. + + +Arduino Compatibility +--------------------- + +The Maple implementation of bit is compatible with Arduino. + + +See also +-------- + + +- :ref:`lang-bitread` +- :ref:`lang-bitwrite` +- :ref:`lang-bitset` +- :ref:`lang-bitclear` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/bitclear.rst b/source/lang/api/bitclear.rst new file mode 100644 index 0000000..941f912 --- /dev/null +++ b/source/lang/api/bitclear.rst @@ -0,0 +1,44 @@ +.. _lang-bitclear: + +bitClear() +========== + +(Macro) Clears (writes a 0 to) a bit of a numeric variable. + +Syntax +------ + +``bitClear(x, n)`` + + +Parameters +---------- + +* **x** the numeric variable whose bit to clear + +* **n** which bit to clear, starting at 0 for the least-significant + (rightmost) bit + + +Returns +------- + +None. + + +Arduino Compatibility +--------------------- + +This implementation is compatible with that of Arduino. + + +See also +-------- + +- :ref:`bit `\ () +- :ref:`bitRead `\ () +- :ref:`bitWrite `\ () +- :ref:`bitSet `\ () + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/bitread.rst b/source/lang/api/bitread.rst new file mode 100644 index 0000000..46b4478 --- /dev/null +++ b/source/lang/api/bitread.rst @@ -0,0 +1,46 @@ +.. _lang-bitread: + +bitRead() +========= + +(Macro) Gets the value of a bit in a number. + + +Syntax +------ + +``bitRead(x, n)`` + + +Parameters +---------- + +* **x** the number from which to read the bit. + +* **n** which bit to read, starting at 0 for the least-significant + (rightmost) bit + + +Value +----- + +The value of the bit (0 or 1). + + +Arduino Compatibility +--------------------- + +The Maple implementation of ``bitRead`` is compatible with Arduino. + + +See also +-------- + + +- :ref:`lang-bit` +- :ref:`lang-bitwrite` +- :ref:`lang-bitset` +- :ref:`lang-bitclear` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/bitset.rst b/source/lang/api/bitset.rst new file mode 100644 index 0000000..ccd76de --- /dev/null +++ b/source/lang/api/bitset.rst @@ -0,0 +1,46 @@ +.. _lang-bitset: + +bitSet() +======== + +(Macro) Sets (writes a 1 to) a bit of a numeric variable. + + +Syntax +------ + +``bitSet(x, n)`` + + +Parameters +---------- + +* **x** the numeric variable whose bit to set + +* **n** which bit to set, starting at 0 for the least-significant + (rightmost) bit + + +Value +----- + +None. + + +Arduino Compatibility +--------------------- + +The Maple implementation of bitSet is compatible with Arduino. + + +See Also +-------- + +- :ref:`lang-bit` +- :ref:`lang-bitread` +- :ref:`lang-bitwrite` +- :ref:`lang-bitclear` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/bitwrite.rst b/source/lang/api/bitwrite.rst new file mode 100644 index 0000000..b3feff2 --- /dev/null +++ b/source/lang/api/bitwrite.rst @@ -0,0 +1,46 @@ +.. highlight:: cpp + +.. _lang-bitwrite: + +bitWrite() +========== + +(Macro) Writes a bit of a numeric variable. + +Syntax +------ + +:: + + bitWrite(x, n, b) + +Parameters +---------- + +**x**: the numeric variable whose bit to write. + +**n**: which bit of the number to write, starting at 0 for the +least-significant (rightmost) bit. + +**b**: the value to write to the bit (0 or 1). + +Returns +------- + +Nothing. + +Arduino Compatibility +--------------------- + +Maple's version of ``bitWrite()`` is compatible with Arduino. + +See also +-------- + +- :ref:`bit() ` +- :ref:`bitRead() ` +- :ref:`bitSet() ` +- :ref:`bitClear() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/cc-attribution.txt b/source/lang/api/cc-attribution.txt new file mode 100644 index 0000000..e100140 --- /dev/null +++ b/source/lang/api/cc-attribution.txt @@ -0,0 +1,9 @@ +.. Included in all this directory's files in order to satisfy the +.. Arduino CC Attribution-ShareAlike 3.0 License + +.. admonition:: License and Attribution + + This documentation page was adapted from the `Arduino Reference + Documentation `_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License `_. diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst new file mode 100644 index 0000000..bc5c894 --- /dev/null +++ b/source/lang/api/constants.rst @@ -0,0 +1,304 @@ +.. _lang-constants: + +Constants +========= + +Constants are like predefined variables, whose values can't +change. They are used to make the programs easier to read and modify. +This page describes the most commonly used constants. + +.. contents:: Contents + :local: + +.. _lang-constants-bool: + +Boolean Constants +----------------- + +There are two constants used to represent truth and falsity: ``true``, +and ``false``. + +.. _lang-constants-false: + +false +^^^^^ + +``false`` is the false ``bool`` value. An integer which is 0 evaluates +to ``false`` as a boolean. + +.. _lang-constants-true: + +true +^^^^ + +``true`` is the true ``bool`` value. As an integer, ``true`` is often +said to be 1. This is correct in the sense that ``true`` evaluates to +1 as an integer. However, any integer which is *non-zero* is ``true`` +as a :ref:`bool `. So -1, 2 and -200 are all +"true", in the sense that these numbers are treated the same as +``true`` in a boolean context. + +Note that the ``true`` and ``false`` constants are typed in lowercase; +unlike e.g. ``HIGH``, ``LOW``, ``INPUT``, and ``OUTPUT`` (which are +described below). + + +Pin Levels: HIGH and LOW +------------------------ + +When reading or writing to a digital pin there are only two possible +values a pin can be set to: ``HIGH`` and ``LOW``. + +.. _lang-constants-high: + +HIGH +^^^^ + +The meaning of ``HIGH`` (in reference to a pin) is somewhat different +depending on whether the pin is set to ``INPUT`` or ``OUTPUT``. When a +pin is configured as an ``INPUT`` (using :ref:`pinMode() +`), and read with :ref:`digitalRead() +`, the microcontroller will report ``HIGH`` if a +voltage of 3 volts or more is present at the pin. + +.. TODO? Following seems false; check it out sometime, leave out for now: + +.. A pin may also be configured as an ``INPUT`` with ``pinMode()``, and +.. subsequently made ``HIGH`` with :ref:`digitalWrite() +.. `, this will set the internal pullup resistors, +.. which will *steer* the input pin to a HIGH reading unless it is pulled +.. LOW by external circuitry. + +When a pin is configured to ``OUTPUT`` with pinMode, and set to +``HIGH`` with :ref:`digitalWrite() `, the pin is at +3.3 volts. In this state it can *source* current, e.g. light an LED +that is connected through a series resistor to ground, or to another +pin configured as an output and set to ``LOW``. + +.. _lang-constants-low: + +LOW +^^^ + +The meaning of ``LOW`` also has a different meaning depending on +whether a pin is set to ``INPUT`` or ``OUTPUT``. When a pin is +configured as an ``INPUT`` with :ref:`pinMode() `, and +read with :ref:`digitalRead() `, the microcontroller +will report ``LOW`` if a voltage of 2 volts or less is present at the +pin. + +When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to +``LOW`` with :ref:`digitalWrite() `, the +microcontroller will attempt to keep that pin's voltage at 0V. In this +state it can *sink* current, e.g. light an LED that is connected +through a series resistor to +3.3V, or to another pin configured as an +output, and set to ``HIGH``. + +Pin Modes +--------- + +Digital pins can be used in a variety of modes. The basic modes, +``INPUT`` and ``OUTPUT``, have been introduced above. Changing a pin +from ``INPUT`` TO ``OUTPUT`` with :ref:`pinMode() ` +drastically changes the electrical behavior of the pin. + +This section describes the basic digital pin modes (``INPUT`` and +``OUTPUT``) only. For a detailed description of all possible pin +modes, see the :ref:`pinMode() ` reference page. + +.. _lang-constants-input: + +INPUT +^^^^^ + +Maple (STM32) pins configured as ``INPUT`` are said to be in a +high-impedance state. One way of explaining this is that pins +configured as ``INPUT`` make extremely small demands on the circuit +that they are sampling. This makes them useful for reading a sensor, +but not powering an LED. + +.. _lang-constants-output: + +OUTPUT +^^^^^^ + +Pins configured as ``OUTPUT`` with :ref:`pinMode() ` are +said to be in a low-impedance state. This means that they can provide +a substantial amount of current to other circuits. STM32 pins can +source (provide positive current) or sink (provide negative current) +up to 50 mA (milliamps) of current to other devices/circuits. This +makes them useful for powering LEDs, but useless for reading sensors. + +Pins configured as outputs can also be damaged or destroyed if short +circuited to either ground or 3.3V power rails. The amount of current +provided by an STM32 pin is also not enough to power most relays or +motors, and some interface circuitry will be required. + +.. _lang-constants-integers: + +Integer Constants +----------------- + +Integer constants (or more properly speaking, integer *literals*) are +numbers used directly in a sketch, like ``123``. By default, an +integer literal is treated as a (signed) :ref:`int `, but +you can change this with the U and L modifiers (see :ref:`below +`). You can specify negative numbers by +putting a minus sign in front, like ``-123``. + +Normally, integer literals are treated as base 10 (decimal) integers, +but special notation (formatters) may be used to enter numbers in +other bases. These are summarized in the following table: + +.. list-table:: + :header-rows: 1 + + * - Base + - Example + - Formatter + - Comment + + * - 10 (decimal) + - ``123`` + - None + - + + * - 2 (binary) + - ``0b1111011`` + - Leading "0b" + - GCC extension; not standard C++ + + * - 8 (octal) + - ``0173`` + - Leading "0" + - Characters 0-7 valid + + * - 16 (hexadecimal) + - ``0x7B`` + - Leading "0x" + - Characters 0-9, A-F (or a-f) valid + +Binary constants (like ``B1111011``) for values between 0 and 255 are +supported for compatibility with Arduino only. Their use in new +programs is discouraged. + +.. _lang-constants-integers-dec: + +**Decimal** is base 10. This is the common number system we learn in +school. Integer literals without other prefixes are assumed to be in +decimal format. + +For example, the decimal literal ``101`` is one hundred and one: 1×10\ +:sup:`2` + 0×10\ :sup:`1` + 1×10\ :sup:`0` = 101. + +.. _lang-constants-integers-bin: + +**Binary** is base two. Only characters 0 and 1 are valid. Binary +literals are indicated by the prefix ``0b`` (this is a :ref:`GCC +` extension; it's not standard C++). + +For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` + +0×2\ :sup:`1` + 1×2\ :sup:`0` = 5. + +.. _lang-constants-integers-oct: + +**Octal** is base eight. Only characters 0 through 7 are valid. Octal +literals are indicated by the prefix ``0``. + +For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` + +0×8\ :sup:`1` + 1×8\ :sup:`0` = 65. + +.. warning:: Bugs sometimes result by (unintentionally) including a + leading "0" before an integer literal, which makes the compiler + interpret it in octal. + +.. _lang-constants-integers-hex: + +**Hexadecimal** (or "hex") is base sixteen. Valid characters are 0 +through 9 and letters A through F; A has the value 10, B is 11, up to +F, which is 15. Hex values are indicated by the prefix ``0x``. A-F +may be typed in upper or lower case (a-f). + +For example, the hexadecimal literal ``0x101`` is two hundred fifty +seven: 1×16\ :sup:`2` + 0×16\ :sup:`1` + 1×16\ :sup:`0` = 257. + +The hexadecimal literal ``0xCF2`` is three thousand, three hundred +fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314. + +(Remember that in hex, ``A`` means 10, and counting up, ``B``\ =11, so +``C``\ =12 and ``F``\ =15). + +.. _lang-constants-integers-u-l: + +U and L Suffixes +^^^^^^^^^^^^^^^^ + +By default, an integer constant is treated as an :ref:`int +`, with the attendant :ref:`limitations in values +`. To specify an integer constant with another data +type, follow it with: + +- a ``u`` or ``U`` to interpret the constant as an unsigned value. + For example, ``33U`` is an :ref:`unsigned int `. + +- an ``l`` or ``L`` to interpret the constant as a long value. For + example, ``100000L`` is a :ref:`long `. + +- a ``ul`` or ``UL`` to do both. For example, ``32767UL`` is an + :ref:`unsigned long `. + +.. _lang-constants-fp: + +Floating-Point Constants +------------------------ + +Similar to integer literals, floating point constants (properly: +floating-point *literals*) are used to make code more readable. +Floating point literals are swapped at compile time for the value to +which the expression evaluates. + +A floating point literal is any number which includes a decimal point. +For instance, ``3.0`` is a floating-point literal for the number 3. +By default, a floating-point literal is a :ref:`double `. +In order for the literal to be interpreted as a :ref:`float +`, you can write ``f`` directly after it. For example, +``3.0f`` is a floating-point literal with type ``float``. + +Floating point constants can also be expressed in a variety of +scientific notation. ``E`` and ``e`` are both accepted as valid +exponent indicators. Some examples are given in the following table: + + +.. list-table:: + :header-rows: 1 + + * - Floating-point literal + - Evaluates to + - Alternate expression + + * - ``10.0`` + - 10 + - + + * - ``2.34E5`` + - 2.34×10\ :sup:`5` + - ``234000.0`` + + * - ``67e-12`` + - 67.0×10\ :sup:`-12` + - ``0.000000000067`` + +See Also +-------- + +- :ref:`pinMode() ` +- :ref:`Boolean Variables ` +- :ref:`#define ` +- :ref:`int ` +- :ref:`unsigned int ` +- :ref:`long ` +- :ref:`unsigned long ` +- :ref:`float ` +- :ref:`double ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/constrain.rst b/source/lang/api/constrain.rst new file mode 100644 index 0000000..d19b61c --- /dev/null +++ b/source/lang/api/constrain.rst @@ -0,0 +1,69 @@ +.. highlight:: cpp + +.. _lang-constrain: + +constrain() +=========== + +(Macro) Constrains a number to be within a range. + +Syntax +------ + +:: + + constrain(x, a, b) + + +Parameters +---------- + +**x**: the number to constrain + +**a**: the lower end of the range + +**b**: the upper end of the range + +Returns +------- + +**x**: if **x** is between **a** and **b** + +**a**: if **x** is less than **a** + +**b**: if **x** is greater than **b** + +Example +------- + +:: + + // limits range of sensor values to between 10 and 150: + sensVal = constrain(sensVal, 10, 150); + + +Warning +------- + +Because of the way ``constrain()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + constrain(x,a++,b); // avoid this - yields incorrect results + + constrain(x,a,b); // use this instead- + a++; // keep other math outside constrain() + +Arduino Compatibility +--------------------- + +Maple's implementation of ``constrain()`` is compatible with Arduino. + +See also +-------- + +- :ref:`min() ` +- :ref:`max() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/cos.rst b/source/lang/api/cos.rst new file mode 100644 index 0000000..3fbb0af --- /dev/null +++ b/source/lang/api/cos.rst @@ -0,0 +1,32 @@ +.. _lang-cos: + +cos() +===== + +Calculates the cosine of an angle. + +Library Documentation +--------------------- + +.. doxygenfunction:: cos + +Arduino Compatibility +--------------------- + +The Maple ``cos()`` implementation is compatible with Arduino. + +Note that the Maple implementation comes from `newlib +`_\ , while Arduino's is that of +`avr-libc `_\ . + +See also +-------- + + +- :ref:`sin() ` +- :ref:`tan() ` +- :ref:`float ` +- :ref:`double ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/delay.rst b/source/lang/api/delay.rst new file mode 100644 index 0000000..90ca268 --- /dev/null +++ b/source/lang/api/delay.rst @@ -0,0 +1,72 @@ +.. highlight:: cpp + +.. _lang-delay: + +delay() +======= + +Pauses the program for at least a given number of milliseconds. (There +are 1000 milliseconds in a second.) + +Library Documentation +--------------------- + +.. doxygenfunction:: delay + + +Discussion +---------- + +While it is easy to create a blinking LED with the ``delay()`` +function, and many sketches use short delays for such tasks as switch +debouncing, the use of ``delay()`` in a sketch has significant +drawbacks. No other reading of sensors, mathematical calculations, or +pin manipulation can go on during the delay function, so in effect, it +brings most other activity to a halt. For alternative approaches to +controlling timing see the :ref:`millis() ` function +and the "Blink Without Delay" sketch cited :ref:`below +`\ . More knowledgeable programmers usually +avoid the use of ``delay()`` for timing of events longer than tens of +milliseconds, unless the sketch is very simple. + +Certain things *do* go on while the ``delay()`` function is +controlling the STM32 chip, however, because the delay function does +not disable interrupts. Serial communication that appears at the RX +pin is recorded, PWM (see :ref:`pwmWrite() `\ ) values +and pin states are maintained, and :ref:`interrupts +` will work as they should. + + +Example +------- + +:: + + int ledPin = 13; // LED connected to pin 13 + + void setup() { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + +.. _lang-delay-seealso: + +See also +-------- + + +- :ref:`millis() ` +- :ref:`micros() ` +- :ref:`delayMicroseconds() ` +- (Arduino) `Blink Without Delay + `_ example (works + unmodified on Maple) + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/delaymicroseconds.rst b/source/lang/api/delaymicroseconds.rst new file mode 100644 index 0000000..24a8286 --- /dev/null +++ b/source/lang/api/delaymicroseconds.rst @@ -0,0 +1,65 @@ +.. highlight:: cpp + +.. _lang-delaymicroseconds: + +delayMicroseconds() +=================== + +Pauses the program for the amount of time (in microseconds) +specified as parameter. There are a thousand microseconds in a +millisecond, and a million microseconds in a second. + +Library Documentation +--------------------- + +.. doxygenfunction:: delayMicroseconds + + +Example +------- + +The following example configures pin number 8 to work as an output +pin, and sends a train of pulses with a period of roughly 100 +microseconds:: + + int outPin = 8; + + void setup() { + pinMode(outPin, OUTPUT); // sets the digital pin as output + } + + void loop() { + digitalWrite(outPin, HIGH); // sets the pin on + delayMicroseconds(50); // pauses for 50 microseconds + digitalWrite(outPin, LOW); // sets the pin off + delayMicroseconds(50); // pauses for 50 microseconds + } + + +Caveats and Known Issues +------------------------ + +The longest time ``delayMicroseconds()`` can delay is bounded by its +argument type and the STM32 clock rate to be (2^32 - 1) / 12 +microseconds, or less than 6 minutes. For longer pauses, use of +:ref:`lang-delay` is possible. + +Arduino Compatibility +--------------------- + +While we have made every effort we could to ensure that the timing of +delayMicroseconds is as accurate as possible, we cannot guarantee it +will behave as the Arduino implementation down to the microsecond, +especially for smaller values of ``us``. + +See Also +-------- + +- :ref:`millis ` +- :ref:`micros ` +- :ref:`delay ` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/detachinterrupt.rst b/source/lang/api/detachinterrupt.rst new file mode 100644 index 0000000..adb2439 --- /dev/null +++ b/source/lang/api/detachinterrupt.rst @@ -0,0 +1,37 @@ +.. _lang-detachinterrupt: + +detachInterrupt() +================= + +Used to disable an interrupt specified with +:ref:`lang-attachinterrupt`\ . + + +Library Documentation +--------------------- + +.. doxygenfunction:: detachInterrupt + +Arduino Compatibility +--------------------- + +There is one important difference between the Maple version of +detachInterrupt and the Arduino version. On the Maple, the argument +to ``detachInterrupt()`` is the *pin* on which the interrupt is +attached, while on the Arduino, the argument is the *interrupt +number*, which is different from the pin the interrupt is enabled on. + +If you're calling this function, you've already called +:ref:`lang-attachinterrupt` to set up your interrupt handler, so +just call ``detachInterrupt()`` with the same pin argument you gave to +``attachInterrupt()``. + +See Also +-------- + +- :ref:`attachInterrupt() ` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/digitalread.rst b/source/lang/api/digitalread.rst new file mode 100644 index 0000000..3502587 --- /dev/null +++ b/source/lang/api/digitalread.rst @@ -0,0 +1,58 @@ +.. highlight:: cpp + +.. _lang-digitalread: + +digitalRead() +============= + +Reads the value from a specified digital pin, either :ref:`HIGH +` or :ref:`LOW `. + + +Library Documentation +--------------------- + +.. doxygenfunction:: digitalRead + + +Example +------- + +The following example turns the LED on when the button is pressed:: + + int ledPin = 13; // LED connected to Maple pin 13 + int buttonPin = 38; // BUT connected to Maple pin 38 + + void setup() { + pinMode(ledPin, OUTPUT); + pinMode(buttonPin, INPUT); + } + + void loop() { + int val = digitalRead(buttonPin); // reads the input pin + digitalWrite(ledPin, val); + } + +Note +---- + +If the pin isn't connected to anything, ``digitalRead()`` can return +either HIGH or LOW (and this can change in a way that seems random). + +Arduino Compatibility +--------------------- + +The Maple version of ``digitalRead()`` is compatible with Arduino. + + +See Also +-------- + +- :ref:`pinMode ` +- :ref:`digitalWrite ` + + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/digitalwrite.rst b/source/lang/api/digitalwrite.rst new file mode 100644 index 0000000..6124d5f --- /dev/null +++ b/source/lang/api/digitalwrite.rst @@ -0,0 +1,68 @@ +.. highlight:: cpp + +.. _lang-digitalwrite: + +digitalWrite() +============== + +Write a :ref:`HIGH ` or a :ref:`LOW +` value to a pin configured as :ref:`OUTPUT +`. + +Library Documentation +--------------------- + +.. doxygenfunction:: digitalWrite + +Discussion +---------- + +If the pin has been configured as an ``OUTPUT`` with :ref:`pinMode() +` its voltage will be set to the corresponding value: +3.3V for ``HIGH``, and 0V (ground) for ``LOW``. + +.. TODO make the following paragraphs true, but refer the reader to +.. INPUT_PULLUP and INPUT_PULLDOWN: + +If the pin is configured as an ``INPUT``, writing a ``HIGH`` value +with ``digitalWrite()`` will enable an internal pullup resistor. +Writing ``LOW`` will disable the pullup. The pullup resistor is enough +to light an LED dimly, so if LEDs appear to work, but very dimly, this +is a likely cause. The remedy is to set the pin to an output with the +:ref:`pinMode() ` function. + +.. note:: Pin 13 is harder to use as an input than the other pins + because it has an LED and resistor soldered to it in series. If you + enable its internal pull-up resistor, it will likely hang at around + 1.1V instead of the expected 3.3V because the onboard LED and + series resistor pull the voltage level down. If you must use pin 13 + as a digital input, use an external pull-down resistor. + +Example +------- + +The following example sets pin 13 to ``HIGH``, makes a one-second-long +delay, sets the pin back to ``LOW``, and delays again, causing a +blinking pattern:: + + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + +See Also +-------- + +- :ref:`pinMode ` +- :ref:`digitalRead ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/highbyte.rst b/source/lang/api/highbyte.rst new file mode 100644 index 0000000..50a1fa6 --- /dev/null +++ b/source/lang/api/highbyte.rst @@ -0,0 +1,59 @@ +.. highlight:: cpp + +.. _lang-highbyte: + +highByte() +========== + +(Macro) Extracts the second lowest byte of an integral data type. + +.. warning:: This macro is provided for compatibility with Arduino + only. It returns the second-least significant byte in an integral + value. It makes sense to call this the "high" byte on a 16-bit + ``int`` microcontroller like the Atmel chips on Arduinos, but it + makes no sense at all on a 32-bit microcontroller like the STM32s + in the Maple line. + + In short: we provide this so that existing Arduino code works as + expected, but **strongly discourage its use** in new programs. + +Syntax +------ + +:: + + highByte(x) + +Parameters +---------- + +**x**: a value of any integral type. + +Returns +------- + +Second lowest byte in **x**. + +Example +------- + +:: + + int x = 0xDEADBEEF; + SerialUSB.println(x, HEX); // prints "BE" + +Arduino Compatibility +--------------------- + +The Maple version of ``highByte()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`lowByte() ` + + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/loop.rst b/source/lang/api/loop.rst new file mode 100644 index 0000000..d8f6183 --- /dev/null +++ b/source/lang/api/loop.rst @@ -0,0 +1,45 @@ +.. highlight:: cpp + +.. _lang-loop: + +loop() +====== + +After creating a :ref:`setup() ` function, which +initializes your sketch, the ``loop()`` function gets called +repeatedly, allowing your program to change and respond. Use it to +actively control your Maple board. + +Example +------- + +:: + + + int buttonPin = 38; + + // setup initializes serial and the button pin + void setup() { + SerialUSB.begin(); + pinMode(buttonPin, INPUT); + } + + // loop() checks the button pin each time it executes, + // and will print 'H' if it is pressed, 'L' otherwise + void loop() { + if (digitalRead(buttonPin) == HIGH) { + SerialUSB.println('H'); + } else { + SerialUSB.println('L'); + } + + delay(1000); + } + +See Also +-------- + +- :ref:`setup() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/lowbyte.rst b/source/lang/api/lowbyte.rst new file mode 100644 index 0000000..58e622f --- /dev/null +++ b/source/lang/api/lowbyte.rst @@ -0,0 +1,25 @@ +.. _lang-lowbyte: + +lowByte() +========= + +Extracts the low-order (rightmost) byte of a variable (e.g. a +word). + +Syntax +------ + +lowByte(x) + +Parameters +---------- + +**x**: a value of any type. However, if a non-integral type is used, +the results will be strange. + +Returns +------- + +The low byte's value (this will be between 0 and 255). + +.. include:: cc-attribution.txt diff --git a/source/lang/api/map.rst b/source/lang/api/map.rst new file mode 100644 index 0000000..79122b3 --- /dev/null +++ b/source/lang/api/map.rst @@ -0,0 +1,68 @@ +.. highlight:: cpp + +.. _lang-map: + +map() +===== + +Re-maps a number from one range to another. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: map + +Discussion +---------- + +``map()`` does not constrain values to within the range, because +out-of-range values are sometimes intended and useful. The +:ref:`constrain() ` macro may be used either before or +after this function, if limits to the ranges are desired. + +Note that the "lower bounds" of either range may be larger or smaller +than the "upper bounds" so that ``map()`` may be used to reverse a +range of numbers; for example:: + + y = map(x, 1, 50, 50, 1); + +The function also handles negative numbers well, so that this +example :: + + y = map(x, 1, 50, 50, -100); + +is also valid. + +The ``map()`` function uses integer math (its arguments and return +values all have type :ref:`long `), so it will not generate +fractions, when the math might indicate that it should do so. +Fractional remainders are truncated, and are not rounded or averaged. + +Example +------- + +:: + + /* Map an ADC reading (12 bits) to 16-bit PWM (0 to 65,535) */ + + void setup() { + pinMode(0, INPUT_ANALOG); + pinMode(9, PWM); + } + + void loop() { + int val = analogRead(0); + val = map(val, 0, 4095, 0, 65535); + analogWrite(9, val); + } + + +See Also +-------- + +- :ref:`constrain() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/max.rst b/source/lang/api/max.rst new file mode 100644 index 0000000..d38eebe --- /dev/null +++ b/source/lang/api/max.rst @@ -0,0 +1,65 @@ +.. highlight:: cpp + +.. _lang-max: + +max() +===== + +(Macro) Calculates the maximum of two numbers. + +Syntax +------ + +:: + + max(x, y) + +Parameters +---------- + +**x**: the first number; may be any number or numeric expression. + +**y**: the second number; may be any number or numeric expression. + + +Returns +------- + +The larger of the two parameter values. + +Example +------- + +:: + + sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 + // (effectively ensuring that it is at least 20) + +.. note:: Perhaps counter-intuitively, max() is often used to + constrain the lower end of a variable's range, while :ref:`min() + ` is used to constrain the upper end of the range. + +Warning +------- + +Because of the way ``max()`` is implemented, avoid using other +functions inside the parentheses. It may lead to incorrect results:: + + max(a--, 0); // avoid this - yields incorrect results + + a--; // use this instead - + max(a, 0); // keep other operations outside max() + +Arduino Compatibility +--------------------- + +The Maple version of ``max()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`min() ` +- :ref:`constrain() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/micros.rst b/source/lang/api/micros.rst new file mode 100644 index 0000000..f12976b --- /dev/null +++ b/source/lang/api/micros.rst @@ -0,0 +1,46 @@ +.. highlight:: cpp + +.. _lang-micros: + +micros() +======== + +Returns the number of microseconds since the Maple board began running +the current program. This number will overflow (go back to zero), +after approximately 70 minutes. + +.. note:: There are 1,000 microseconds in a millisecond, and 1,000,000 + microseconds in a second. + +Library Documentation +--------------------- + +.. doxygenfunction:: micros + +Example +------- + +:: + + unsigned int time; + + void setup() { + } + + void loop() { + SerialUSB.print("Time: "); + time = micros(); + // prints time since program started + SerialUSB.println(time); + // wait a second so as not to send massive amounts of data + delay(1000); + } + +See Also +-------- + +- :ref:`millis() ` +- :ref:`delay() ` +- :ref:`delayMicroseconds() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/millis.rst b/source/lang/api/millis.rst new file mode 100644 index 0000000..54e4507 --- /dev/null +++ b/source/lang/api/millis.rst @@ -0,0 +1,52 @@ +.. highlight:: cpp + +.. _lang-millis: + +millis() +======== + +Returns the number of milliseconds since the Maple board began running +the current program. This number will overflow (go back to zero) after +approximately 50 days. + +Library Documentation +--------------------- + +.. doxygenfunction:: millis + +Example +------- + +The following time prints the value returned by ``millis()`` roughly +once per second:: + + unsigned int time; + + void setup() { + } + + void loop() { + SerialUSB.print("Time: "); + time = millis(); + // prints time since program started + Serial.println(time); + + // wait a second so as not to send massive amounts of data + delay(1000); + } + +Tip +--- + +Since the return value for ``millis()`` is an :ref:`unsigned long +`, overflow errors may occur if you try to do math +with other data types, such as :ref:`ints `. + +See Also +-------- + +- :ref:`micros ` +- :ref:`delay ` +- :ref:`delayMicroseconds ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/min.rst b/source/lang/api/min.rst new file mode 100644 index 0000000..1245f6f --- /dev/null +++ b/source/lang/api/min.rst @@ -0,0 +1,66 @@ +.. highlight:: cpp + +.. _lang-min: + +min() +===== + +(Macro) Calculates the minimum of two numbers. + +Syntax +------ + +:: + + min(x,y) + +Parameters +---------- + +**x**: the first number; may be any number or numeric expression. + +**y**: the second number; may be any number or numeric expression. + +Returns +------- + +The smaller of the two numbers. + +Example +------- + +:: + + sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 + // ensuring that it never gets above 100. + + +.. note:: Perhaps counter-intuitively, max() is often used to + constrain the lower end of a variable's range, while min() is used + to constrain the upper end of the range. + + +Warning +------- + +Because of the way ``min()`` is implemented, avoid using other +functions inside the parentheses. It may lead to incorrect results:: + + min(a++, 100); // avoid this - yields incorrect results + + a++; // use this instead - + min(a, 100); // keep other operations outside min() + +Arduino Compatibility +--------------------- + +The Maple version of ``min()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`max() ` +- :ref:`constrain() ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/pinmode.rst b/source/lang/api/pinmode.rst new file mode 100644 index 0000000..b9095da --- /dev/null +++ b/source/lang/api/pinmode.rst @@ -0,0 +1,77 @@ +.. highlight:: cpp + +.. _lang-pinmode: + +pinMode() +========= + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: pinMode + +.. doxygenenum:: WiringPinMode + +Discussion +---------- + +``pinMode()`` is usually called within :ref:`lang-setup` in order to +configure a pin for a certain usage (although it may be called +anywhere). + +Example +------- + +:: + + int ledPin = 13; // LED connected to digital pin 13 + + void setup() { + pinMode(ledPin, OUTPUT); // sets the digital pin as output + } + + void loop() { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second + } + +Arduino Compatibility +--------------------- + +.. TODO check out Arduino vs. Maple static discilpline cutoffs to +.. ensure accuracy of following: + +The libmaple implementation of ``pinMode()`` supports the ``INPUT`` +and ``OUTPUT`` modes with semantics identical to that of the Arduino +function (however, be advised that the Maple, as a 3.3V device, will +only drive 3.3V to an ``OUTPUT`` pin that has been set ``HIGH``). + +``INPUT_ANALOG`` and ``PWM`` modes were added because the Maple does +not distinguish between analog and digital pins the same way the +Arduino does. Unlike the Arduino, you **must call** ``pinMode()`` to +set up a pin for these purposes before a call to, e.g., +:ref:`lang-analogRead`. In practice, this should only add a few lines +to your :ref:`lang-setup` function. + +.. TODO verify following before putting it in: + +.. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and +.. ``PWM_OPEN_DRAIN`` modes represent functionality not currently +.. available on Arduino boards. + +See also +-------- + +- :ref:`lang-constants` +- :ref:`lang-digitalwrite` +- :ref:`lang-digitalread` +- Maple :ref:`GPIO ` reference page + + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/pow.rst b/source/lang/api/pow.rst new file mode 100644 index 0000000..4280400 --- /dev/null +++ b/source/lang/api/pow.rst @@ -0,0 +1,23 @@ +.. _lang-pow: + +pow() +===== + +Calculates the value of a number raised to a power. + +Library Documentation +--------------------- + +.. doxygenfunction:: pow + +.. TODO LATER some examples + +See Also +-------- + +- :ref:`sqrt() ` +- :ref:`float ` +- :ref:`double ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst new file mode 100644 index 0000000..7a1d51f --- /dev/null +++ b/source/lang/api/pwmwrite.rst @@ -0,0 +1,49 @@ +.. highlight:: cpp + +.. _lang-pwmwrite: + +pwmWrite() +========== + +Writes a :ref:`PWM wave ` to a pin. You can use this to make an +LED get brighter or dimmer, control a servomotor, etc. After a call to +pwmWrite(), the pin will output a steady square wave with the given +duty cycle. You can change the duty cycle later by calling pwmWrite() +again with the same pin and a different duty. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: pwmWrite + +Example +------- + +Sets the output to the LED proportional to the value read from the +potentiometer:: + + int ledPin = 13; // LED connected to pin 13 (Maple) + int analogPin = 3; // potentiometer connected to analog pin 3 + int val = 0; // variable to store the read value + + void setup() { + pinMode(ledPin, OUTPUT); // sets the LED pin as output + + pinMode(analogPin, PWM); // sets the potentiometer pin as PWM + // output + } + + void loop() { + val = analogRead(analogPin); // read the input pin + + analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, + // analogWrite values from 0 to 65535 + } + +See Also +-------- + +- :ref:`Maple PWM tutorial ` diff --git a/source/lang/api/random.rst b/source/lang/api/random.rst new file mode 100644 index 0000000..f2a9762 --- /dev/null +++ b/source/lang/api/random.rst @@ -0,0 +1,73 @@ +.. highlight:: cpp + +.. _lang-random: + +random() +======== + +The ``random()`` function generates pseudo-random numbers. + +.. TODO keep tracking Sphinx/Breathe's ability to reference overloaded +.. functions so we can use doxygenfunction instead of manually +.. documenting this. + +Library Documentation +--------------------- + +.. cpp:function:: random(long max) + + Same as a call to ``random(0, max)``. + +.. cpp:function:: random(long min, long max) + + Generate a pseudo-random number with given lower and upper bounds. + + *Parameters* + + - ``min`` - Lower bound on the returned value, inclusive + - ``max`` - Upper bound on the returned value, exclusive + + *Returns*: A pseudo-random number in the range [min, max). + +Discussion +---------- + +If it is important for a sequence of values generated by +:ref:`random() ` to differ, on subsequent executions of a +sketch, use :ref:`randomSeed() ` to initialize the +random number generator with a fairly random input, such as +:ref:`analogRead() ` on an unconnected pin. + +Conversely, it can occasionally be useful to use pseudorandom +sequences that repeat exactly. This can be accomplished by calling +``randomSeed()`` with a fixed number, before starting the random +sequence. + +Example +------- + +The following sketch initializes the random seed based on an :ref:`ADC +` reading of pin 0. If this pin is unconnected, the Sketch +should print different values to the :ref:`serial monitor +` each time it is run:: + + long randNumber; + + void setup() { + pinMode(0, INPUT_ANALOG); + randomSeed(analogRead(0)); + } + + void loop() { + randNumber = random(300); + SerialUSB.println(randNumber); + + delay(50); + } + +See Also +-------- + +- :ref:`randomSeed() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/randomseed.rst b/source/lang/api/randomseed.rst new file mode 100644 index 0000000..d0a15b7 --- /dev/null +++ b/source/lang/api/randomseed.rst @@ -0,0 +1,60 @@ +.. highlight:: cpp + +.. _lang-randomseed: + +randomSeed() +============ + +``randomSeed()`` initializes the `pseudorandom number generator +`_, +causing it to start at an arbitrary point in its random sequence. +This sequence, while very long, and random, is always the same. + + +Library Documentation +--------------------- + +.. doxygenfunction:: randomSeed + +Discussion +---------- + +If it is important for a sequence of values generated by +:ref:`random() ` to differ, on subsequent executions of a +sketch, use ``randomSeed()`` to initialize the random number generator +with a fairly random input, such as :ref:`analogRead() +` on an unconnected pin. + +Conversely, it can occasionally be useful to use pseudorandom +sequences that repeat exactly. This can be accomplished by calling +``randomSeed()`` with a fixed number, before starting the random +sequence. + +Example +------- + +The following sketch initializes the random seed based on an :ref:`ADC +` reading of pin 0. If this pin is unconnected, the Sketch +should print different values to the :ref:`serial monitor +` each time it is run:: + + long randNumber; + + void setup() { + pinMode(0, INPUT_ANALOG); + randomSeed(analogRead(0)); + } + + void loop() { + randNumber = random(300); + SerialUSB.println(randNumber); + + delay(50); + } + +See Also +-------- + +- :ref:`random() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst new file mode 100644 index 0000000..ca89b31 --- /dev/null +++ b/source/lang/api/serial.rst @@ -0,0 +1,226 @@ +.. _lang-serial: + +Serial Ports (``Serial1``, ``Serial2``, ``Serial3``) +==================================================== + +Used for communication between the Maple board and a computer or other +devices. + +.. contents:: Contents + :local: + +Introduction +------------ + +The Maple has three serial ports (also known as a UARTs or USARTs): +``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the +pins summarized in the following table: + +.. list-table:: + :header-rows: 1 + + * - Serial port + - TX, RX, CK + - CTS, RTS (if present) + + * - ``Serial1`` + - 7, 8, 6 + - + + * - ``Serial2`` + - 1, 0, 10 + - 2, 3 + + * - ``Serial3`` + - 29, 30, 31 + - 32, 33 + +Thus, if you use a particular serial port, you cannot also use its +communication pins for other purposes at the same time. + +If you want to communicate with the Maple using the provided USB port, +use :ref:`SerialUSB ` instead. + +To use them to communicate with an external TTL serial device, connect +the TX pin to your device's RX pin, the RX to your device's TX pin, +and the ground of your Maple to your device's ground. + +.. warning:: Don't connect these pins directly to an RS232 serial + port; they operate at +/- 12V and can damage your board. + + +Library Documentation +--------------------- + +All of the ``Serial[1,2,3]`` objects are instances of the +``HardwareSerial`` class, which is documented in this section. (This +means that you can use any of these functions on any of ``Serial1``, +``Serial2``, and ``Serial3``). + +.. cpp:class:: HardwareSerial + + Serial port class. Predefined instances are ``Serial1``, + ``Serial2``, and ``Serial3``. + +.. cpp:function:: HardwareSerial::begin(unsigned int baud) + + Set up a ``HardwareSerial`` object for communications. This method + must be called before attempting to use the ``HardwareSerial`` + object (typically, you call this in your :ref:`setup() + ` function). + +.. cpp:function:: HardwareSerial::end() + + Disables the USART associated with this object, allowing any + associated communication pins to be used for other purposes. + +.. cpp:function:: unsigned int HardwareSerial::available() + + Returns the number of bytes available for reading. + +.. cpp:function:: unsigned char HardwareSerial::read() + + Returns the next available, unread character. If there are no + available characters (you can check this with :cpp:func:`available + `), the call will block until one + becomes available. + +.. cpp:function:: HardwareSerial::flush() + + Removes the contents of the Serial's associated USART RX FIFO. + That is, clears any buffered characters, so that the next character + read is guaranteed to be new. + +.. cpp:function:: HardwareSerial::print(unsigned char b) + + Print the given byte over the USART. + +.. cpp:function:: HardwareSerial::print(char c) + + Print the given character over the USART. 7-bit clean characters + are typically interpreted as ASCII text. + +.. cpp:function:: HardwareSerial::print(const char *str) + + Print the given null-terminated string over the USART. + +.. cpp:function:: HardwareSerial::print(int n) + + Print the argument's digits over the USART, in decimal format. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: HardwareSerial::print(unsigned int n) + + Print the argument's digits over the USART, in decimal format. + +.. cpp:function:: HardwareSerial::print(long n) + + Print the argument's digits over the USART, in decimal format. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: HardwareSerial::print(unsigned long n) + + Print the argument's digits over the USART, in decimal format. + +.. cpp:function:: HardwareSerial::print(long n, int base) + + Print the digits of ``n`` over the USART, in base ``base`` (which + may be between 2 and 16). The ``base`` value 2 corresponds to + binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative + values will be prefixed with a ``'-'`` character. + +.. cpp:function:: HardwareSerial::print(double n) + + Print ``n``, accurate to 2 digits after the decimal point. + +.. _lang-serial-println: + +.. cpp:function:: HardwareSerial::println(char c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(const char *c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(unsigned char b) + + Like ``print(b)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(unsigned int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(unsigned long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(long n, int base) + + Like ``print(n, b)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(double n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println() + + Prints ``"\r\n"`` over the USART. + +.. cpp:function:: HardwareSerial::write(unsigned char ch) + + Sends one character over the USART. This function is currently + blocking, although nonblocking writes are a planned future + extension. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +.. cpp:function:: HardwareSerial::write(const char* str) + + Send the given null-terminated character string over the USART. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +.. cpp:function:: HardwareSerial::write(void *buf, unsigned int size) + + Writes the first ``size`` bytes of ``buf`` over the USART. Each + byte is transmitted as an individual character. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +Arduino Compatibility Note +-------------------------- + +Unlike the Arduino, none of the Maple's serial ports is connected to +the USB port on the Maple board (for that, use :ref:`SerialUSB +`). Thus, to use these pins to communicate with your +personal computer, you will need an additional USB-to-serial adaptor. + +.. TODO LATER port these examples over + +.. Examples +.. -------- + +.. - `ASCII Table `_ +.. - `Dimmer `_ +.. - `Graph `_ +.. - `Physical Pixel `_ +.. - `Virtual Color Mixer `_ +.. - `Serial Call Response `_ +.. - `Serial Call Response ASCII `_ + +.. include:: cc-attribution.txt diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst new file mode 100644 index 0000000..af3a7e0 --- /dev/null +++ b/source/lang/api/serialusb.rst @@ -0,0 +1,242 @@ +.. highlight:: cpp + +.. _lang-serialusb: + +``SerialUSB`` +============= + +Used for communication between the Maple board and a computer. + +.. contents:: Contents + :local: + +Introduction +------------ + +In addition to three :ref:`serial ports `, the Maple's +STM32 microprocessor includes a dedicated USB peripheral. This +peripheral is used to emulate a regular serial port for use as a +terminal (text read/write). The emulated terminal is relatively slow +and inefficient; it is best for transferring data at regular serial +speeds (kilobaud). + +Library access to the emulated serial port is provided through the +``SerialUSB`` object. You can mostly use ``SerialUSB`` as a drop-in +replacement for ``Serial1``, ``Serial2``, and ``Serial3``. + +.. warning:: The ``SerialUSB`` functionality includes a 50 millisecond + timeout for writes, and does not try to detect if the USB host is + "really" connected, or just enumerated and initialized. + + This means that if you have a number of calls to one of the + ``SerialUSB`` ``write()`` or ``print()`` functions in your code, + and you are not monitoring the emulated on a computer, your program + will run much, much slower than if it is being monitored or totally + disconnected (run off of a battery). + + You can avoid this behavior by :ref:`deciphering the port status + using the DTR and RTS line status `; the + behavior of these control lines is platform dependent and we no + longer interpret them by default. + +Library Documentation +--------------------- + +The ``SerialUSB`` object is an instance of the ``USBSerial`` class, +which is documented in this section. This means that you can use any +of these functions by writing +``SerialUSB.functionName(arguments...)``. For example, to print the +message "hello, world!", you can write ``USBSerial.println("hello, +world!")``. + +.. cpp:class:: USBSerial + + Emulated serial-over-USB class. ``SerialUSB`` is the predefined + instance. + +.. cpp:function:: USBSerial::begin() + + Set up the USB peripheral for emulated serial communication. The + peripheral is configured this way by default; calling this function + should only be necessary if you have disabled the peripheral using + ``SerialUSB.end()``. + +.. _lang-serialusb-end: + +.. cpp:function:: USBSerial::end() + + Disables the USB peripheral. + +.. cpp:function:: unsigned int USBSerial::available() + + Returns the number of bytes available for reading. + +.. _lang-serialusb-read: + +.. cpp:function:: unsigned char USBSerial::read() + + Returns the next available, unread character. If there are no + available characters (you can check this with :cpp:func:`available + `), the call will block until one + becomes available. + +.. cpp:function:: USBSerial::flush() + + Removes the contents of the Serial's associated input buffer. That + is, clears any buffered characters, so that the next character read + is guaranteed to be new. + +.. cpp:function:: USBSerial::print(unsigned char b) + + Print the given byte over the USB connection. + +.. cpp:function:: USBSerial::print(char c) + + Print the given character over the USB connection. 7-bit clean characters + are typically interpreted as ASCII text. + +.. cpp:function:: USBSerial::print(const char *str) + + Print the given null-terminated string over the USB connection. + +.. cpp:function:: USBSerial::print(int n) + + Print the argument's digits over the USB connection, in decimal format. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: USBSerial::print(unsigned int n) + + Print the argument's digits over the USB connection, in decimal format. + +.. cpp:function:: USBSerial::print(long n) + + Print the argument's digits over the USB connection, in decimal + format. Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: USBSerial::print(unsigned long n) + + Print the argument's digits over the USB connection, in decimal + format. + +.. cpp:function:: USBSerial::print(long n, int base) + + Print the digits of ``n`` over the USB connection, in base ``base`` + (which may be between 2 and 16). The ``base`` value 2 corresponds + to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. + Negative values will be prefixed with a ``'-'`` character. + +.. cpp:function:: USBSerial::print(double n) + + Print ``n``, accurate to 2 digits after the decimal point. + +.. _lang-serialusb-println: + +.. cpp:function:: USBSerial::println(char c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(const char *c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(unsigned char b) + + Like ``print(b)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(unsigned int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(unsigned long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(long n, int base) + + Like ``print(n, b)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(double n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println() + + Prints ``"\r\n"`` over the USB connection. + +.. cpp:function:: USBSerial::write(unsigned char ch) + + Sends one character over the USB connection. This function is + currently blocking, although nonblocking writes are a planned + future extension. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +.. cpp:function:: USBSerial::write(const char* str) + + Send the given null-terminated character string over the USB + connection. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +.. cpp:function:: USBSerial::write(void *buf, unsigned int size) + + Writes the first ``size`` bytes of ``buf`` over the USB connection. + Each byte is transmitted as an individual character. + + This is a low-level function. One of the ``print()`` or + ``println()`` functions is likely to be more useful when printing + multiple characters, when formatting numbers for printing, etc. + +Examples +-------- + +.. _lang-serialusb-safe-print: + +**Safe print**: This function should run smoothly and not block; the +LED should blink at roughly the same speed whether being monitored, +running from battery, or connected but not monitored. You may need to +experiment with the DTR/RTS logic for your platform and device +configuration. :: + + #define LED_PIN 13 + + void setup() { + /* Set up the LED to blink */ + pinMode(LED_PIN, OUTPUT); + } + + void loop() { + // LED will stay off if we are disconnected; + // will blink quickly if USB is unplugged (battery etc) + if(SerialUSB.isConnected()) { + digitalWrite(LED_PIN, 1); + } + delay(100); + + // If this logic fails to detect if bytes are going to + // be read by the USB host, then the println() will fully + // many times, causing a very slow LED blink. + // If the characters are printed and read, the blink will + // only slow a small amount when "really" connected, and fast + // when the virtual port is only configured. + if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) { + for(int i=0; i<10; i++) { + SerialUSB.println(123456,BIN); + } + } + digitalWrite(LED_PIN, 0); + delay(100); + } + diff --git a/source/lang/api/setup.rst b/source/lang/api/setup.rst new file mode 100644 index 0000000..837ddd6 --- /dev/null +++ b/source/lang/api/setup.rst @@ -0,0 +1,29 @@ +.. highlight:: cpp + +.. _lang-setup: + +setup() +======= + +The ``setup()`` function is called when a sketch starts. Use it to +initialize :ref:`variables `, :ref:`pin modes +`, start using :ref:`libraries `, etc. The +``setup()`` function will only run once, after each power-up or reset +of the Maple board. + +Example +------- + +:: + + int buttonPin = 38; + + void setup() { + pinMode(buttonPin, INPUT); + } + + void loop() { + // ... + } + +.. include:: cc-attribution.txt diff --git a/source/lang/api/sin.rst b/source/lang/api/sin.rst new file mode 100644 index 0000000..398b8f3 --- /dev/null +++ b/source/lang/api/sin.rst @@ -0,0 +1,32 @@ +.. _lang-sin: + +sin() +===== + +Calculates the `sine `_ of an +angle. + +Library Documentation +--------------------- + +.. doxygenfunction:: sin + +Arduino Compatibility +--------------------- + +The Maple version of ``sin()`` is compatible with Arduino. + +Note that the Maple implementation comes from `newlib +`_\ , while Arduino's is that of +`avr-libc `_\ . + +See Also +-------- + +- :ref:`cos ` +- :ref:`tan ` +- :ref:`float ` +- :ref:`double ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/sq.rst b/source/lang/api/sq.rst new file mode 100644 index 0000000..bd32648 --- /dev/null +++ b/source/lang/api/sq.rst @@ -0,0 +1,46 @@ +.. highlight:: cpp + +.. _lang-sq: + +sq() +==== + +(Macro) computes the square of a number. + +Syntax +------ + +:: + + sq(a) + +Parameters +---------- + +**a**: the number. + +Returns +------- + +**a** squared (**a** × **a**). + +Warning +------- + +Because of the way ``sq()`` is implemented, avoid using other +functions or causing side effects inside the parentheses, as it may +lead to incorrect results:: + + b = sq(a++); // avoid this - yields incorrect results + + b = sq(a); // use this instead - + a++; // keep other operations outside sq() + + +Arduino Compatibility +--------------------- + +Maple's implementation of ``sq()`` is compatible with Arduino. + + +.. include:: cc-attribution.txt diff --git a/source/lang/api/tan.rst b/source/lang/api/tan.rst new file mode 100644 index 0000000..4bbe0db --- /dev/null +++ b/source/lang/api/tan.rst @@ -0,0 +1,31 @@ +.. _lang-tan: + +tan() +===== + +Calculates the tangent of an angle. + +Library Documentation +--------------------- + +.. doxygenfunction:: tan + +Arduino Compatibility +--------------------- + +The Maple version of ``tan()`` is compatible with Arduino. + +Note that the Maple implementation comes from `newlib +`_\ , while Arduino's is that of +`avr-libc `_\ . + +See Also +-------- + + +- :ref:`sin ` +- :ref:`cos ` +- :ref:`float ` +- :ref:`double ` + +.. include:: cc-attribution.txt diff --git a/source/lang/api/volatile.rst b/source/lang/api/volatile.rst new file mode 100644 index 0000000..276bb6a --- /dev/null +++ b/source/lang/api/volatile.rst @@ -0,0 +1,65 @@ +.. highlight:: cpp + +.. _lang-volatile: + +``volatile`` +============ + +The ``volatile`` keyword known is a variable *qualifier*. It is +usually used before the datatype of a variable, to modify the way in +which the compiler treats the variable. + +Declaring a variable ``volatile`` is a directive to the compiler. The +compiler is software which translates your C++ code into the machine +code, which are the real instructions for the STM32 chip in the +Maple. (The particular compiler we provide for use with the Maple is a +version of :ref:`GCC `). + +Specifically, it directs the compiler to read the variable's value +fresh every time it is used, rather than "backing up" the value and +reading from its backup copy. (Compilers often "back up" a variable's +value in RAM into a storage location called a *register*; this is done +for efficiency). + +A variable should be declared ``volatile`` whenever its value can be +changed by something beyond the control of the code section in which +it appears, such as an :ref:`external interrupt +`. On the Maple, the only place that this is +likely to occur is in sections of code associated with interrupts. + +Example +------- + +:: + + // toggles LED when interrupt pin changes state + + int pin = 13; + volatile int state = LOW; + + void setup() { + pinMode(pin, OUTPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() { + digitalWrite(pin, state); + } + + void blink() { + if (state == HIGH) { + state = LOW; + } else { + // state must be HIGH + state = HIGH; + } + } + +See also +-------- + +- :ref:`External Interrupts ` +- :ref:`lang-attachinterrupt` +- :ref:`lang-detachinterrupt` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/arithmetic.rst b/source/lang/cpp/arithmetic.rst new file mode 100644 index 0000000..91fe22e --- /dev/null +++ b/source/lang/cpp/arithmetic.rst @@ -0,0 +1,127 @@ +.. highlight:: cpp + +.. _lang-arithmetic: + +Arithmetic Operators (``+``, ``-``, ``*``, ``/``) +================================================= + +The operators ``+``, ``-``, ``*``, and ``/`` respectively evaluate to +the sum, difference, product, or quotient (respectively) of the two +operands. The operation is conducted using the data type of the +operands, so, for example, ``9 / 4`` gives ``2`` since 9 and 4 are +:ref:`int variables `. + +This also means that the operation can overflow if the result is +larger than that which can be stored in the data type (e.g. adding 1 +to an :ref:`lang-int` with the value 2,147,483,647 gives +-2,147,483,648). + +.. _lang-arithmetic-typeconversion: + +If the operands are of different types, the "larger" type is used for +the calculation. If one of the numbers (operands) are of the type +**float** or of type **double**, floating point math will be used for +the calculation. + +.. note:: The specifics of these rules are beyond the scope of this + documentation; for more information, see `The C++ Programming + Language `_\ , by Bjarne + Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks + entry on C++ type conversion + `_. + +.. note:: For more information on how computers represent integers, + see the Wikipedia page on `two's complement + `_. + +.. contents:: Contents + :local: + +Examples +-------- + + :: + + y = y + 3; + x = x - 7; + i = j * 6; + r = r / 5; + + +Syntax +------ + + :: + + result = value1 + value2; + result = value1 - value2; + result = value1 * value2; + result = value1 / value2; + + +Parameters +---------- + +**value1**: any numeric variable or constant + +**value2**: any numeric variable or constant + +Programming Tips +---------------- + +- Know that :ref:`integer constants ` + default to :ref:`int `, so some constant calculations + may overflow (e.g., 200000 * 5000000 will yield a negative result). + +- Choose variable sizes that are large enough to hold the largest + results from your calculations. + +- Know at what point your variable will "roll over" and also what + happens in the other direction e.g. (0 - 1) for unsigned arithmetic, + or (0 - -2,147,483,648) for signed arithmetic. + +- For math that requires fractions, float variables may be used, but + be aware of their drawbacks: large size and slow computation speeds + (the STM32 has no floating point hardware, so all floating point + calculations have to be done in software). + +- Use cast operator, e.g. ``(int)myFloat`` to convert one variable type + to another on the fly. + +Arduino Compatibility +--------------------- + +Since the STM32 processor on the Maple is a 32-bit machine, the int +type overflows at a much higher value on Maple than on Arduino. In +particular, on Maple, ints do not overflow (become negative) until +they reach 2,147,483,648; on the Arduino, they overflow at 32,767. +Because of this, programs running on Maple are much less likely to run +into overflow issues. The following table summarizes the sizes and +ranges of integer datatypes on the Maple (the ranges of long long +types are approximate): + +.. _lang-arithmetic-int-sizes: + +.. csv-table:: + :header: Datatype, Unsigned range, Signed range, Size (bytes) + :widths: 8, 12, 17, 8 + + ``char``, 0 --- 255, -128 --- 127, 1 + ``short``, "0 --- 65,535", "-32,768 --- 32,767", 2 + ``int``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 + ``long``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 + ``long long``, "0 --- 1.8*10\ :sup:`19`\ " (approx.), "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 + + +See Also +-------- + +- The individual sizes (in bits) of various available types are + defined in `libmaple_types.h + `_\ + . + +- :ref:`sizeof `\ () + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/array.rst b/source/lang/cpp/array.rst new file mode 100644 index 0000000..30a818f --- /dev/null +++ b/source/lang/cpp/array.rst @@ -0,0 +1,123 @@ +.. highlight:: cpp + +.. _lang-array: + +Arrays +====== + +An array is a collection of variables that are accessed with an index +number. Arrays in the C++ programming language, in which the Maple is +programmed, can be complicated, but using simple arrays is relatively +straightforward. + +.. contents:: Contents + :local: + +Creating (Declaring) an Array +----------------------------- + +All of the methods below are valid ways to create (declare) an +array. :: + + int myInts[6]; + int myPins[] = {2, 4, 8, 3, 6}; + int mySensVals[6] = {2, 4, -8, 3, 2}; + char message[6] = "hello"; + +You can declare an array without initializing it, as with myInts. In +the line referring to myPins, we declare an array without explicitly +choosing a size. The compiler counts the elements and creates an +array of the appropriate size. + +Finally, you can both initialize and size your array, as in +mySensVals. Note that when declaring an array with elements of type +char, one more element than your initialization is required, to hold +the required `null character `_. + + +Accessing an Array +------------------ + + +.. compound:: + + Arrays are **zero indexed**; that is, referring to the array + initialization above, the first element of the array is at index 0, + hence :: + + mySensVals[0] == 2; + mySensVals[1] == 4 + + and so forth. + +It also means that in an array with ten elements, index nine is the +last element. Hence:: + + int myArray[10]={9,3,2,4,3,2,7,8,9,11}; + // myArray[9] contains 11 + // myArray[10] is invalid and contains random information (other memory address) + +For this reason, you should be careful in accessing arrays. Accessing +past the end of an array (using an index number greater than your +declared array size - 1) is reading from memory that is in use for +other purposes. Reading from these locations is probably not going to +do much except yield invalid data. Writing to random memory locations +is definitely a bad idea, and can often lead to unhappy results such +as crashes or program malfunction. This can also be a difficult bug to +track down. + +Unlike Basic or Java, the C compiler does no checking to see if array +access is within legal bounds of the array size that you have +declared. + + +To assign a value to an array +----------------------------- + :: + + mySensVals[0] = 10; + + +To retrieve a value from an array +--------------------------------- + + :: + + x = mySensVals[4]; + + +Arrays and ``for`` Loops +------------------------ + +Arrays are often manipulated inside :ref:`for loops `, where +the loop counter is used as the index for each array element. For +example, to print the elements of an array over the serial port, you +could do something like this:: + + int i; + for (i = 0; i < 5; i = i + 1) { + SerialUSB.println(myPins[i]); + } + + +Example +------- + +For a complete program that demonstrates the use of arrays, see the +Arduino `Knight Rider example +`_\ (which will run +unmodified on the Maple). + +Arduino Compatibility +--------------------- + +Arrays on Maple are identical those on Arduino. + +See also +-------- + +- :ref:`Storing arrays in FLASH memory ` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/assignment.rst b/source/lang/cpp/assignment.rst new file mode 100644 index 0000000..b6ad4d5 --- /dev/null +++ b/source/lang/cpp/assignment.rst @@ -0,0 +1,70 @@ +.. highlight:: cpp + +.. _lang-assignment: + +Assignment Operator (``=``) +=========================== + +Stores the value to the right of the equal sign in the variable to +the left of the equal sign. + +The single equal sign in the C++ programming language is called the +assignment operator. It has a different meaning than in algebra +class, where it indicated an equation or equality. The assignment +operator tells the microcontroller to evaluate whatever value or +expression is on the right side of the equal sign, and store it in +the variable to the left of the equal sign [#fgross]_. + + + +Example +------- + +:: + + int sensVal; // declare an integer variable named sensVal + senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal + + + +Programming Tips +---------------- + +The variable on the left side of the assignment operator ( = sign ) +needs to be able to hold the value stored in it. If it is not large +enough to hold a value, the value stored in the variable will be +incorrect. + +Don't confuse the assignment operator [ = ] (single equal sign) +with the comparison operator [ == ] (double equal signs), which +evaluates whether two expressions are equal. + + +Arduino Compatibility +--------------------- + +Assignments on the Maple are identical to those on Arduino. + + + +See Also +-------- + + +- `if (comparison operators) `_ +- `char `_ +- `int `_ +- `long `_ + + +.. rubric:: Footnotes + +.. [#fgross] Experienced C++ programmers know this to be an + oversimplification of what happens when the variable on the left + hand side is an object. See Richard Gillam's wonderful and scary + `The Anatomy of the Assignment Operator + `_ + for more information. + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/bitshift.rst b/source/lang/cpp/bitshift.rst new file mode 100644 index 0000000..e1c8de0 --- /dev/null +++ b/source/lang/cpp/bitshift.rst @@ -0,0 +1,144 @@ +.. highlight:: cpp + +.. _lang-bitshift: + +Bit Shift Operators (``<<``, ``>>``) +==================================== + +(Adapted from `The Bit Math Tutorial +`_ in `The Arduino +Playground `_\ ) + +There are two bit shift operators in C++: the left shift operator +``<<`` and the right shift operator ``>>``. These operators cause the +bits in the left operand to be shifted left or right by the number of +positions specified by the right operand. + +More information on bitwise math can be obtained in the Wikipedia +article on `bitwise operations +`_\ , especially the +section on shifts in `C, C++, and Java +`_\ . + + +Syntax +------ + +``some_int << number_of_bits`` + +``some_int >> number_of_bits`` + + +Parameters +---------- + +* **some_int** An integer value or variable. + +* **number_of_bits** integer whose value is at most ``8 * + sizeof(variable)`` (so ``number_of_bits`` can be at most 32 for + ``int`` values, at most ``8`` for ``char`` values, etc.; the various + integer sizes are summarized :ref:`in this table + `\ ). + + + +Example: +-------- + +Here are some examples of bit shifting, with the binary representation of the number in comments:: + + int a = 5; // binary: 101 + int b = a << 3; // binary: 101000, or 40 in decimal + int c = b >> 3; // binary: 101, or back to 5 like we started with + + +When you left shift a value x by y bits (x << y), the leftmost y bits +in x are lost, literally shifted out of existence. We'll do this +example with ``char`` values (which are integers in the range 0-255, +and take up 8 bits of memory):: + + char a = 5; // binary (all 8 bits): 00000101 + char b = a << 7; // binary: 10000000 - the first 1 in 101 was discarded + + +If you are certain that none of the ones in a value are being shifted +into oblivion, a simple way to think of the left-shift operator is +that it multiplies the left operand by 2 raised to the right operand +power (in math notation, ``x << y`` equals x * 2\ :sup:`y`\ , as long +as none of the bits of x get shifted out). For example, to generate +powers of 2, the following expressions can be employed:: + + 1 << 0 == 1 + 1 << 1 == 2 + 1 << 2 == 4 + 1 << 3 == 8 + ... + 1 << 8 == 256 + 1 << 9 == 512 + 1 << 10 == 1024 + ... + +.. _lang-bitshift-signbit-gotcha: + +When you shift x right by y bits (``x >> y``), and the highest bit in +x is a 1, the behavior depends on the exact data type of x. If x is of +type ``int``, the highest bit is special, and determines whether x is +negative or not; the details are too complicated to explain here, but +they are thoroughly explained in the Wikipedia article on `two's +complement arithmetic +`_\ , which the +system most computers use to store integers. In that case, the sign +bit is copied into lower bits, for esoteric historical reasons:: + + int x = -16; // binary (all 32 bits): 11111111111111111111111111110000 + int y = x >> 3; // binary: 11111111111111111111111111111110 + + + +This behavior, called "sign extension", is often not what you +want. You probably wish zeros to be shifted in from the left. It +turns out that the right shift rules are different for ``unsigned +int`` values, so you can use a type cast to suppress ones being copied +from the left:: + + int x = -16; // binary: 11111111111111111111111111110000 + int y = (unsigned int)x >> 3; // binary: 00011111111111111111111111111110 + + + +If you are careful to avoid sign extension, you can use the +right-shift operator, ``>>``, as a way to divide by powers of 2. For +example:: + + int x = 1000; + int y = x >> 3; // integer division of 1000 by 8, causing y = 125. + + +Arduino Compatibility +--------------------- + +Since it's part of the C++ language, bit shifting on the Maple is +compatible with the Arduino; however, you should keep in mind that the +Maple has bigger integer types (as in, more bits) than the Arduino. + +Since the STM32 is a 32-bit processor, the ``int`` type takes up 32 +bits instead of 16, like on Arduino's 16-bit microcontroller. This +means that you can shift left, like ``x << y``, with bigger values of +``y`` on the Maple before ones in ``x`` start to get shifted out. + +To calculate the number of bits of an integer type on the Maple, +multiply its size in bytes (see :ref:`this table +` for these) by 8, since there are 8 +bits in 1 byte. For example, a ``short`` takes up 2 bytes of memory, +or 2 * 8 = 16 bits. + +See Also +-------- + +- :ref:`lang-bit` +- :ref:`lang-bitread` +- :ref:`lang-bitwrite` +- :ref:`lang-bitclear` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/bitwisemath.rst b/source/lang/cpp/bitwisemath.rst new file mode 100644 index 0000000..28fe6bf --- /dev/null +++ b/source/lang/cpp/bitwisemath.rst @@ -0,0 +1,186 @@ +.. highlight:: cpp + +.. _lang-bitwisemath: + +Bitwise Operators (``&``, ``|``, ``^``, ``~``) +============================================== + +The bitwise operators perform their calculations at the bit level of +variables. They help solve a wide range of common programming +problems. + +Much of the material here is adapted for Maple from an (Arduino) +`tutorial on bitwise math +`_\ . Another great +resource is the Wikipedia article on `bitwise operations +`_\ . + +Below are descriptions and syntax for all of the operators. + +.. contents:: Contents + :local: + +.. _lang-bitwisemath-and: + +Bitwise AND (``&``) +------------------- + +The bitwise AND operator in C++ is a single ampersand, ``&``, used +between two other integer expressions. Bitwise AND operates on each +bit position of the surrounding expressions independently, according +to this rule: if both input bits are 1, the resulting output is 1, +otherwise the output is 0. Another way of expressing this is:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) = result + + +On the Maple, the type ``int`` is a 32-bit value, so using ``&`` +between two ``int`` expressions causes 32 simultaneous AND operations +to occur. In a code fragment like:: + + int a = 92; // in binary: 00000000000000000000000001011100 + int b = 101; // in binary: 00000000000000000000000001100101 + int c = a & b; // result: 00000000000000000000000001000100, + // (or 68 in decimal). + + +Each of the 32 bits in ``a`` and ``b`` are processed using bitwise +AND, and all 32 resulting bits are stored in ``c``, resulting in the +value 1000100 in binary, which is 68 in decimal. + + +.. _lang-bitwisemath-or: + +Bitwise OR (``|``) +------------------ + +The bitwise OR operator in C++ is the vertical bar symbol, ``|``. Like +the ``&`` operator, ``|`` operates independently on each bit in its +two surrounding integer expressions, but what it does is +different. The bitwise OR of two bits is 1 if either or both of the +input bits is 1, otherwise it is 0. For example:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) = result + +Here is an example of bitwise OR used in a snippet of C++ code (using +``char``, which takes up 8 bits of memory, instead of ``int``, which +uses 32):: + + char a = 92; // in binary: 01011100 + char b = 101; // in binary: 01100101 + char c = a | b; // result: 01111101, or 125 in decimal. + +.. _lang-bitwisemath-xor: + +Bitwise XOR (``^``) +------------------- + +There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE +OR, also known as bitwise XOR. (In English, this is usually pronounced +"zor" or "ex-or"). The bitwise XOR operator is written using the caret +symbol, ``^``. This operator is very similar to the bitwise OR +operator ``|``, except it evaluates to 0 for a given bit position when +both of the input bits for that position are 1:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) = result + + +Another way to look at bitwise XOR is that each bit in the result +is a 1 if the input bits are different, or 0 if they are the same. + +Here is a simple example:: + + int x = 12; // binary (ignoring extra bits): 1100 + int y = 10; // binary: 1010 + int z = x ^ y; // binary: 0110, or decimal 6 + + + +The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 +to 0) some of the bits in an integer expression. In a bitwise OR +operation if there is a 1 in the mask bit, that bit is inverted; if +there is a 0, the bit is not inverted and stays the same. Below is a +program to blink digital pin 13 (the LED pin on Maple):: + + // Blink Maple LED pin + + int led_pin = 13; + int toggle = 0; + + // demo for Exclusive OR + void setup(){ + pinMode(led_pin, OUTPUT); + } + + void loop(){ + toggle = toggle ^ 1; + digitalWrite(led_pin, toggle); + delay(100); + } + +.. _lang-bitwisemath-not: + +Bitwise NOT (``~``) +------------------- + +The bitwise NOT operator in C++ is the tilde character ``~``. Unlike +``&`` and ``|``, the bitwise NOT operator is applied to a single +operand to its right. Bitwise NOT changes each bit to its opposite: 0 +becomes 1, and 1 becomes 0. For example:: + + 0 1 operand1 + ---- + 1 0 ~operand1 = result + +Another example:: + + char a = 103; // binary: 01100111 + char b = ~a; // binary: 10011000 = -104 + +You might be surprised to see a negative number like -104 as the +result of this operation. This is because the highest bit in an int +variable is the so-called "sign bit". If the highest bit is 1, the +number is interpreted as negative. This encoding of positive and +negative numbers is referred to as *two's complement*. For more +information, see the Wikipedia article on `two's +complement. `_ + +As an aside, it is interesting to note that (under two's complement +arithmetic) for any integer ``x``, ``~x`` is the same as ``-x-1``. + +At times, the sign bit in a signed integer expression can cause +some unwanted surprises. + + +Uses +---- + +One of the most common uses of bitwise operations is to select or +manipulate a particular bit (or bits) from an integer value, often +called `bit masking +`_\ . See the +linked Wikipedia article for more information and examples. + +If you really want to see bit-twiddling techniques in their full +glory, you could do much worse than to get yourself a copy of +`Hacker's Delight `_\ . + + +See Also +-------- + +- :ref:`Boolean operations ` (``&&``, ``||``) +- :ref:`Compound bitwise operations ` (``&=``, + ``|=``, ``^=``). + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/boolean.rst b/source/lang/cpp/boolean.rst new file mode 100644 index 0000000..8d6aa5c --- /dev/null +++ b/source/lang/cpp/boolean.rst @@ -0,0 +1,91 @@ +.. highlight:: cpp + +.. _lang-boolean: + +Boolean Operators +================= + +These can be used inside the condition of an :ref:`if ` +statement. Evaluate to :ref:`true ` or +:ref:`false `. + +.. contents:: Contents + :local: + +.. _lang-boolean-and: + +&& (logical and) +---------------- + +True only if both operands are true. For example:: + + if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches + // ... + } + +is true only if both inputs are high. Another example:: + + if (a >= 10 && a <= 20){} // true if a is between 10 and 20 + +**Be careful** not to say ``10 <= a <= 20``! This won't work the way +you want. You have to separately test whether ``a`` is at least 10 +using ``a >= 10``, then test whether ``a`` is at most 20 using ``a <= +20``, then combine the results using ``&&``. + + +.. _lang-boolean-or: + +\|\| (logical or) +----------------- + +True if either operand is true. For example:: + + if (x > 0 || y > 0) { + // ... + } + +is true if either ``x`` or ``y`` is greater than 0. + +.. _lang-boolean-not: + +! (logical not) +--------------- + +True if the operand is false. For example:: + + if (!x) { + // ... + } + +is true if ``x`` is false (i.e. if ``x`` is zero). + +Some Advice +----------- + +.. warning:: + + Make sure you don't mistake the boolean AND operator ``&&`` + (double ampersand) for the :ref:`bitwise AND operator + ` ``&`` (single ampersand). They are + entirely different beasts. + + Similarly, do not confuse the boolean OR operator ``||`` (double + pipe) with the :ref:`bitwise OR operator ` + ``|`` (single pipe). + + The :ref:`bitwise NOT operator ` ``~`` + (tilde) looks much different than the boolean not operator ``!`` + (exclamation point, or "bang", as some programmers say), but you + still have to be sure which one you want. + + +See Also +-------- + +- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) +- :ref:`Compound bitwise operators ` (``&=``, + ``|=``, ``^=``). +- :ref:`if statement ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/booleanvariables.rst b/source/lang/cpp/booleanvariables.rst new file mode 100644 index 0000000..6051b8c --- /dev/null +++ b/source/lang/cpp/booleanvariables.rst @@ -0,0 +1,54 @@ +.. highlight:: cpp + +.. _lang-booleanvariables: + +Booleans +======== + +A **boolean** holds one of two values, :ref:`true +` or :ref:`false `. On a +Maple, each boolean variable has type ``bool``. + +.. warning:: + + On an Arduino, the type ``boolean`` is also provided. While the + Maple also has this type for compatibility, **its use is strongly + discouraged**. The ``bool`` type is a standard part of C++, while + ``boolean`` is a non-standard extension that serves no purpose. + +Example +------- + +:: + + int ledPin = 13; // LED on pin 13 + int switchPin = 12; // momentary switch on 12, other side connected to ground + + // running is a boolean variable: + bool running = false; + + void setup() { + pinMode(ledPin, OUTPUT); + pinMode(switchPin, INPUT); + digitalWrite(switchPin, HIGH); // turn on pullup resistor + } + + void loop() { + if (digitalRead(switchPin) == LOW) { + // switch is pressed - pullup keeps pin high normally + delay(100); // delay to debounce switch + running = !running; // toggle running variable + digitalWrite(ledPin, running) // indicate via LED + } + } + +See also +-------- + + +- :ref:`Boolean constants ` +- :ref:`Boolean operators ` +- :ref:`Variables ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/break.rst b/source/lang/cpp/break.rst new file mode 100644 index 0000000..ce8ac17 --- /dev/null +++ b/source/lang/cpp/break.rst @@ -0,0 +1,35 @@ +.. highlight:: cpp + +.. _lang-break: + +``break`` +========= + +``break`` is used to exit from a :ref:`while `\ , +:ref:`for `\ , or :ref:`do/while ` loop, +bypassing the normal loop condition. It is also used to exit from a +:ref:`switch ` statement. + + +Example +------- + +:: + + for (x = 0; x < 255; x ++) + { + digitalWrite(PWMpin, x); + sens = analogRead(sensorPin); + if (sens > threshold){ // bail out on sensor detect + x = 0; + // this line of code means that we'll immediately exit + // from the "for" loop: + break; + } + delay(50); + } + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/byte.rst b/source/lang/cpp/byte.rst new file mode 100644 index 0000000..45c9d5f --- /dev/null +++ b/source/lang/cpp/byte.rst @@ -0,0 +1,34 @@ +.. highlight:: cpp + +.. _lang-byte: + +byte +==== + +The ``byte`` type stores a 1-byte (8-bit) unsigned integer number, +from 0 to 255. + +.. warning:: + + The ``byte`` type is provided for compatibility with Arduino. + However, it is a non-standard extension. The standard C++ type for + storing an 8-bit unsigned integer is ``unsigned char``; we + recommend using that instead. (Your code will still work on an + Arduino). + + +Example +------- + +:: + + byte b = 134; + +See Also +-------- + +- :ref:`byte() ` (casting a value to a byte) +- :ref:`Variables ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/bytecast.rst b/source/lang/cpp/bytecast.rst new file mode 100644 index 0000000..b3f0de2 --- /dev/null +++ b/source/lang/cpp/bytecast.rst @@ -0,0 +1,50 @@ +.. highlight:: cpp + +.. _lang-bytecast: + +byte() (cast) +============= + +Converts a value to the :ref:`byte ` data type. + +.. note:: + + Casting to the byte type is provided for compatibility with + Arduino. However, the recommended Maple type for storing an 8-bit + unsigned integer is ``uint8``. (C and C++ programmers: ``stdint.h`` + is also available). + + In order to cast a variable ``x`` to a ``uint8``, the + following syntax can be used:: + + uint8(x); + +Syntax +------ + +``byte(x)`` + + +Parameters +---------- + +**x**: a value of any integer type + + +Returns +------- + +The value, converted to a ``byte``. Note, however, that if the value +is larger than the maximum value you can store in a byte (255), then +the results might be strange and unexpected. + + +See Also +-------- + +- :ref:`lang-byte` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/cc-attribution.txt b/source/lang/cpp/cc-attribution.txt new file mode 100644 index 0000000..e100140 --- /dev/null +++ b/source/lang/cpp/cc-attribution.txt @@ -0,0 +1,9 @@ +.. Included in all this directory's files in order to satisfy the +.. Arduino CC Attribution-ShareAlike 3.0 License + +.. admonition:: License and Attribution + + This documentation page was adapted from the `Arduino Reference + Documentation `_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License `_. diff --git a/source/lang/cpp/char.rst b/source/lang/cpp/char.rst new file mode 100644 index 0000000..b8747f3 --- /dev/null +++ b/source/lang/cpp/char.rst @@ -0,0 +1,50 @@ +.. highlight:: cpp + +.. _lang-char: + +``char`` +======== + +The ``char`` type stores a 1-byte character value (or integer with +value from -128 to 127). Character literals are written in single +quotes, like this: ``'A'`` (for multiple characters - strings - use +double quotes: ``"ABC"``). + + +Just like everything else on a computer, characters are stored as +numbers. You can see the specific encoding in the `ASCII chart +`_\ +. This means that it is possible to do arithmetic on characters, in +which the ASCII value of the character is used (e.g. ``'A' + 1`` has the +decimal value 66, since the ASCII value of the capital letter A in +decimal is 65). See the :ref:`Serial.println() +` documentation for more information about how +characters are converted into numbers. + +The ``char`` datatype is a signed type, meaning that it encodes +numbers from -128 to 127. For an unsigned type, which stores values +from 0 to 255, just use the type ``unsigned char`` (two words). + + +Example +------- + +:: + + // the following two lines are equivalent, using the ASCII + // character encoding: + char c = 'A'; + char c = 65; + + +See also +-------- + + +- :ref:`lang-int` +- :ref:`lang-array` (a string is just an array of ``char``\ s) +- :ref:`Serial.println() ` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/charcast.rst b/source/lang/cpp/charcast.rst new file mode 100644 index 0000000..a480dec --- /dev/null +++ b/source/lang/cpp/charcast.rst @@ -0,0 +1,36 @@ +.. highlight:: cpp + +.. _lang-charcast: + +``char()`` (cast) +================= + +Converts a value to the :ref:`char ` data type. + +Syntax +------ + +``char(x)`` + + +Parameters +---------- + +**x**: a value of any type + + +Returns +------- + +The value, converted to a ``char``. Note, however, that if the value +is outside the range of a ``char`` (-128 to 127), then the results +might be strange and unexpected. + + +See Also +-------- + +- :ref:`char ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/comments.rst b/source/lang/cpp/comments.rst new file mode 100644 index 0000000..c5f118a --- /dev/null +++ b/source/lang/cpp/comments.rst @@ -0,0 +1,67 @@ +.. highlight:: cpp + +.. _lang-comments: + +Comments +======== + +Comments are lines in the program that are used to inform yourself or +others about the way the program works. They are ignored by the +compiler, and not exported to the processor, so they don't take up any +space in RAM or Flash. + +One use for comments is to help you understand (or remember) how your +program works, or to inform others how your program works. There are +two different ways of making comments. + +.. _lang-comments-singleline: + +**Single line comment**: Anything following two slashes, ``//``, until +the end of the line, is a comment:: + + x = 5; // the rest of this line is a comment + +.. _lang-comments-multiline: + +**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` +is a comment:: + + /* <-- a slash-star begins a multi-line comment + + all of this in the multi-line comment - you can use it to comment + out whole blocks of code + + if (gwb == 0){ // single line comment is OK inside a multi-line comment + x = 3; + } + + // don't forget the "closing" star-slash - they have to be balanced: + */ + +Note that it's okay to use single-line comments within a multi-line +comment, but you can't use multi-line comments within a multi-line +comment. Here's an example:: + + /* ok, i started a multi-line comment + + x = 3; /* this next star-slash ENDS the multi-line comment: */ + + x = 4; // this line is outside of the multi-line comment + + // next line is also outside of the comment, and causes a compile error: + */ + +Programming Tip +--------------- + +When experimenting with code, "commenting out" parts of your program +is a convenient way to remove lines that may be buggy. This leaves +the lines in the code, but turns them into comments, so the compiler +just ignores them. This can be especially useful when trying to locate +a problem, or when a program refuses to compile and the compiler error +is cryptic or unhelpful. + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/comparison.rst b/source/lang/cpp/comparison.rst new file mode 100644 index 0000000..b24355f --- /dev/null +++ b/source/lang/cpp/comparison.rst @@ -0,0 +1,87 @@ +.. highlight:: cpp + +.. _lang-comparison: + +Comparison Operators (``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``) +=================================================================== + +The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and +``>=`` are used to compare two numbers. They are :ref:`true +` when the comparison is true, and :ref:`false +` otherwise. They are based on the symbols +=, ≠, <, >, ≤, and ≥ from mathematics. + +Here are some examples, with their meaning in comments:: + + // "eq" is true when x is equal to y + bool eq = (x == y); + + // "neq" is true when x is different than y + bool neq = (x != y); + + // "lt" is true when x is less than, but NOT equal to, y + bool lt = (x < y); + + // "gt" is true when x is greater than, but NOT equal to, y + bool gt = (x > y); + + // "lte" is true when x is less than or equal to y + bool lte = (x <= y); + + // "gte" is true when x is greater than or equal to y + bool gte = (x >= y); + +The parentheses are optional; they are present only for clarity. For +example, the following two lines are the same:: + + bool eq = x == y; + + bool eq = (x == y); + +Uses +---- + +Comparison operators, along with :ref:`boolean operators +`, are useful inside the conditionals of :ref:`if +` statements. Here's one example:: + + if (x < 50) { + // only execute these lines if x is less than 50 + SerialUSB.println("delaying:"); + SerialUSB.println(x); + delay(x); + } + +.. warning:: + Beware of accidentally using the single equal sign (``=``) when you + meant to test if two numbers are equal (``==``). This is a common + mistake inside of ``if`` statement conditionals, e.g.:: + + // DON'T MAKE THIS MISTAKE + if (x = 10) { + // body + } + + The single equal sign is the assignment operator, and sets x to 10 + (puts the value 10 into the variable x). Instead use the double equal + sign (e.g. ``if (x == 10)``), which is the comparison operator, and + tests *whether* x is equal to 10 or not. The latter statement is only + true if x equals 10, but the former statement will always be true. + + This is because C evaluates the statement ``if (x=10)`` as follows: 10 + is assigned to x (remember that the single equal sign is the + :ref:`assignment operator `), so x now + contains 10. Then the 'if' conditional evaluates 10, which evaluates + to :ref:`true `, since any non-zero number + evaluates to ``true``. + + Consequently, the conditional of an ``if`` statement like ``if (x = + 10) {...}`` will always evaluate to ``true``, and the variable x + will be set to 10, which is probably not what you meant. + + (This sometimes has uses, though, so just because an assignment + appears within a conditional doesn't mean it's automatically wrong. + Be careful to know what you mean.) + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/compoundarithmetic.rst b/source/lang/cpp/compoundarithmetic.rst new file mode 100644 index 0000000..420f1db --- /dev/null +++ b/source/lang/cpp/compoundarithmetic.rst @@ -0,0 +1,44 @@ +.. highlight:: cpp + +.. _lang-compoundarithmetic: + +Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) +=============================================================== + +These oparators perform a mathematical operation on a variable with +another constant or variable. These operators are just a convenient +shorthand:: + + x += y; // equivalent to the expression x = x + y; + x -= y; // equivalent to the expression x = x - y; + x *= y; // equivalent to the expression x = x * y; + x /= y; // equivalent to the expression x = x / y; + +Here is an example:: + + int x = 2; + int y = 10; + + x += 4; // x now contains 6 + x -= 3; // x now contains 3 + x *= y; // x now contains 30 + x /= 2; // x now contains 15 + x += max(20, 6); // x now contains 35 + x -= sq(5); // x now contains 15 + +Parameters +---------- + +**x**: a numeric variable + +**y**: a numeric variable, number constant, or any other expression +that evaluates to a number (e.g. call to a function that returns a +number). + +See Also +-------- + +- :ref:`Arithmetic operators ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/compoundbitwise.rst b/source/lang/cpp/compoundbitwise.rst new file mode 100644 index 0000000..a4bbb24 --- /dev/null +++ b/source/lang/cpp/compoundbitwise.rst @@ -0,0 +1,231 @@ +.. highlight:: cpp + +.. _lang-compoundbitwise: + +Compound Bitwise Operators (``&=``, ``|=``, ``^=``) +=================================================== + +The compound bitwise operators perform their calculations at the +bit level of variables. They are often used to clear and set +specific bits of a variable. + +See the :ref:`bitwise math tutorial ` for more +information on bitwise operators. + +.. contents:: Contents + :local: + +.. _lang-compoundbitwise-and: + +Compound bitwise AND (``&=``) +----------------------------- + +The compound bitwise AND operator ``&=`` is often used with a variable +and a constant to force particular bits in a variable to be zero. This +is often referred to in programming guides as "clearing" or +"resetting" bits. In a program, writing the line ``x &= y;`` is +equivalent to writing ``x = x & y;``. That is, the value of ``x`` +after the line will be equal to its old value bitwise ANDed with the +value of ``y``:: + + x &= y; // equivalent to x = x & y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any :ref:`integer value +` (like ``3`` or ``0x20``) for ``y``. + +Before doing an example of ``&=``, let's first review the Bitwise AND +(``&``) operator:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) = result + +As shown above, bits that are "bitwise ANDed" with 0 become 0, while +bits that are "bitwise ANDed" with 1 are left unchanged. So, if ``b`` +is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b & +B11111111`` equals ``b``. + +.. _lang-compoundbitwise-binconst: + +.. note:: The above uses :ref:`binary constants + `\ . The numbers are still the same + value in other representations, they just might not be as easy to + understand. + + Normally, in C and C++ code, :ref:`hexadecimal + ` or :ref:`octal + ` are used when we're interested in + an integer's bits, rather than its value as a number. + + While hexadecimal and octal literals might be harder to understand + at first, you should really take the time to learn them. They're + part of C, C++, and many other programming languages, while binary + constants are available only for compatibility with Arduino. + + Also, ``B00000000`` is shown for clarity, but zero in any number + format is zero. + +So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while +leaving the rest of the variable's bits unchanged, use the compound +bitwise AND operator ``&=`` with the constant ``B11111100`` +(hexadecimal ``0xFC``\ ):: + + 1 0 1 0 1 0 1 0 variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + 1 0 1 0 1 0 0 0 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared + + +Here is the same representation with the variable's bits replaced +with the symbol ``x``\ :: + + x x x x x x x x variable + 1 1 1 1 1 1 0 0 mask + ---------------------- + x x x x x x 0 0 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged cleared + + +So, using a byte variable ``b``\ , if we say:: + + b = B10101010; // B10101010 == 0xAA + b &= B11111100; // B11111100 == 0xFC + +then we will have :: + + b == B10101000; // B10101000 == 0xA8 + +.. _lang-compoundbitwise-or: + +Compound bitwise OR (``|=``) +---------------------------- + +The compound bitwise OR operator ``|=`` is often used with a variable +and a constant to "set" (set to 1) particular bits in a variable. In +a program, writing the line ``x |= y;`` is equivalent to writing ``x = +x | y;``. That is, the value of ``x`` after the line will be equal to +its old value bitwise ORed with the value of ``y``:: + + x |= y; // equivalent to x = x | y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`compound bitwise AND +`\ , ``&=``). + +Before doing an example of ``|=``, let's first review the Bitwise OR +(``|``) operator:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) = result + +Bits that are "bitwise ORed" with 0 are unchanged, while bits that are +"bitwise ORed" with 1 are set to 1. So if ``b`` is a ``byte`` +variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111`` +equals ``B11111111`` (here we've used binary constants; see the +:ref:`note ` above). + +So, to set bits 0 and 1 of a one-byte variable, while leaving the rest +of the variable unchanged, use the compound bitwise OR operator +(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``):: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set + +Here is the same representation with the variable's bits replaced with +the symbol ``x``:: + + x x x x x x x x variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + x x x x x x 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged set + +So, using a byte variable ``b``, if we say:: + + b = B10101010; // B10101010 == 0xAA + b |= B00000011; // B00000011 == 0x3 + +then we will have :: + + b == B10101011; // B10101011 == 0xAB + +.. _lang-compoundbitwise-xor: + +Compound bitwise XOR (``^=``) +----------------------------- + +The compound bitwise XOR operator ``^=`` is used with a variable and a +constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a +variable. In a program, writing the line ``x ^= y;`` is equivalent to +writing ``x = x ^ y;``. That is, the value of ``x`` after the line +will be equal to its old value bitwise XORed with the value of ``y``:: + + x ^= y; // equivalent to x = x ^ y; + +You can use any integer variable for ``x`` (i.e., any variable of type +``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +integer variable or any integer value (like ``3`` or ``0x20``) for +``y``. (This works the same way as :ref:`&= +` and :ref:`\|= +`; in fact, these three operators all +work the same in this way). + +Before doing an example of ``^=``, let's first review the Bitwise +XOR operator, ``^``:: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) = result + +One way to look at bitwise XOR is that each bit in the result is a 1 +if the input bits are different, or 0 if they are the same. Another +way to think about it is that the result bit will be 1 when *exactly* +one (no more, no less) of the input bits is 1; otherwise, it will be +zero. This means that if you XOR a bit with 1, it will change (or +toggle) its value, while if you XOR a bit with 0, it stays the same. + +So, to toggle bits 0 and 1 of a one-byte variable, while leaving the +rest of the variable unchanged, use the compound bitwise XOR operator +``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see +:ref:`note ` above):: + + 1 0 1 0 1 0 1 0 variable + 0 0 0 0 0 0 1 1 mask + ---------------------- + 1 0 1 0 1 0 1 1 + ^^^^^^^^^^^^^^^^ ^^^^ + unchanged toggled + +So, using a byte variable ``b``, if we say:: + + b = B10101010; // B10101010 == 0xAA + b ^= B00000011; // B00000011 == 0x3 + +then we will have :: + + b == B10101001; // B10101001 == 0xA9 + +See Also +-------- + +- :ref:`Boolean operations ` (``&&``, ``||``) +- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/const.rst b/source/lang/cpp/const.rst new file mode 100644 index 0000000..52de85f --- /dev/null +++ b/source/lang/cpp/const.rst @@ -0,0 +1,52 @@ +.. highlight:: cpp + +.. _lang-const: + +``const`` +========= + +The ``const`` keyword stands for "constant". It is a variable +*qualifier* that modifies the behavior of the variable, making a +variable "*read-only*". This means that the variable can be used just +as any other variable of its type, but its value cannot be +changed. You will get a compiler error if you try to assign a value to +a ``const`` variable. + +Constants defined with the ``const`` keyword obey the same rules of +:ref:`variable scoping ` that govern other +variables. This, and the pitfalls of using :ref:`#define +`, often makes using the ``const`` keyword a superior +method for defining constants than ``#define``. + +Example +------- + +:: + + // this defines a variable called "pi", which cannot be changed: + const float pi = 3.14; + float x; + + // .... + + x = pi * 2; // it's fine to find the value of a const variable + + pi = 7; // illegal - you can't write to (modify) a constant + + +**#define** or **const** +------------------------ + +You can use either ``const`` or ``#define`` for creating numeric or +string constants. For :ref:`arrays `\ , you will need +to use ``const``. In general, ``const`` is preferred over ``#define`` +for defining constants. + +See Also +-------- + +- :ref:`#define ` +- :ref:`volatile ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/continue.rst b/source/lang/cpp/continue.rst new file mode 100644 index 0000000..13d1815 --- /dev/null +++ b/source/lang/cpp/continue.rst @@ -0,0 +1,32 @@ +.. highlight:: cpp + +.. _lang-continue: + +``continue`` +============ + +The ``continue`` keyword skips the rest of the current iteration of a +:ref:`while `\ , :ref:`for `\ , or +:ref:`do/while ` loop. It continues by checking the +conditional expression of the loop, and proceeding with any subsequent +iterations. + +Example +------- + +:: + + + for (x = 0; x < 255; x ++) { + if (x > 40 && x < 120) { // create jump in values + continue; // skips the next two lines and goes to the + // beginning of the loop, with the next value of x + } + + digitalWrite(PWMpin, x); + delay(50); + } + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/curly-braces.rst b/source/lang/cpp/curly-braces.rst new file mode 100644 index 0000000..a4bd3dc --- /dev/null +++ b/source/lang/cpp/curly-braces.rst @@ -0,0 +1,109 @@ +.. highlight:: cpp + +.. _lang-curly-braces: + +Curly Braces (``{``, ``}``) +=========================== + +.. contents:: Contents + :local: + +Introduction +------------ + +Curly braces (also referred to as just "braces" or as "curly +brackets") are a major part of the C and C++ programming +languages. They are used in several different constructs, outlined +below, and this can sometimes be confusing for beginners. + +An opening curly brace, ``{`` must always be followed by a closing +curly brace ``}``. This is a condition that is often referred to as +the braces being *balanced*. The Maple IDE (integrated development +environment) includes a convenient feature to check the balance of +curly braces. Just select a brace, or even click the insertion point +immediately following a brace, and its companion will be highlighted\ +[#fbug]_\ . + +Beginning programmers, and programmers coming to C++ from languages +without braces, often find using them confusing or daunting. + +Because the use of the curly brace is so varied, it is good +programming practice to type the closing brace immediately after +typing the opening brace when inserting a construct which requires +curly braces. Then insert some blank lines between your braces and +begin inserting statements. Your braces, and your attitude, will never +become unbalanced. + +Unbalanced braces can often lead to cryptic, impenetrable compiler +errors that can sometimes be hard to track down in a large program. +Because of their varied usages, braces are also incredibly important +to the syntax of a program and moving a brace one or two lines will +usually dramatically affect the meaning of a program. + +The main uses of curly braces +----------------------------- + +**Functions**:: + + // a function body needs braces around it + void myFunction(datatype argument) { + // ... function body goes in here ... + } + +**Loops** (see the :ref:`while `\ , :ref:`for +`\ , and :ref:`do/while ` loop reference +pages for more information):: + + // you should put braces around the body of a loop: + + while (boolean expression) { + // code inside the loop goes here + } + + for (initialisation; termination condition; incrementing expr) { + // code inside the loop goes here + } + + do { + // code inside the loop goes here + } while (boolean expression); + + +**Conditional statements** (see the :ref:`if statement ` +reference page for more information):: + + // you should put braces around the body of an "if", "else if", + // or "else": + + if (boolean expression) { + // code inside the "if" + } + else if (boolean expression) { + // code inside the "else if" + } + else { + // code inside the "else" + } + +**Switch statements** (see the :ref:`switch statement +` reference page for more information):: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + +.. rubric:: Footnotes + +.. TODO remove this once IDE 0.1.0 released + +.. [#fbug] At present this feature is slightly buggy as the IDE will + often find (incorrectly) a brace in text that has been commented + out. + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/define.rst b/source/lang/cpp/define.rst new file mode 100644 index 0000000..677390d --- /dev/null +++ b/source/lang/cpp/define.rst @@ -0,0 +1,56 @@ +.. highlight:: cpp + +.. _lang-define: + +``#define`` +=========== + +``#define`` is a useful C and C++ feature that allows the programmer +to give a name to a constant value before the program is compiled. +The compiler will replace references to these constants with the +defined value at compile time. + +This can have some unwanted side effects. In general, the :ref:`const +` keyword is preferred for defining constants. + + +Syntax +------ + +The following line would define the name ``MY_CONSTANT`` to have value +``value``:: + + #define MY_CONSTANT value + +Note that the ``#`` is necessary. It is usually good style for the +name to be capitalized, although this is not required. + +There is no semicolon after the #define statement. If you include one, +the compiler will likely throw cryptic errors in unrelated places. +That is, **don't do this**:: + + // DON'T DO THIS! THE SEMICOLON SHOULDN'T BE THERE! + #define NAME value; + +Similarly, including an equal sign after the ``#define`` line will +also generate a cryptic compiler error further down the page. That +is, **don't do this, either**:: + + // DON'T DO THIS, EITHER! THE EQUALS SIGN SHOULDN'T BE THERE! + #define NAME = value + +Example +------- + +:: + + #define LED_PIN 13 + // The compiler will replace any mention of LED_PIN with + // the value 3 at compile time. + +See Also +-------- +- :ref:`const ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/double.rst b/source/lang/cpp/double.rst new file mode 100644 index 0000000..1527778 --- /dev/null +++ b/source/lang/cpp/double.rst @@ -0,0 +1,48 @@ +.. _lang-double: + +``double`` +========== + +Double precision floating point type. Occupies 8 bytes. On Maple, the +``double`` type has a range of approximately -1.79769×10^308 to +1.79769×10^308; the ``double`` type subject to the same :ref:`overflow +issues ` as any numeric data type. + +Floating point numbers are not exact, and may yield strange results +when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You +should instead check that the absolute value of the difference between +the numbers is less than some small number. + +Floating point math is also much slower than integer math in +performing calculations, so should be avoided if, for example, a loop +has to run at top speed for a critical timing function. Programmers +often go to some lengths to convert floating point calculations to +integer math to increase speed. + +For more information, see the `Wikipedia article on floating point +math `_\ . + +Floating-point numbers represent numbers with "decimal point", unlike +integral types, which always represent whole numbers. Floating-point +numbers are often used to approximate analog and continuous values +because they have greater resolution than integers. + +The double implementation on the Maple uses twice the number of bytes +as a :ref:`float `, with the corresponding gains in +precision. + +Tip +--- + +Users who borrow code from other sources that includes ``double`` +variables may wish to examine the code to see if the implied range and +precision are different from that actually achieved on the Maple. + +See Also +-------- + +- :ref:`float ` + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/doublecast.rst b/source/lang/cpp/doublecast.rst new file mode 100644 index 0000000..511fe24 --- /dev/null +++ b/source/lang/cpp/doublecast.rst @@ -0,0 +1,27 @@ +.. highlight:: cpp + +.. _lang-doublecast: + +``double()`` (cast) +=================== + +Converts a value to the :ref:`double ` floating point +data type. Here is an example:: + + int x = 2; + double d = double(x); // d now holds 2.0, a double value + +The value ``x`` can be of any type. However, if ``x`` is not a number +(like an ``int`` or ``long``), you will get strange results. + +See the :ref:`double ` reference for details about the +precision and limitations of ``double`` values on the Maple. + +See Also +-------- + +- :ref:`double ` +- :ref:`float ` +- :ref:`float() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/dowhile.rst b/source/lang/cpp/dowhile.rst new file mode 100644 index 0000000..fe92226 --- /dev/null +++ b/source/lang/cpp/dowhile.rst @@ -0,0 +1,27 @@ +.. highlight:: cpp + +.. _lang-dowhile: + +``do``/``while`` +================ + +A ``do`` loop works in the same manner as a :ref:`while +` loop, with the exception that the condition is tested +at the end of the loop, so the ``do`` loop will *always* run at least +once. + +This is the basic syntax:: + + do { + // statement block + } while (test condition); + +Example:: + + do { + delay(50); // wait for sensors to stabilize + x = readSensors(); // check the sensors + } while (x < 100); + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/enum.rst b/source/lang/cpp/enum.rst new file mode 100644 index 0000000..ba82383 --- /dev/null +++ b/source/lang/cpp/enum.rst @@ -0,0 +1,53 @@ +.. highlight:: cpp + +.. _lang-enum: + +``enum`` +======== + +The ``enum`` keyword is used to specify an enumeration type. An +enumeration type is a type whose values are taken from a specified, +fixed list of constant values. + +Example +------- + +Here's an example defining an enumeration type called ``weather``, +which has values ``HOT``, ``COMFY``, and ``COLD``:: + + enum weather {HOT, COMFY, COLD}; + +Once you've defined this type, you can create variables of type +``weather``, in the same way you would with an :ref:`int ` +or a :ref:`long `:: + + // create a weather variable named theWeather, with value COMFY: + weather theWeather = COMFY; + +Enumeration types are useful within :ref:`switch statements +`. If you know that an argument is of an enumeration +type, you can make ``case`` statements for all of that type's possible +values, so you know you won't miss anything:: + + void describeWeather(weather currentWeather) { + switch(currentWeather) { + case HOT: + SerialUSB.println("it's hot out"); + break; + case COMFY: + SerialUSB.println("it's nice today"); + break; + case COLD: + SerialUSB.println("it's freezing!"); + break; + } + } + +Such a ``switch`` statement would need no :ref:`default +`, since we know that ``currentWeather`` must +be either ``HOT``, ``COMFY``, or ``COLD``. + +See Also +-------- + +- :ref:`lang-switchcase` diff --git a/source/lang/cpp/float.rst b/source/lang/cpp/float.rst new file mode 100644 index 0000000..6937c8c --- /dev/null +++ b/source/lang/cpp/float.rst @@ -0,0 +1,50 @@ +.. highlight:: cpp + +.. _lang-float: + +``float`` +========= + +Single-precision floating point number. Occupies 4 bytes. On Maple, +the ``float`` type has a range of approximately -3.40282×10^38 to +3.40282×10^38; the ``float`` type is subject to the same +:ref:`overflow issues ` as any numeric data +type. + +``float``\ s have only 6-7 decimal digits of precision. That means the +total number of digits, not the number to the right of the decimal +point. You can get more precision by using a :ref:`double +` (which has a precision of about 16 decimal digits). + +The following example declares a ``float`` value named ``myfloat``:: + + float myfloat; + +This example declares a ``float`` value named ``sensorCalibrate``, +with value 1.117:: + + float sensorCalibrate = 1.117; + +The general syntax for declaring a float named ``var`` with value +``val`` is:: + + float var = val; + +Here is a more extended example involving a :ref:`float cast +`:: + + int x; + int y; + float z; + + x = 1; + y = x / 2; // y now contains 0, ints can't hold fractions + z = float(x) / 2; // z now contains .5 + +See Also +-------- + +- :ref:`double ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/floatcast.rst b/source/lang/cpp/floatcast.rst new file mode 100644 index 0000000..4766478 --- /dev/null +++ b/source/lang/cpp/floatcast.rst @@ -0,0 +1,28 @@ +.. highlight:: cpp + +.. _lang-floatcast: + +``float()`` (cast) +================== + +Converts a value to the :ref:`float ` data type. Here is +an example (see the :ref:`constants reference ` for +an explanation of the "2.0f"):: + + int x = 2; + float f = float(x); // f now holds 2.0f, a float value + +The value ``x`` can be of any type. However, if ``x`` is not a number +(like an ``int``), you will get strange results. + +See the :ref:`float ` reference for details about the +precision and limitations of ``float`` values on the Maple. + +See Also +-------- + +- :ref:`float ` +- :ref:`double ` +- :ref:`double() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/for.rst b/source/lang/cpp/for.rst new file mode 100644 index 0000000..71c5aca --- /dev/null +++ b/source/lang/cpp/for.rst @@ -0,0 +1,142 @@ +.. highlight:: cpp + +.. _lang-for: + +``for`` +======= + +A ``for`` loop is used to repeat a block of statements enclosed in +curly braces. ``for`` loops are useful for performing repetitive +operations, and are often used in combination with :ref:`arrays +` to operate on collections of data or multiple +:ref:`pins `. A ``for`` loop is composed of two parts: first, a +*header*, which sets up the for loop, and then a *body*, which is made +up of lines of code enclosed in curly braces. + +.. contents:: Contents + :local: + +Syntax +------ + +There are three parts to the ``for`` loop header: an *initialization* +expression, *loop condition* expression, and a *post-loop* +expression. The general syntax looks like this:: + + for (initialization; condition; post-loop) { + // all of these lines inside the curly braces are part + // of the loop body. + statement 1; + statement 2; + ... + } + +(Note that there is no semicolon after the post-loop). The +initialization happens first and exactly once, before the loop begins. +Each time through the loop, the condition is tested. The condition is +a :ref:`boolean ` expression. If it is true, then the +list of statements inside the curly braces are executed. Next, the +post-loop is executed. The loop then begins again by evaluating the +condition again, entering the loop body if it is true. This proceeds +until the condition becomes false. + +Examples +-------- + +Here's an example:: + + // Dim an LED using a PWM pin + int pwmPin = 9; // LED in series with 470 ohm resistor on pin 9 + + void setup() { + pinMode(pwmPin, PWM); + } + + void loop() { + for (int i=0; i <= 65535; i++) { + pwmWrite(pwmPin, i); + delay(1); + } + } + +There is a ``for`` loop In the :ref:`loop() ` function of +the above example. This loop starts by declaring an ``int`` variable +named ``i``, whose value starts out at zero. The loop proceeds by +checking if ``i`` is less than or equal to 65535. Since ``i`` is +zero, this is true, and so the calls to :ref:`pwmWrite() +` and :ref:`delay() ` happen next. At this +point, the post-loop expression ``i++`` is evaluated, which +:ref:`increments ` ``i``, so that ``i`` becomes one. +That concludes the first time through the loop. Each "time through +the loop" is referred to as an *iteration*. + +The loop then jumps back to the beginning, checking the condition as +the beginning of its second iteration (initialization is skipped, +since this only happens once, before the first iteration). One is +less than 65535, so the loop statements are executed again. This +proceeds over and over until the iteration when ``i`` finally +reaches 65536. At that point, the condition is no longer true, so the +loop stops executing, and the ``loop()`` function returns. + +Here's another example, using a ``for`` loop to brighten and fade an +LED (see the :ref:`pwmWrite() ` reference for more +information):: + + int pwmPin = 9; // hook up the LED to pin 9 + void loop() { + int x = 1; + for (int i = 0; i >= 0; i += x) { + analogWrite(pwmPin, i); // controls the brightness of the LED + if (i == 65535) { + x = -1; // switch direction, so i starts decreasing + } + delay(1); + } + } + +Coding Tips +----------- + +The C ``for`` loop is more flexible than ``for`` loops found in some +other computer languages, including BASIC. Any or all of the three +header elements may be left blank, although the semicolons are +required. Also the statements for initialization, condition, and +post-loop can be any valid C statements, and use any C datatypes, +including :ref:`floating point numbers `. These types +of unusual ``for`` loops sometimes provide solutions to less-common +programming problems. + +For example, using a multiplication in the post-loop line will +generate a `geometric progression +`_:: + + for(int x = 1; x <= 100; x = x * 2) { + SerialUSB.println(x); + } + + +This loop prints out the numbers 1, 2, 4, 8, ..., 64. Check +your understanding of ``for`` loops by answering the following two +questions (answers are in footnote [#fanswers]_\ ): + +1. How many iterations occur before the loop finishes? + +2. Why does it stop at 64? + +See also +-------- + +- :ref:`while ` loops +- :ref:`do ` loops + +.. rubric:: Footnotes + +.. [#fanswers] + 1. Seven. + + 2. After the seventh iteration, the post-loop causes ``x`` to + equal 128. This is larger than 100, so the loop condition is + false, and the loop stops. + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/goto.rst b/source/lang/cpp/goto.rst new file mode 100644 index 0000000..ff2f248 --- /dev/null +++ b/source/lang/cpp/goto.rst @@ -0,0 +1,130 @@ +.. highlight:: cpp + +.. _lang-goto: + +Labels and ``goto`` +=================== + +A *label* gives a name to a line of code within a function. You can +label a line by writing a name for it, then a colon (``:``), before +the line starts. The ``goto`` keyword allows program flow to transfer +to a labeled line from anywhere within the same function. + +.. warning:: The use of ``goto`` is discouraged in C and C++ + programming. It is *never necessary* to use ``goto`` to write a + program. + + Unless you know what you're doing, using ``goto`` tends to + encourage code which is harder to debug and understand than + programs without ``goto`` that do the same thing. That said, + however, it's sometimes useful; :ref:`see below ` + for a concrete example. + +Using Labels and goto +--------------------- + +Labels and ``goto`` are probably best explained through example. +Let's start with an example of how to label lines. The first line +(``int x = analogRead(some_pin);``) in the :ref:`loop ` +function below has label ``readpin``. The third line (``delay(x);``) +has label ``startdelay``. The second line (``SerialUSB.println(x);``) +does not have a label:: + + void loop() { + readpin: + int x = analogRead(some_pin); + SerialUSB.println(x); // for debugging + startdelay: + delay(x); + // ... more code ... + } + +Anything which can be a :ref:`variable ` name can +be a label. + +Let's say that we wanted to print ``x`` only if it was very large, say +at least 2000. We might want to do this just so anybody watching on a +:ref:`serial monitor ` would know they were in for +a longer wait than usual. We can accomplish this through the use of a +``goto`` statement that skips the printing if ``x`` is less than +2000:: + + void loop() { + readpin: + int x = analogRead(some_pin); + if (x < 2000) { + goto startdelay; + } + SerialUSB.println(x); // for debugging + startdelay: + delay(x); + // ... more code ... + } + +In this modified program, whenever ``x`` is less than 2000, the body +of the :ref:`if ` statement in the second line is +executed. The ``goto`` statement inside the ``if`` body skips +straight to the line labeled ``startdelay``, passing over the line +doing the printing. + +A ``goto`` does not have to "move forwards"; it can go "backwards", +too. For example, the following program prints "5" forever (why?):: + + void loop() { + printfive: + SerialUSB.println(5); + goto printfive; + SerialUSB.println(6); + } + +.. _goto-when-to-use: + +When to Use goto +---------------- + +As mentioned above, use of ``goto`` is `generally discouraged +`_. However, +when used with care, ``goto`` can simplify certain programs. One +important use case for ``goto`` is breaking out of deeply nested +:ref:`for ` loops or :ref:`if ` logic blocks. +Here's an example:: + + for(int r = 0; r < 255; r++) { + for(int g = 255; g > -1; g--) { + for(int b = 0; b < 255; b++) { + if (analogRead(0) > 250) { + goto bailout; + } + // more statements ... + } + // innermost loop ends here + } + } + bailout: + // more code here + +In the above example, whenever the :ref:`analog reading +` on pin 0 was greater than 250, the program would +jump to the line labeled ``bailout``, exiting all three loops at once. + +While there is already a :ref:`break ` keyword for +breaking out of a loop, it will only break out of the *innermost* +loop. So, if instead of saying "``goto bailout;``", there was a +"``break;``" instead, the program would only exit from the loop with +header "``for(int b = 0; b < 255; b++)``". The program would continue +at the line which reads "``// innermost loop ends here``", which is +clearly undesirable if you wanted to leave all three loops at once. + +More examples of when ``goto`` is a good choice are given in Donald +Knuth's paper, "Structured Programming with go to Statements"; see +below for a link. + +See Also +-------- + +- Dijkstra, Edsger W. `Go To Statement Considered Harmful `_ (PDF) + +- Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/if.rst b/source/lang/cpp/if.rst new file mode 100644 index 0000000..bef89e2 --- /dev/null +++ b/source/lang/cpp/if.rst @@ -0,0 +1,121 @@ +.. highlight:: cpp + +.. _lang-if: + +``if``/``else`` +=============== + +An ``if`` statement is used to execute code when certain conditions +are met. The general syntax for an ``if`` statement is:: + + if (condition) { + body + } + +An ``if`` statement first tests whether its *condition* is true (such +as an input being above a certain number). If the condition is true, +the ``if`` statement executes its *body*, which is made up of lines of +code inside :ref:`curly braces `. If the condition +is false, the body is not executed. Here's a more concrete example:: + + if (someVariable > 50) { + // do something here + } + +The program tests to see if ``someVariable`` is greater than 50. If it +is, the program executes every line in the curly braces (which in the +above example does nothing, since the body is just the :ref:`comment +` line "``// do something here``"). + +Put another way, if the statement in parentheses is true, the +statements inside the braces are run. If not, the program skips over +the code. + +An ``if`` statement's condition (which is inside the parentheses after +``if``) often uses one or more :ref:`boolean ` or +:ref:`comparison ` operators. + +Writing the if Body +------------------- + +The brackets may be omitted after an ``if`` statement's +conditional. If this is done, the next line (which ends in a +semicolon) becomes the only line in the body. The following three +``if`` statements all do the same thing:: + + if (x > 120) digitalWrite(ledPin, HIGH); + + if (x > 120) + digitalWrite(ledPin, HIGH); + + if (x > 120) { + digitalWrite(ledPin, HIGH); + } + +However, the following two examples are different:: + + // example 1: two lines of code in the if body + if (x > 120) { + digitalWrite(ledPin1, HIGH); + digitalWrite(ledPin2, HIGH); + } + + // example 2: one line of code in the if body, and + // another line of code after the if statement + if (x > 120) + digitalWrite(ledPin1, HIGH); // this is in the if body + digitalWrite(ledPin2, HIGH); // this is NOT in the if body + +In the first example, since the body is enclosed in curly braces, both +lines are included. In the second example, since the curly braces are +missing, only the first line is in the ``if`` body. + +``else`` +-------- + +``if``/\ ``else`` allows greater control over the flow of code than +the basic :ref:`if ` statement, by allowing multiple tests to +be grouped together. For example, an :ref:`analog input +` could be tested, with one action taken if the input +was less than 500, and another action taken if the input was 500 or +greater. The code would look like this:: + + if (pinFiveInput < 500) { + // action A + } else { + // action B + } + +``else`` can precede another ``if`` test, so that multiple, mutually +exclusive tests can be run at the same time. + +Each test will proceed to the next one until a true test is +encountered. When a true test is found, its associated block of code +is run, and the program then skips to the line following the entire +if/else construction. If no test proves to be true, the default +``else`` block is executed, if one is present, and sets the default +behavior. + +Note that an ``else if`` block may be used with or without a +terminating ``else`` block, and vice-versa. An unlimited number of +such ``else if`` branches is allowed. Here is a code example:: + + if (pinFiveInput < 500) { + // do Thing A + } else if (pinFiveInput >= 1000) { + // do Thing B + } else { + // do Thing C + } + +Another way to express branching, mutually exclusive tests, is with a +:ref:`switch/case ` statement. + + +See Also +-------- + +- :ref:`boolean operators ` +- :ref:`comparison operators ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/include.rst b/source/lang/cpp/include.rst new file mode 100644 index 0000000..74fe7af --- /dev/null +++ b/source/lang/cpp/include.rst @@ -0,0 +1,72 @@ +.. highlight:: cpp + +.. _lang-include: + +``#include`` +============ + +``#include`` is used to include outside libraries in your sketch. +This gives the programmer access to a large group of standard C +libraries (groups of pre-made functions and data types), and also +libraries written especially for Maple. + +Example +------- + +This example (from the `Arduino LiquidCrystal Tutorial +`_) includes a library +that is used to control :ref:`LCD displays +`:: + + // include the library code: + #include + + // initialize the library with the numbers of the interface pins + LiquidCrystal lcd(12, 11, 5, 4, 3, 2); + + void setup() { + // set up the LCD's number of columns and rows: + lcd.begin(16, 2); + // Print a message to the LCD. + lcd.print("hello, world!"); + } + + void loop() { + // set the cursor to column 0, line 1 + // (note: line 1 is the second row, since counting begins with 0): + lcd.setCursor(0, 1); + // print the number of seconds since reset: + lcd.print(millis()/1000); + } + +Note that a ``#include`` line, like :ref:`#define `, +has **no semicolon**. The compiler will print strange error messages +if you add one. + +C Standard Library +------------------ + +The standard C library that comes with Maple is called `newlib +`_. Its main sources of documentation +are its `main reference `_ +page and its `math functions +`_ reference page. Here's an +example that imports the math.h library in order to take the `cube +root `_ of a number:: + + #include + + void setup() { + // no setup necessary + } + + void loop() { + // "cbrt" stands for "cube root" + double cubeRootOf3 = cbrt(3.0); + // prints a number that is approximately the cube root of 3: + SerialUSB.println(cubeRootOf3); + } + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/increment.rst b/source/lang/cpp/increment.rst new file mode 100644 index 0000000..6dffa80 --- /dev/null +++ b/source/lang/cpp/increment.rst @@ -0,0 +1,37 @@ +.. highlight:: cpp + +.. _lang-increment: + +Increment and Decrement Operators (``++``, ``--``) +================================================== + +These operators increment (add one to) or decrement (subtract one +from) a variable. If they come before the variable, they return its +new value; otherwise, they return its old value. + +Some quick examples:: + + x++; // adds one to x, and returns the old value of x + ++x; // adds one to x, and returns the new value of x + + x--; // decrement x by one and returns the old value of x + --x; // decrement x by one and returns the new value of x + +A more extended example:: + + x = 2; + y = ++x; // x now contains 3, y contains 3 + y = x--; // x contains 2 again, y still contains 3 + +.. warning:: Be careful! You cannot put a space in between the two + ``+`` or ``-`` signs. This example is broken:: + + // this line won't compile (notice the extra space): + int y = x+ +; + +See Also +-------- + +- :ref:`lang-compoundarithmetic` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/int.rst b/source/lang/cpp/int.rst new file mode 100644 index 0000000..ca75f75 --- /dev/null +++ b/source/lang/cpp/int.rst @@ -0,0 +1,64 @@ +.. highlight:: cpp + +.. _lang-int: + +``int`` +======= + +The ``int`` data type represents integers. Integers are your primary +data type for number storage, and store a 4 byte value. This yields a +range of -2,147,483,648 to 2,147,483,647 (minimum value of -2^31 and a +maximum value of (2^31) - 1; that's about negative 2 billion to +positive 2 billion). + +An ``int`` stores a negative number with a technique called `two's +complement math +`_\ . +The highest bit in an ``int``, sometimes refered to as the "sign" bit, +flags the number as a negative number. (See the linked article on +two's complement for more information). + +The Maple takes care of dealing with negative numbers for you, so that +arithmetic operations work mostly as you'd expect. There can be an +:ref:`unexpected complication ` in +dealing with the :ref:`bitshift right operator (>>) +`, however. + +Here is an example of declaring an ``int`` variable named ``ledPin``, +then giving it value 13:: + + int ledPin = 13; + +The general syntax for declaring an ``int`` variable named ``var``, +then giving it value ``val``, looks like:: + + int var = val; + +.. _lang-int-overflow: + +Integer Overflow +---------------- + +When ``int`` variables leave the range specified above, they +:ref:`roll over ` in the other direction. +Here are some examples:: + + int x; + x = -2,147,483,648; + x--; // x now contains 2,147,483,647; rolled over "left to right" + + x = 2,147,483,647; + x++; // x now contains -2,147,483,648; rolled over "right to left" + +See Also +-------- + +- :ref:`unsigned int ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`long ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/intcast.rst b/source/lang/cpp/intcast.rst new file mode 100644 index 0000000..386fe14 --- /dev/null +++ b/source/lang/cpp/intcast.rst @@ -0,0 +1,29 @@ +.. highlight:: cpp + +.. _lang-intcast: + +``int()`` (cast) +================ + +Converts a value to the :ref:`int ` data type. Here is +an example:: + + double d = 2.5; + int i = int(d); // i holds "2", an int value + +The value inside of the parentheses (``int(...)``) can be of any type. +However, if it is not a numeric type (like ``double``, ``char``, +etc.), you will get strange results. + +See the :ref:`int ` reference for details about the +precision and limitations of ``int`` variables on the Maple. + +See Also +-------- + +- :ref:`int ` + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/keywords.rst b/source/lang/cpp/keywords.rst new file mode 100644 index 0000000..e4ebe99 --- /dev/null +++ b/source/lang/cpp/keywords.rst @@ -0,0 +1,205 @@ +.. _lang-keywords: + +Keywords +======== + +This page lists all of the C++ keywords, and either links to a +reference page explaining their use, or provides a brief description. + +List of Keywords +---------------- + +The C++ keywords are: + +``and``, ``and_eq``, ``asm``, ``auto``, ``bitand``, ``bitor``, +``bool``, ``break``, ``case``, ``catch``, ``char``, ``class``, +``compl``, ``const``, ``const_cast``, ``continue``, ``default``, +``delete``, ``do``, ``double``, ``dynamic_cast``, ``else``, ``enum``, +``explicit``, ``export``, ``extern``, ``false``, ``float``, ``for``, +``friend``, ``goto``, ``if``, ``inline``, ``int``, ``long``, +``mutable``, ``namespace``, ``new``, ``not``, ``not_eq``, +``operator``, ``or``, ``or_eq``, ``private``, ``protected``, +``public``, ``register``, ``reinterpret_cast``, ``return``, ``short``, +``signed``, ``sizeof``, ``static``, ``static_cast``, ``struct``, +``switch``, ``template``, ``this``, ``throw``, ``true``, ``try``, +``typedef``, ``typeid``, ``typename``, ``union``, ``unsigned``, +``using``, ``virtual``, ``void``, ``volatile``, ``wchar_t``, +``while``, ``xor``, ``xor_eq`` + +Boolean Operator Synonyms +------------------------- + +- ``and`` is a synonym for :ref:`&& `. +- ``not`` is a synonym for :ref:`\! `. +- ``not_eq`` is a synonym for :ref:`\!= `. +- ``or`` is a synonym for :ref:`|| `. + +Bitwise Operator Synonyms +------------------------- + +- ``and_eq`` is a synonym for :ref:`&= `. +- ``bitand`` is a synonym for (bitwise) :ref:`& `. +- ``bitor`` is a synonym for :ref:`\| `. +- ``compl`` is a synonym for :ref:`~ `. +- ``or_eq`` is a synonym for :ref:`|= `. +- ``xor`` is a synonym for :ref:`^ `. +- ``xor_eq`` is a synonym for :ref:`^= `. + +Constants +--------- + +- ``true`` and ``false`` are the :ref:`boolean constants + `. + +Control Flow +------------ + +- ``break`` can exit out of a :ref:`switch statement + ` or a :ref:`for `, :ref:`do + `, or :ref:`while ` loop. + +- ``case`` defines alternatives in a :ref:`switch statement `. + +- ``continue`` will move control flow to the next iteration of the + enclosing :ref:`for `, :ref:`do `, or + :ref:`while ` loop. + +- ``default`` defines the default alternative in a :ref:`switch + statement `. + +- ``do`` introduces a :ref:`do ` loop. + +- ``else`` is used in :ref:`if statements `. + +- ``for`` introduces a :ref:`for ` loop. + +- ``goto`` :ref:`jumps ` to a label. + +- ``if`` introduces an :ref:`if statement `. + +- ``return`` :ref:`transfers flow to a function's caller `. + +- ``switch`` introduces a :ref:`switch statement `. + +- ``while`` introduces a :ref:`while ` loop. + +Types +----- + +The following keywords are used for built-in types. + +- :ref:`bool ` +- :ref:`lang-char` +- :ref:`lang-double` +- :ref:`lang-float` +- :ref:`lang-int` +- :ref:`lang-long` +- :ref:`short ` +- :ref:`void ` (not really a type, but used in the absence + of one) + +The following keywords are used to introduce new types. + +- :ref:`enum ` + +Qualifiers +---------- + +- :ref:`static ` can be used to declare persistent local + variables; it has other uses not documented here. + +- ``unsigned`` is used to specify an unsigned integral type. + Examples: :ref:`lang-unsignedint`, :ref:`lang-unsignedchar`, + :ref:`lang-unsignedlong`. + +- :ref:`volatile ` is useful when declaring variables + that may be modified by external interrupts. + +- :ref:`const ` is used to define constants. + +Other +----- + +These keywords are not described in the Maple documentation. For more +information, consult a C++ reference. + +- ``asm`` is used to insert literal assembly language. + +- ``auto`` is used to declare that a variable has automatic storage. + +- ``catch`` is used in exception handling. Note that the default + flags we pass to :ref:`GCC ` include ``-fno-exceptions``. + +- ``class`` is used to define classes. + +- ``const_cast`` is used in typecasting. + +- ``delete`` is used to free ``new``\ -allocated storage. Note that + dynamic memory allocation is not available by default on the Maple, + so you'll have to bring your own ``new`` and ``delete`` if you want + this. + +- ``dynamic_cast`` is used in typecasting. + +- ``explicit`` is used to declare constructors that can be called only + explicitly. + +- ``export`` declares a template definition accessible to other + compilation units. + +- ``extern`` can mark a declaration as a declaration and not a + definition, and also grant external linkage to a ``const`` or + ``typedef``. + +- ``friend`` is used to declare that certain functions have access to + a class's private variables. + +- ``inline`` is a compiler hint to inline a function. + +- ``mutable`` specifies that a member can be updated, even when a + member of a ``const`` object. + +- ``namespace`` declares a new namespace. + +- ``new`` dynamically allocates space for a value. Note that dynamic + memory allocation is not available by default on the Maple, so + you'll have to bring your own ``new`` and ``delete`` if you want + this. + +- ``operator`` is used to define type-specific operator overrides. + +- ``private`` declares a private class member. + +- ``protected`` declares a protected class member. + +- ``public`` declares a public class member. + +- ``register`` is a compiler hint to store a variable in a register. + +- ``reinterpret_cast`` is used in typecasting. + +- ``signed`` is the opposite of ``unsigned``. + +- ``static_cast`` is used in typecasting. + +- ``struct`` declares a new struct. + +- ``template`` introduces a template class, function, etc. + +- ``this`` is a pointer to the receiver object. + +- ``throw`` is used in exception handling. Note that the default + flags we pass to :ref:`GCC ` include ``-fno-exceptions``. + +- ``try`` is used in exception handling. Note that the default + flags we pass to :ref:`GCC ` include ``-fno-exceptions``. + +- ``typedef`` defines a type synonym. + +- ``union`` defines an untagged union. + +- ``using`` is a directive related to namespaces. + +- ``virtual`` declares a method which may be overridden. + +- ``wchar_t`` is the wide character type. diff --git a/source/lang/cpp/long.rst b/source/lang/cpp/long.rst new file mode 100644 index 0000000..d8498c0 --- /dev/null +++ b/source/lang/cpp/long.rst @@ -0,0 +1,52 @@ +.. highlight:: cpp + +.. _lang-long: + +``long`` +======== + +The ``long`` data type stores extended size integer values. You can +use a ``long`` when your values are too large to fit into an :ref:`int +`. A ``long`` occupies 8 bytes of memory. This yields a +range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion +billion, or about 92 million times the number of stars in the Milky +Way galaxy). The exact range of a ``long`` on the Maple is from +-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to +(2^63-1). A ``long`` it is subject to the same :ref:`overflow issues +` as any numeric data type. + +Here's an example of declaring a long (see :ref:`integer constants +` for an explanation of the "L" at the end of the +number):: + + // Speed of light in nanometers per second (approximate). + long c = 299792458000000000L; + +The general syntax for declaring an ``long`` variable named ``var``, +then giving it value ``val``, looks like:: + + long var = val; + +This is identical to the ``int`` syntax, with ``long`` replacing +``int``. + +Note that ``long`` values will still :ref:`overflow +`, just like ``int`` values, but their much +larger range makes this less likely to happen. + +The downside to using a ``long`` instead of an ``int`` (besides the +extra storage) is that :ref:`arithmetic ` operations +on ``long``\ s will take slightly longer than on ``int``\ s. + +See Also +-------- + +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`int ` +- :ref:`unsigned int ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/longcast.rst b/source/lang/cpp/longcast.rst new file mode 100644 index 0000000..2b92345 --- /dev/null +++ b/source/lang/cpp/longcast.rst @@ -0,0 +1,27 @@ +.. highlight:: cpp + +.. _lang-longcast: + +``long()`` (cast) +================= + +Converts a value to the :ref:`long ` data type. Here is +an example:: + + double d = 2.5; + long i = long(d); // i holds "2L", an long value + +The value inside of the parentheses (``long(...)``) can be of any type. +However, if it is not a numeric type (like ``double``, ``char``, +etc.), you will get strange results. + +See the :ref:`long ` reference for details about the +precision and limitations of ``long`` variables on the Maple. + +See Also +-------- + +- :ref:`long ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/modulo.rst b/source/lang/cpp/modulo.rst new file mode 100644 index 0000000..289fba0 --- /dev/null +++ b/source/lang/cpp/modulo.rst @@ -0,0 +1,70 @@ +.. highlight:: cpp + +.. _lang-modulo: + +Modulo Operator (``%``) +======================= + +Calculates the `remainder `_ +when one integer is divided by another. It is useful for keeping a +variable within a particular range (e.g. the size of an array). + +Syntax +------ + +:: + + dividend % divisor + +Parameters +---------- + +**dividend**: the number to be divided + +**divisor**: the number to divide by + +Returns +------- + +The remainder of **dividend**\ /\ **divisor**\ . + +Examples +-------- + +:: + + int x; + x = 7 % 5; // x now contains 2 + x = 9 % 5; // x now contains 4 + x = 5 % 5; // x now contains 0 + x = 4 % 5; // x now contains 4 + +:: + + /* update one value in an array each time through a loop */ + + int values[10]; + int i = 0; + + void setup() { + // no setup necessary + } + + void loop() { + values[i] = analogRead(0); + i = (i + 1) % 10; // modulo operator makes sure i stays between 0 and 9 + } + +Tip +--- + +The modulo operator does not work on floats. For that, you can use +the C standard library function `fmod() +`_. + +See Also +-------- + +- :ref:`Arithmetic ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/numeric-types.rst b/source/lang/cpp/numeric-types.rst new file mode 100644 index 0000000..9d2be48 --- /dev/null +++ b/source/lang/cpp/numeric-types.rst @@ -0,0 +1,79 @@ +.. _lang-numeric-types: + +Numeric types +============= + +This document serves as a reference for all of the built-in numeric +types which are available when programming in the IDE. Programmers +using the :ref:`command-line tools ` will have access +to these types as long as they have imported ``wirish.h``; several are +defined in in `libmaple_types.h +`_. + +.. _lang-numeric-types-integral: + +Integral types +-------------- + +.. cpp:type:: char + + 8-bit integer value. + +.. cpp:type:: short + + 16-bit integer value. + +.. cpp:type:: int + + 32-bit integer value. + +.. cpp:type:: long + + 64-bit integer value. + +.. cpp:type:: long long + + 64-bit integer value. + +.. cpp:type:: int8 + + Synonym for ``char``. + +.. cpp:type:: uint8 + + Synonym for ``unsigned char``. + +.. cpp:type:: int16 + + Synonym for ``short``. + +.. cpp:type:: uint16 + + Synonym for ``unsigned short``. + +.. cpp:type:: int32 + + Synonym for ``int``. + +.. cpp:type:: uint32 + + Synonym for ``unsigned int`` + +.. cpp:type:: int64 + + Synonym for ``long long`` + +.. cpp:type:: uint64 + + Synonym for ``unsigned long long``. + +Floating-Point Types +-------------------- + +.. cpp:type:: float + + 32-bit, IEEE 754 single-precision floating-point type. + +.. cpp:type:: double + + 64-bit, IEEE 754 double-precision floating-point type. diff --git a/source/lang/cpp/pointer.rst b/source/lang/cpp/pointer.rst new file mode 100644 index 0000000..0a42270 --- /dev/null +++ b/source/lang/cpp/pointer.rst @@ -0,0 +1,31 @@ +.. _lang-pointer: + +Pointer Operators (``&``, ``*``) +================================ + +The pointer operators ``&`` (reference) and ``*`` (dereference) are +different from the bitwise math operator :ref:`& +` and the arithmetic operator :ref:`* +`. + +Pointers are one of the more complicated subjects for beginners in +learning C, and it is possible to write many useful Arduino sketches +without ever encountering pointers. However, for manipulating certain +data structures, the use of pointers can simplify the code, improve +its efficiency, and generally provide many benefits that would be +difficult to achieve without the use of pointers. + +Introducing pointers is somewhat outside the scope of this +documentation. However, a good `pointer tutorial +`_ is available. +Also see the `Wikipedia article on pointers +`_, especially +the section on `pointers in C +`_. + +See Also +-------- + +- http://xkcd.com/138/ + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/return.rst b/source/lang/cpp/return.rst new file mode 100644 index 0000000..7b5039e --- /dev/null +++ b/source/lang/cpp/return.rst @@ -0,0 +1,61 @@ +.. highlight:: cpp + +.. _lang-return: + +``return`` +========== + +Terminates a function and return a value from a function to the +calling function, if the function has non-``void`` return type. + +Syntax: +------- + +:: + + // from within a "void" function: + return; + + // from within a non-"void" function: + return value; + +In the second case, ``value`` should have a type which is the same as +the return type of the function, or be convertible to it (like an +``int`` to a ``long``, etc.; see :ref:`this note +` for some references). + +Examples: +--------- + +A function to compare a sensor input to a threshold:: + + // converts analog readings between 0 and 400 to 0, and 400 up to 1. + int checkSensor() { + if (analogRead(0) > 400) { + return 1; + else { + return 0; + } + } + +An early ``return`` is also useful when testing a section of code +without having to "comment out" large sections of possibly buggy code, +like so:: + + void loop() { + + // brilliant code idea to test here + + return; + + // the rest of a dysfunctional sketch here + // this code will never be executed + } + +See Also +-------- + +- :ref:`comments ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/scope.rst b/source/lang/cpp/scope.rst new file mode 100644 index 0000000..7b65bab --- /dev/null +++ b/source/lang/cpp/scope.rst @@ -0,0 +1,120 @@ +.. highlight:: cpp + +.. _lang-scope: + +Scope +===== + +Variables in the C++ programming language, which Maple uses (all of +your sketches are C++ programs in disguise), have a property called +*scope*. Simply put, a variable's scope is made up of all of the +lines where the variable can be used. + +Scope in C++ is a fairly complex topic, so we won't try to describe it +in full here. Instead, we present a simplified view, describing two +different kinds of scopes, *global* and *local*. For more detailed +information, consult a C++ reference. + +Global and Local Variables +-------------------------- + +A global variable is one that can be "seen" by every function in a +program. In the :ref:`Maple IDE `, any variable declared outside +of a function (like :ref:`setup() ` and :ref:`loop() +`) is a global variable. + +A local variable can only be "seen" inside of a particular function. +You can declare a variable to be local to a function by declaring it +inside of the :ref:`curly braces ` which enclose +that function. + +When programs start to get larger and more complex, local variables +are a useful way to ensure that a function has exclusive access to its +own variables. This prevents programming errors when one function +mistakenly modifies variables used by another function. + +It is also sometimes useful to declare and initialize a variable +inside a :ref:`for ` loop. This creates a variable that +can only be accessed from inside the loop body. + +Example +------- + +Here is an example sketch (which you can copy into the Maple IDE and +run on your Maple) that illustrates the use of global and local +variables, as well as declaring variables inside of a ``for`` loop. +Be sure to open a :ref:`serial monitor ` after you +:ref:`verify ` and :ref:`upload ` the sketch:: + + int globalVar; // any function will see this variable + + void setup() { + // since "globalVar" is declared outside of any function, + // every function can "see" and use it: + globalVar = 50; + + // the variables "i" and "d" declared inside the "loop" function + // can't be seen here. see what happens when you uncomment the + // following lines, and try to Verify (compile) the sketch: + // + // i = 16; + // SerialUSB.print("i = "); + // SerialUSB.println(i); + // d = 26.5; + // SerialUSB.print("d = "); + // SerialUSB.println(d); + } + + void loop() { + // since "i" and "d" are declared inside of the "loop" function, + // they can only be seen and used from inside of it: + int i; + double d; + + for (int j = 0; j < 5; j++) { + // variable i can be used anywhere inside the "loop" function; + // variable j can only be accessed inside the for-loop brackets: + i = j * j; + SerialUSB.print("i = "); + SerialUSB.println(i); + } + + // globalVar can be accessed from anywhere. note how even + // though we set globalVar = 50 in the "setup" function, we can + // see that value here: + SerialUSB.print("globalVar = "); + SerialUSB.println(globalVar); + + // d can be accessed from anywhere inside the "loop" function: + d = 26.5; + SerialUSB.print("d = "); + SerialUSB.print(d); + SerialUSB.println(" (before separateFunction())"); + + separateFunction(); + + // notice how even though separateFunction() has a variable + // named "d", it didn't touch our (local) variable which has + // the same name: + SerialUSB.print("d = "); + SerialUSB.print(d); + SerialUSB.println(" (after separateFunction())"); + } + + void separateFunction() { + // variable "d" here has the same name as variable "d" inside of + // the "loop" function, but since they're both _local_ + // variables, they don't affect each other: + double d = 30.5; + SerialUSB.print("d = "); + SerialUSB.print(d); + SerialUSB.println(" (inside of separateFunction())"); + } + +See Also +-------- + +- `C++ programming Wikibook `_. +- Wikipedia article on `scope `_ + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/semicolon.rst b/source/lang/cpp/semicolon.rst new file mode 100644 index 0000000..8164616 --- /dev/null +++ b/source/lang/cpp/semicolon.rst @@ -0,0 +1,25 @@ +.. highlight:: cpp + +.. _lang-semicolon: + +Semicolon (``;``) +================= + +Used to end a line of code. Example:: + + int a = 13; + +Tip +--- + +Forgetting to end a line in a semicolon will result in a compiler +error. The error text may be obvious, and refer to a missing +semicolon, or it may not. If an impenetrable or seemingly illogical +compiler error comes up, one of the first things to check is a +missing semicolon, in the immediate vicinity, preceding the line at +which the compiler complained. + + + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/sizeof.rst b/source/lang/cpp/sizeof.rst new file mode 100644 index 0000000..eae509c --- /dev/null +++ b/source/lang/cpp/sizeof.rst @@ -0,0 +1,64 @@ +.. highlight:: cpp + +.. _lang-sizeof: + +``sizeof()`` +============ + +The ``sizeof`` operator on the Maple returns the number of bytes +needed to store a value of a given type\ [#fcharsize]_. This can be +an ordinary numeric type, like ``int``. It can be something more +complicated, like a ``struct`` or ``union``. If the argument to +``sizeof`` is an array, it returns the total number of bytes occupied +by the array. + +The general syntax looks like this:: + + sizeof(type) + sizeof(var) + +Example +------- + +The ``sizeof`` operator is useful for dealing with arrays (such as +strings) where it is convenient to be able to change the size of the +array without breaking other parts of the program. + +This program prints out a text string one character at a time. Try +changing the text phrase:: + + char myStr[] = "this is a test"; + int i; + + void setup() { + Serial.begin(9600); + } + + void loop() { + for (i = 0; i < sizeof(myStr) - 1; i++) { + Serial.print(i, DEC); + Serial.print(" = "); + Serial.println(myStr[i], BYTE); + } + } + + +Note that ``sizeof`` returns the total number of bytes. So for larger +variable types such as ``int``, the :ref:`for loop ` +would look something like this:: + + for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { + // do something with myInts[i] + } + +.. rubric:: Footnotes + +.. [#fcharsize] Technically (and pedantically) speaking, ``sizeof`` + returns a multiple of the number of bits a ``char`` occupies in + memory. However, on the Maple (this goes for most C++ + implementations), a ``char`` occupies 8 bits = 1 byte. All the C++ + standard guarantees, however, is that a ``char`` occupies at + *least* 8 bits. + +.. include:: cc-attribution.txt + diff --git a/source/lang/cpp/sqrt.rst b/source/lang/cpp/sqrt.rst new file mode 100644 index 0000000..956a754 --- /dev/null +++ b/source/lang/cpp/sqrt.rst @@ -0,0 +1,25 @@ +.. _lang-sqrt: + +sqrt() +====== + +Calculates the square root of a number. + +Library Documentation +--------------------- + +.. doxygenfunction:: sqrt + +Arduino Compatibility +--------------------- + +The Maple versino of ``sqrt()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`pow ` +- :ref:`sq ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/static.rst b/source/lang/cpp/static.rst new file mode 100644 index 0000000..5d1802e --- /dev/null +++ b/source/lang/cpp/static.rst @@ -0,0 +1,57 @@ +.. highlight:: cpp + +.. _lang-static: + +``static`` +========== + +The ``static`` keyword can be used to create variables that are +visible to only one function. However, unlike local variables that get +created and destroyed every time a function is called, ``static`` +variables persist beyond the function call, preserving their data +between function calls. + +Variables declared as ``static`` will only be created and initialized +the first time a function is called. + +.. note:: This is only one use of the ``static`` keyword in C++. It + has some other important uses that are not documented here; consult + a reliable C++ reference for details. + +Example +------- + +One use case for ``static`` variables is implementing counters that +last longer than the functions which need them, but shouldn't be +shared to other functions. Here's an example:: + + void setup() { + SerialUSB.begin(); + } + + void loop() { + int reading; + if (timeToReadSensors()) { + reading = readSensors(); + } + // do something with reading + } + + int readSensors() { + static int numSensorReadings = 0; + numSensorReadings++; + if (numSensorReadings % 100 == 0) { + SerialUSB.print("just got to another 100 sensor readings"); + } + return analogRead(...); + } + +In this example, the static variable ``numSensorReadings`` is +initialized to zero the first time ``readSensors()`` is called, and +then incremented, so it starts out at one. Subsequent calls to +``readSensors()`` won't reset ``numSensorReadings`` to zero, because +it was declared ``static``. Thus, ``numSensorReadings`` is a count of +the number of times that ``readSensors()`` has been called. + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/string.rst b/source/lang/cpp/string.rst new file mode 100644 index 0000000..0a270da --- /dev/null +++ b/source/lang/cpp/string.rst @@ -0,0 +1,128 @@ +.. highlight:: cpp + +.. _lang-string: + +Strings +======= + +Text strings can be represented in two ways. You can + +1. Use the :ref:`String ` data type, which is +part of the core as of version 0.0.9, or + +2. You can make a string out of an array of type :ref:`char +` and null-terminate it. + +This page describes the second method. + +Examples +-------- + +All of the following are valid declarations for strings:: + + char str1[15]; + char str2[6] = {'m', 'a', 'p', 'l', 'e'}; + char str3[6] = {'m', 'a', 'p', 'l', 'e', '\0'}; + char str4[ ] = "maple"; + char str5[6] = "maple"; + char str6[15] = "maple"; + +As you can see, there are several methods available for declaring and +initializing strings: + +- Declare an array of ``char`` without initializing it, as with ``str1``. + +- Declare an array of ``char`` (with one extra ``char``) and the + compiler will add the required null character, as with ``str2``. + +- Explicitly add the null character (``'\0'``), as with ``str3``. + +- Initialize with a string constant in quotation marks (``"..."``); + the compiler will size the array to fit the string constant and a + terminating null character (``str4``). + +- Initialize the array with an explicit size and string constant, + (``str5``). + +- Initialize the array, leaving extra space for a larger string + (``str6``). + +Null Termination +---------------- + +Generally, strings are terminated with a null character (`ASCII +`_ code 0). This allows functions +(like ``SerialUSB.print()``) to tell where the end of a string is. +Otherwise, they would continue reading subsequent bytes of memory that +aren't actually part of the string. + +This means that your string needs to have space for one more character +than the text you want it to contain. That is why ``str2`` and +``str5`` need to be six characters, even though "maple" is only five +-- the last position is automatically filled with a NULL +character. ``str4`` will be automatically sized to six characters, one +for the extra null. In the case of ``str3``, we've explicitly included +the null character (written ``'\0'``) ourselves. + +Note that it's possible to have a string without a final null +character (e.g. if you had specified the length of ``str2`` as five +instead of six). This will break most functions that use strings, so +you shouldn't do it intentionally. If you notice something behaving +strangely (operating on characters not in the string), however, this +could be the problem. + +Single quotes or double quotes? +------------------------------- + +Strings are always defined inside double quotes (``"Abc"``) and +characters are always defined inside single quotes (``'A'``). + +Wrapping long strings +--------------------- + +You can wrap long strings like this:: + + char myString[] = "This is the first line" + " this is the second line" + " etcetera"; + +Arrays of Strings +----------------- + +It is often convenient, when working with large amounts of text, +such as a project with an LCD display, to setup an array of +strings. Because strings themselves are arrays, this is in actually +an example of a two-dimensional array. + +In the code below, the asterisk after the datatype char ``char *`` +indicates that this is an array of "pointers". All array names are +actually pointers, so this is required to make an array of arrays. +Pointers are one of the more esoteric parts of C for beginners to +understand, but it isn't necessary to understand pointers in detail to +use them effectively here:: + + char* myStrings[] = {"This is string 1", "This is string 2", + "This is string 3", "This is string 4", + "This is string 5", "This is string 6"}; + + void setup() { + SerialUSB.begin(); + } + + void loop() { + for (int i = 0; i < 6; i++) { + SerialUSB.println(myStrings[i]); + delay(500); + } + } + + +See Also +-------- + +- :ref:`array ` +- :ref:`__attribute__ ` +- :ref:`Variables ` + + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/switchcase.rst b/source/lang/cpp/switchcase.rst new file mode 100644 index 0000000..b484bc5 --- /dev/null +++ b/source/lang/cpp/switchcase.rst @@ -0,0 +1,118 @@ +.. highlight:: cpp + +.. _lang-switchcase: + +``switch``\ /\ ``case`` +======================= + +Like :ref:`if ` statements, A ``switch`` statement controls +program flow by allowing you to specify different code that should be +executed under various cases. + +The general syntax looks like this:: + + switch (var) { + case val1: + // statements + break; + case val2: + // statements + break; + ... + default: + // statements + } + +Where ``var`` is a variable whose value to investigate, and the +``val1``, ``val2`` after each ``case`` are constant values that +``var`` might be. + +Description +----------- + +A ``switch`` statement compares the value of a variable to the values +specified in ``case`` statements. When a ``case`` statement is found +whose value matches that of the variable, the code in that case +statement is run. + +Here's a more concrete example:: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + afterTheSwitch(); + +In the above example, if ``var == 1``, then the code beginning on the +line after ``case 1`` gets executed. That is, if ``var`` is one, +``doThing1()`` gets called first, and then the ``break`` statement is +executed. + +The ``break`` keyword exits the ``switch`` statement, and is typically +used at the end of each ``case``. Since there is a ``break`` at the +end of ``case 1``, the ``switch`` statement exits, and the next line +to be run is the one which calls ``afterTheSwitch()``. + +Without a ``break``, the ``switch`` statement will continue executing +the following ``case`` expressions ("falling-through") until a +``break`` (or the end of the switch statement) is reached. Let's +pretend the ``switch`` looked like this instead:: + + switch (var) { + case 1: + doThing1(); + // no break statement anymore + case 2: + doThing2(); + break; + } + afterTheSwitch(); + +Now, if ``var`` is one, ``doThing1()`` gets executed like before. +However, without a ``break``, the code would continue to be executed +line-by-line, so ``doThing2()`` would be called next. At this point, +a ``break`` has been reached, so the program continues by calling +``afterTheSwitch()``. This is usually not what you want, which is why +each ``case`` usually has a ``break`` at the end. + +.. _lang-switchcase-default: + +Writing "``default:``" instead of a ``case`` statement allows you to +specify what to do if none of the ``case`` statements matches. Having +a ``default`` is optional (you can leave it out), but if you have one, +it must appear after all of the ``case`` statements. Let's add a +``default`` to the ``switch`` we've been discussing:: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + default: + doSomethingElse(); + } + afterTheSwitch(); + +If ``var`` is one, then ``doThing1()`` gets called. If ``var`` is +two, ``doThing2()`` gets called. If ``var`` is anything else, +``doSomethingElse()`` gets called. As stated above, a ``default`` is +optional. If you're missing one and none of the ``case`` statements +match, the ``switch`` does nothing at all, as if it weren't there. + +``switch`` statements are often used with an :ref:`enum ` +value as the variable to compare. In this case, you can write down +all of the values the ``enum`` takes as ``case`` statements, and be +sure you've covered all the possibilities. + +See also: +--------- + +- :ref:`if/else ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/unsignedchar.rst b/source/lang/cpp/unsignedchar.rst new file mode 100644 index 0000000..5b946ed --- /dev/null +++ b/source/lang/cpp/unsignedchar.rst @@ -0,0 +1,33 @@ +.. highlight:: cpp + +.. _lang-unsignedchar: + +``unsigned char`` +================= + +An unsigned version of the :ref:`char ` data type. An +``unsigned char`` occupies 1 byte of memory; it stores an integer from +0 to 255. + +Like an :ref:`unsigned int `, an ``unsigned char`` +won't store negative numbers; it is also subject to the same +:ref:`overflow issues ` as any integral data type. + +Example +------- + +:: + + unsigned char c = 240; + +See Also +-------- + + +- :ref:`byte ` +- :ref:`int ` +- :ref:`array ` +- :ref:`SerialUSB.println() ` +- :ref:`Serial.println() ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/unsignedint.rst b/source/lang/cpp/unsignedint.rst new file mode 100644 index 0000000..f6311da --- /dev/null +++ b/source/lang/cpp/unsignedint.rst @@ -0,0 +1,55 @@ +.. highlight:: cpp + +.. _lang-unsignedint: + +``unsigned int`` +================ + +An ``unsigned int`` (unsigned integer) is the same as an :ref:`int +` in that it stores a 4 byte integer value. However, +Instead of storing both negative and positive numbers, an ``unsigned +int`` can only store nonnegative values, yielding a range of 0 to +4,294,967,295 (the positive value is 2^32 - 1). + +The difference between an ``unsigned int`` and a (signed) ``int`` lies +in the way the highest bit, sometimes referred to as the "sign" bit, +is interpreted. In the case of the Maple ``int`` type (which is +signed), if the high bit is a "1", the number is interpreted as a +negative number, using a technique known as `two's complement math +`_. The +bits in an an ``unsigned int`` are interpreted according to the usual +rules for converting `binary to decimal +`_. + +An ``unsigned int`` is subject to the same :ref:`overflow issues +` as a regular ``int``; the only difference is +that an ``unsigned int`` will "underflow" at 0, and "overflow" at +4,294,967,295. Here is some example code which illustrates this:: + + unsigned int x; + x = 0; + x--; // x now contains 4,294,967,295; rolled over "left to right" + x++; // x now contains 0; rolled over "right to left" + +Here is an example of declaring an ``unsigned int`` variable named +``ledPin``, then giving it value 13:: + + unsigned int ledPin = 13; + +The general syntax for declaring an ``unsigned int`` variable named +``var``, then giving it value ``val``, looks like:: + + unsigned int var = val; + +See Also +-------- + +- :ref:`int ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`long ` +- :ref:`unsigned long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/unsignedlong.rst b/source/lang/cpp/unsignedlong.rst new file mode 100644 index 0000000..14a4fc3 --- /dev/null +++ b/source/lang/cpp/unsignedlong.rst @@ -0,0 +1,41 @@ +.. highlight:: cpp + +.. _lang-unsignedlong: + +``unsigned long`` +================= + +An unsigned version of the :ref:`long ` data type. An +``unsigned long`` occupies 8 bytes of memory; it stores an integer +from 0 to 2^64-1, which is approximately 1.8×10^19 (18 quintillion, or +18 billion billion). + +Like an :ref:`unsigned int `, an ``unsigned long`` +won't store negative numbers; it is also subject to the same +:ref:`overflow issues ` as any integral data type. + +Here is an example of declaring an ``unsigned long`` variable named +``c``, then giving it value 299,792,458,000,000,000 (see :ref:`integer +constants ` for an explanation of the "L" +at the end of the number):: + + // Speed of light in nanometers per second (approximate). + unsigned long c = 299792458000000000L; + +The general syntax for declaring an ``unsigned long`` variable named +``var``, then giving it value ``val``, looks like:: + + unsigned long var = val; + +See Also +-------- + +- :ref:`long ` +- :ref:`int ` +- :ref:`unsigned ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/variables.rst b/source/lang/cpp/variables.rst new file mode 100644 index 0000000..9094cd5 --- /dev/null +++ b/source/lang/cpp/variables.rst @@ -0,0 +1,170 @@ +.. highlight:: cpp + +.. _lang-variables: + +Variables +========= + +A variable is a way of naming and storing a value for later use by +the program, such as data from a sensor or an intermediate value +used in a calculation. + +.. contents:: Contents + :local: + +.. _lang-variables-declaring: + +Declaring Variables +------------------- + +Before they are used, all variables have to be *declared*. Declaring a +variable means defining its type, giving it a name, and (optionally) +giving it an initial value (this is often referred to as +*initializing* the variable). Variables do not have to be initialized +(given a value) when they are declared, but it is good style to give +them an initial value whenever possible. + +Here is an example of declaring a variable named ``inputVariable1`` +with type :ref:`int ` (the ``int`` type is used to store +integers, like -2, -1, 0, 1, etc.):: + + int inputVariable1; + +In the above declaration, we did not give the variable an initial +value. Here is another example, where we declare an ``int`` variable +named ``inputVariable2``, with an initial value of ``0``:: + + int inputVariable2 = 0; + +The Maple environment comes ready to use with many useful types of +variables. See the :ref:`built-in types ` page +for more information. + +Here are a few examples of declaring variables of different types:: + + int lightSensVal; + char currentLetter; + unsigned long speedOfLight = 186000UL; + char errorMessage = {"choose another option"}; // see string + +Naming Variables +---------------- + +The rules for naming a variable are simple. Names for variables can +contain letters, numbers, and underscores (the underscore is the +:kbd:`_` character), and cannot begin with a number. So +``temperature_reading``, ``tempReading``, ``tempReading1``, and +``tempReading2`` are all valid variable names, but ``4_temp_readings`` +is not, because it begins with a number. + +You cannot choose a name for a variable that is one of the C++ +:ref:`keywords `. + +Variable names are case-sensitive, so "tempreading" and "tempReading" +are different variables. However, it is very bad style to write code +that chooses variables which are the same up to case. + +You should give your variables descriptive names, so as to make your +code more readable. Variable names like ``tiltSensor`` or +``pushButton`` help you (and anyone else reading your code) understand +what the variable represents. Variable names like ``var`` or +``value``, on the other hand, do little to make your code readable. + +.. _lang-variables-scope: + +Variable Scope +-------------- + +An important choice that programmers face is where (in the program +text) to declare variables. The specific place that variables are +declared influences how various functions in a program will "see" the +variable. This is called variable *scope*. See the :ref:`scope +reference ` for more information. + +.. _lang-variables-initializing: + +Initializing Variables +---------------------- + +Variables may be *initialized* (assigned a starting value) when they +are declared or not. It is always good programming practice however to +double check that a variable has valid data in it before it is used. +Using a variable before you give it a value is a common source of +bugs. + +.. _lang-variables-rollover: + +Variable Rollover +----------------- + +Every (numeric) type has a valid *range*. The range of a type is the +smallest and largest value that a variable of that type can store. +For example, the :ref:`int ` type has a range of +-2,147,483,648 to 2,147,483,647 [#frange]_. + +When variables are made to exceed their range's maximum value, they +"roll over" back to their minimum value. Note that this happens in +both directions. It's like in the game *Pac-Man* -- when Pac-Man goes +past the right edge of the screen, he reappears on the left, and when +he goes past the left side of the screen, he reappears on the right:: + + int x; + x = -2,147,483,648; + x = x - 1; // x now contains -2,147,483,647; rolled over "left to right" + + x = 2,147,483,647; + x = x + 1; // x now contains -2,147,483,648; rolled over "right to left" + +Each numeric type's reference page includes its range. See the +:ref:`built-in types ` reference for links to each +type's reference page. + +Using Variables +--------------- + +Once variables have been declared, they are given values using the +:ref:`assignment operator `, which is a single equals +sign, ``=``. The assignment operator tells the program to store the +value on the right side of the equals sign into the variable on the +left side:: + + inputVariable1 = 7; // sets variable named inputVariable1 to 7 + inputVariable2 = analogRead(2); // sets variable named inputVariable2 to + // the (digitized) input voltage read from + // analog pin #2 + +Once a variable has been set (assigned a value), you can test its +value to see if it meets certain conditions, or you can use its value +directly. For instance, the following code tests whether the +inputVariable2 is less than 100, then sets a delay based on +inputVariable2 (which, at that point, is at least 100):: + + if (inputVariable2 < 100) { + inputVariable2 = 100; + } + + delay(inputVariable2); + +See Also +-------- + +- :ref:`lang-scope` +- :ref:`lang-numeric-types` + +.. rubric:: Footnotes + +.. [#frange] This range might seem a little weird at first. The + reasons for this range of values have to do with the fact that an + ``int`` occupies 32 bits of memory, and the facts :: + + 2^31 = -2,147,483,648 + 2^31 - 1 = 2,147,483,647 + + + Why 2^31 instead of 2^32? Well, that has to do with `how ints are + (usually) stored + `_ on computers. + + +.. include:: cc-attribution.txt + diff --git a/source/lang/cpp/void.rst b/source/lang/cpp/void.rst new file mode 100644 index 0000000..88bd448 --- /dev/null +++ b/source/lang/cpp/void.rst @@ -0,0 +1,31 @@ +.. highlight:: cpp + +.. _lang-void: + +``void`` +======== + +The ``void`` keyword is used only in function declarations. It +indicates that the function is expected to return no information to +the function from which it was called, or that it expects no arguments +from its caller. + +Example +------- + +:: + + // actions are performed in the functions "setup" and "loop" + // but no information is reported to the larger program + + void setup() { + // ... + } + + void loop() { + // ... + } + +.. TODO doc page on function declaration? + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/while.rst b/source/lang/cpp/while.rst new file mode 100644 index 0000000..9047d05 --- /dev/null +++ b/source/lang/cpp/while.rst @@ -0,0 +1,38 @@ +.. highlight:: cpp + +.. _lang-while: + +``while`` +========= + +Syntax +------ + +:: + + while (expression) { + // block of code + } + +Description +----------- + +``while`` loops will repeat the statements inside their associated +block of code until the expression inside the parentheses becomes +:ref:`false `. Something must change the tested +expressions' value, or the ``while`` loop will never exit. This could +be in your code, such as an incremented variable, or an external +condition, such as testing a sensor. + +Example +------- + +:: + + var = 0; + while(var < 200) { + // do something repetitive 200 times + var++; + } + +.. include:: cc-attribution.txt diff --git a/source/language-index.rst b/source/language-index.rst index ddc7849..1c5e35f 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -1,16 +1,28 @@ .. _language-index: -Language Reference Index -======================== - -This is the index of the :ref:`language reference ` -documentation. - -.. toctree:: - :maxdepth: 1 - :glob: - - lang/* +============================= +Complete Maple Language Index +============================= + +This is the index of Maple's :ref:`language reference ` documentation. The 'Maple API' column includes language specific to Maple as a microcontroller development platform, while the language in 'C++ for Maple' is more generally applied. + +# Fix above explanation/have marti write it + +.. _index-language-index-cpp: +.. _index-language-index-api: + ++--------------------------------------------+----------------------------------------------+ +| Maple API | :ref:`C++ for Maple ` | +| | | ++============================================+==============================================+ +| | | +| .. toctree:: | .. toctree:: | +| :maxdepth: 1 | :maxdepth: 1 | +| :glob: | :glob: | +| | | +| lang/api/* | lang/cpp/* | +| | | ++--------------------------------------------+----------------------------------------------+ .. Unfinished, unimplemented in libmaple: diff --git a/source/language.rst b/source/language.rst index 463041e..8e5d454 100644 --- a/source/language.rst +++ b/source/language.rst @@ -268,10 +268,16 @@ the Maple. However, they will be present in future versions: .. _newlib: http://sourceware.org/newlib/ +.. _cpp-for-maple: + +C++ for Maple +-------------- +If you haven't programmed in C++, or if you just need to jog your memory, you may want to check out our :ref:`C++ for Maple Index`. It covers programming ideas and C++ that will definitely come in handy. + .. _arduino_c_for_c_hackers: -Note for C/C++ Programmers --------------------------- +Note for C/C++ Hackers +---------------------- This is a note for programmers comfortable with C or C++ (although, you C programmers should remember that `C++ is not a superset of C diff --git a/source/libraries.rst b/source/libraries.rst index 4c87539..567aec8 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -57,8 +57,8 @@ the hardware i2c peripheral on the stm32 as well as the DMA for performance. Support for slave, smBUS, and multimaster modes are also slated for inclusion in the enhanced Wire port. -Function Reference -^^^^^^^^^^^^^^^^^^ +Wire Function Reference +^^^^^^^^^^^^^^^^^^^^^^^ ``Wire.begin()`` Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL diff --git a/source/specs.rst b/source/specs.rst new file mode 100644 index 0000000..43c91a1 --- /dev/null +++ b/source/specs.rst @@ -0,0 +1,28 @@ +.. _specs: + +.. _specs-Technical-Specifications: + +================================ +Maple's Technical Specifications +================================ + + * STM32 F103RB: a **32-bit** ARM Cortex M3 microprocessor + * Clock Speed: **72 MHz** + * Operating Voltage: 3.3V + * Input Voltage (recommended): 3.0V-12V + * 39 Digital I/O Pins (:ref:`GPIO `) + * **16 Analog** Input Pins (:ref:`ADC `) + * **15 PWM pins** at 16-bit resolution (:ref:`PWM `) + * Dedicated **USB** port for programming and communications (:ref:`USB`) + * External **JTAG** interface (:ref:`USB `) + * **128 Flash** and **20KB SRAM** + * 64 Channel nested vector interrupt handler (including external interrupt on GPIO’s) + * Integrated **SPI** (:ref:`SPI`) + * Integrated **I2C** (:ref:`I2C`) + * 7 Channels of Direct Memory Access (DMA) + * 3 **USART** divices (:ref:`USART `) + * Four 4-channel Timers (:ref:`Timers `) + * Supplies up to 800mA @ 3.3v + * Support for low power and sleep modes (<500uA) + * Dimensions are 2.05″x2.1″ + -- cgit v1.2.3 From 11573d0fca18ef2ccd965ab67d419afd48b7cef2 Mon Sep 17 00:00:00 2001 From: Hanna Mendes Levitin Date: Thu, 2 Dec 2010 22:38:45 -0500 Subject: side reorder, home link, template mod to add rel bar links --- source/_templates/layout.html | 6 ++++++ source/conf.py | 4 ++-- source/home.rst | 9 ++++----- source/i2c.rst | 2 +- source/index.rst | 2 +- source/language-index.rst | 8 ++++---- source/specs.rst | 5 +++-- 7 files changed, 21 insertions(+), 15 deletions(-) create mode 100644 source/_templates/layout.html diff --git a/source/_templates/layout.html b/source/_templates/layout.html new file mode 100644 index 0000000..98b3d82 --- /dev/null +++ b/source/_templates/layout.html @@ -0,0 +1,6 @@ +{% extends "!layout.html" %} +{% block rootrellink %} +
  • LeafLabs |
    • +
  • Docs Home |
    • + {{ super() }} +{% endblock %} \ No newline at end of file diff --git a/source/conf.py b/source/conf.py index 755f4ce..1ad4e57 100644 --- a/source/conf.py +++ b/source/conf.py @@ -143,10 +143,10 @@ html_theme_options = { # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = 'LeafLabs' + project + ' v' + release + ' Documentation' +html_title = project + ' v' + release + ' Documentation' # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +html_short_title = 'Index' # The name of an image file (relative to this directory) to place at the top # of the sidebar. diff --git a/source/home.rst b/source/home.rst index 9193e90..db5b56e 100644 --- a/source/home.rst +++ b/source/home.rst @@ -7,10 +7,7 @@ Maple Documentation Home Welcome! -Maple is a user-friendly prototyping platform developed by LeafLabs in Cambridge, MA. Using Maple, creators with any level of experience can implement beautiful ideas that require the power of a 32-bit processor. For more details about Maple's hardware, please see its :ref:`technical specifications `. To start using your Maple, keep reading. - -.. contents:: Contents - :local: +Maple is a user-friendly prototyping platform developed by LeafLabs in Cambridge, MA. Using Maple, creators with any level of experience can implement beautiful ideas that require the power of a 32-bit processor. For more details about Maple's hardware, please see its :ref:`technical specifications `. To start using your Maple, keep reading .. _home-Getting-Started: @@ -19,9 +16,11 @@ Getting Started :ref:`Quickstart ` +:ref:`IDE Anatomy ` + :ref:`Basic Language Reference ` -:ref:`Full Documentation ` +:ref:`Tech Specs` .. _home-Problem-Solving: diff --git a/source/i2c.rst b/source/i2c.rst index ddb2ac9..6e5b946 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -6,7 +6,7 @@ .. note:: - The i2c interface is currently only available from the 'i2c' branch + The |i2c| interface is currently only available from the 'i2c' branch of the github `libmaple `_ repository. diff --git a/source/index.rst b/source/index.rst index 9fee4d2..c552dd4 100644 --- a/source/index.rst +++ b/source/index.rst @@ -34,7 +34,7 @@ Maple Documentation Contents .. _index-hardware: -**Hardware Features:** +**Hardware Peripherals:** .. toctree:: :maxdepth: 1 diff --git a/source/language-index.rst b/source/language-index.rst index 1c5e35f..7843cb0 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -1,12 +1,12 @@ .. _language-index: -============================= -Complete Maple Language Index -============================= +======================= +Complete Language Index +======================= This is the index of Maple's :ref:`language reference ` documentation. The 'Maple API' column includes language specific to Maple as a microcontroller development platform, while the language in 'C++ for Maple' is more generally applied. -# Fix above explanation/have marti write it +# Fix above explanation .. _index-language-index-cpp: .. _index-language-index-api: diff --git a/source/specs.rst b/source/specs.rst index 43c91a1..4972a83 100644 --- a/source/specs.rst +++ b/source/specs.rst @@ -11,8 +11,9 @@ Maple's Technical Specifications * Operating Voltage: 3.3V * Input Voltage (recommended): 3.0V-12V * 39 Digital I/O Pins (:ref:`GPIO `) - * **16 Analog** Input Pins (:ref:`ADC `) - * **15 PWM pins** at 16-bit resolution (:ref:`PWM `) + * 16 Analog Input Pins + * 12-bit **ADC** resolution (:ref:`ADC `) + * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) * Dedicated **USB** port for programming and communications (:ref:`USB`) * External **JTAG** interface (:ref:`USB `) * **128 Flash** and **20KB SRAM** -- cgit v1.2.3 From 210f3d2b1555bae87c9de27ea145e16d3bddb0f8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 3 Dec 2010 20:18:00 -0500 Subject: cleaning up previous commits. note that addition of new files under docs/source/lang/api and docs/source/lang/cpp which were just copies of files in docs/source/lang/ imply that change history is lost to git. --- source/confDefaultGreen.txt | 250 ------------------------------ source/home.rtf | 43 ------ source/lang/abs.rst | 48 ------ source/lang/analogread.rst | 152 ------------------- source/lang/analogwrite.rst | 166 -------------------- source/lang/arithmetic.rst | 127 ---------------- source/lang/array.rst | 123 --------------- source/lang/assignment.rst | 70 --------- source/lang/attachinterrupt.rst | 102 ------------- source/lang/bit.rst | 44 ------ source/lang/bitclear.rst | 44 ------ source/lang/bitread.rst | 46 ------ source/lang/bitset.rst | 46 ------ source/lang/bitshift.rst | 144 ------------------ source/lang/bitwisemath.rst | 186 ----------------------- source/lang/bitwrite.rst | 46 ------ source/lang/boolean.rst | 91 ----------- source/lang/booleanvariables.rst | 54 ------- source/lang/break.rst | 35 ----- source/lang/byte.rst | 34 ----- source/lang/bytecast.rst | 50 ------ source/lang/char.rst | 50 ------ source/lang/charcast.rst | 36 ----- source/lang/comments.rst | 67 -------- source/lang/comparison.rst | 87 ----------- source/lang/compoundarithmetic.rst | 44 ------ source/lang/compoundbitwise.rst | 231 ---------------------------- source/lang/const.rst | 52 ------- source/lang/constants.rst | 304 ------------------------------------- source/lang/constrain.rst | 69 --------- source/lang/continue.rst | 32 ---- source/lang/cos.rst | 32 ---- source/lang/curly-braces.rst | 109 ------------- source/lang/define.rst | 56 ------- source/lang/delay.rst | 72 --------- source/lang/delaymicroseconds.rst | 65 -------- source/lang/detachinterrupt.rst | 37 ----- source/lang/digitalread.rst | 58 ------- source/lang/digitalwrite.rst | 68 --------- source/lang/double.rst | 48 ------ source/lang/doublecast.rst | 27 ---- source/lang/dowhile.rst | 27 ---- source/lang/enum.rst | 53 ------- source/lang/float.rst | 50 ------ source/lang/floatcast.rst | 28 ---- source/lang/for.rst | 142 ----------------- source/lang/goto.rst | 130 ---------------- source/lang/highbyte.rst | 59 ------- source/lang/if.rst | 121 --------------- source/lang/include.rst | 72 --------- source/lang/increment.rst | 37 ----- source/lang/int.rst | 64 -------- source/lang/intcast.rst | 29 ---- source/lang/keywords.rst | 205 ------------------------- source/lang/long.rst | 52 ------- source/lang/longcast.rst | 27 ---- source/lang/loop.rst | 45 ------ source/lang/lowbyte.rst | 25 --- source/lang/map.rst | 68 --------- source/lang/max.rst | 65 -------- source/lang/micros.rst | 46 ------ source/lang/millis.rst | 52 ------- source/lang/min.rst | 66 -------- source/lang/modulo.rst | 70 --------- source/lang/numeric-types.rst | 79 ---------- source/lang/pinmode.rst | 77 ---------- source/lang/pointer.rst | 31 ---- source/lang/pow.rst | 23 --- source/lang/pwmwrite.rst | 49 ------ source/lang/random.rst | 73 --------- source/lang/randomseed.rst | 60 -------- source/lang/return.rst | 61 -------- source/lang/scope.rst | 120 --------------- source/lang/semicolon.rst | 25 --- source/lang/serial.rst | 226 --------------------------- source/lang/serialusb.rst | 242 ----------------------------- source/lang/setup.rst | 29 ---- source/lang/sin.rst | 32 ---- source/lang/sizeof.rst | 64 -------- source/lang/sq.rst | 46 ------ source/lang/sqrt.rst | 25 --- source/lang/static.rst | 57 ------- source/lang/string.rst | 128 ---------------- source/lang/switchcase.rst | 118 -------------- source/lang/tan.rst | 31 ---- source/lang/unsignedchar.rst | 33 ---- source/lang/unsignedint.rst | 55 ------- source/lang/unsignedlong.rst | 41 ----- source/lang/variables.rst | 170 --------------------- source/lang/void.rst | 31 ---- source/lang/volatile.rst | 65 -------- source/lang/while.rst | 38 ----- 92 files changed, 7007 deletions(-) delete mode 100644 source/confDefaultGreen.txt delete mode 100644 source/home.rtf delete mode 100644 source/lang/abs.rst delete mode 100644 source/lang/analogread.rst delete mode 100644 source/lang/analogwrite.rst delete mode 100644 source/lang/arithmetic.rst delete mode 100644 source/lang/array.rst delete mode 100644 source/lang/assignment.rst delete mode 100644 source/lang/attachinterrupt.rst delete mode 100644 source/lang/bit.rst delete mode 100644 source/lang/bitclear.rst delete mode 100644 source/lang/bitread.rst delete mode 100644 source/lang/bitset.rst delete mode 100644 source/lang/bitshift.rst delete mode 100644 source/lang/bitwisemath.rst delete mode 100644 source/lang/bitwrite.rst delete mode 100644 source/lang/boolean.rst delete mode 100644 source/lang/booleanvariables.rst delete mode 100644 source/lang/break.rst delete mode 100644 source/lang/byte.rst delete mode 100644 source/lang/bytecast.rst delete mode 100644 source/lang/char.rst delete mode 100644 source/lang/charcast.rst delete mode 100644 source/lang/comments.rst delete mode 100644 source/lang/comparison.rst delete mode 100644 source/lang/compoundarithmetic.rst delete mode 100644 source/lang/compoundbitwise.rst delete mode 100644 source/lang/const.rst delete mode 100644 source/lang/constants.rst delete mode 100644 source/lang/constrain.rst delete mode 100644 source/lang/continue.rst delete mode 100644 source/lang/cos.rst delete mode 100644 source/lang/curly-braces.rst delete mode 100644 source/lang/define.rst delete mode 100644 source/lang/delay.rst delete mode 100644 source/lang/delaymicroseconds.rst delete mode 100644 source/lang/detachinterrupt.rst delete mode 100644 source/lang/digitalread.rst delete mode 100644 source/lang/digitalwrite.rst delete mode 100644 source/lang/double.rst delete mode 100644 source/lang/doublecast.rst delete mode 100644 source/lang/dowhile.rst delete mode 100644 source/lang/enum.rst delete mode 100644 source/lang/float.rst delete mode 100644 source/lang/floatcast.rst delete mode 100644 source/lang/for.rst delete mode 100644 source/lang/goto.rst delete mode 100644 source/lang/highbyte.rst delete mode 100644 source/lang/if.rst delete mode 100644 source/lang/include.rst delete mode 100644 source/lang/increment.rst delete mode 100644 source/lang/int.rst delete mode 100644 source/lang/intcast.rst delete mode 100644 source/lang/keywords.rst delete mode 100644 source/lang/long.rst delete mode 100644 source/lang/longcast.rst delete mode 100644 source/lang/loop.rst delete mode 100644 source/lang/lowbyte.rst delete mode 100644 source/lang/map.rst delete mode 100644 source/lang/max.rst delete mode 100644 source/lang/micros.rst delete mode 100644 source/lang/millis.rst delete mode 100644 source/lang/min.rst delete mode 100644 source/lang/modulo.rst delete mode 100644 source/lang/numeric-types.rst delete mode 100644 source/lang/pinmode.rst delete mode 100644 source/lang/pointer.rst delete mode 100644 source/lang/pow.rst delete mode 100644 source/lang/pwmwrite.rst delete mode 100644 source/lang/random.rst delete mode 100644 source/lang/randomseed.rst delete mode 100644 source/lang/return.rst delete mode 100644 source/lang/scope.rst delete mode 100644 source/lang/semicolon.rst delete mode 100644 source/lang/serial.rst delete mode 100644 source/lang/serialusb.rst delete mode 100644 source/lang/setup.rst delete mode 100644 source/lang/sin.rst delete mode 100644 source/lang/sizeof.rst delete mode 100644 source/lang/sq.rst delete mode 100644 source/lang/sqrt.rst delete mode 100644 source/lang/static.rst delete mode 100644 source/lang/string.rst delete mode 100644 source/lang/switchcase.rst delete mode 100644 source/lang/tan.rst delete mode 100644 source/lang/unsignedchar.rst delete mode 100644 source/lang/unsignedint.rst delete mode 100644 source/lang/unsignedlong.rst delete mode 100644 source/lang/variables.rst delete mode 100644 source/lang/void.rst delete mode 100644 source/lang/volatile.rst delete mode 100644 source/lang/while.rst diff --git a/source/confDefaultGreen.txt b/source/confDefaultGreen.txt deleted file mode 100644 index 789a5a0..0000000 --- a/source/confDefaultGreen.txt +++ /dev/null @@ -1,250 +0,0 @@ -# -*- coding: utf-8 -*- -# -# libmaple documentation build configuration file, created by -# sphinx-quickstart on Thu Oct 7 06:42:30 2010. -# -# 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 sys, os - - -# 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. -# -# We rely on Michael Jones's breathe as a Doxygen-to-Sphinx bridge. -# See libmaple/docs/README for information on obtaining it and letting -# Sphinx know where it is. -sys.path.append(os.environ['BREATHE_HOME']) - -# -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', 'sphinx.ext.todo', - 'sphinx.ext.coverage', 'breathe'] - -# 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'Maple' -copyright = u'2010, LeafLabs, LLC' - -# 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. -# -# The short X.Y version. -version = '0.0' -# The full version, including alpha/beta/rc tags. -release = '0.0.9' - -# 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 = ['epilog.rst', 'prolog.rst'] - -# Included at the end of every source file that is read. -with open('epilog.rst', 'r') as ep: - rst_epilog = ep.read() - -# Included at the beginning of every source file that is read. -with open('prolog.rst', 'r') as pr: - rst_prolog = pr.read() - -# 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 = [] - -# Warn about all references where the target cannot be found. -nitpicky = True - -# -- 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 = 'nature' - -# 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. - -# 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 -# " v documentation". -html_title = project + ' v' + release + ' Documentation' - -# 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 = '_static/img/round_logo_60x60.png' - -# 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 = '_static/img/round_logo_32x32.ico' - -# 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'] - -# 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 = { - '**': ['globaltoc.html', 'searchbox.html'], -} - - -# 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 = False - -# 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 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 = 'mapledoc' - - -# -- Options for LaTeX output ------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target file, title, author, documentclass [howto/manual]) -latex_documents = [ - ('index', 'maple.tex', u'Maple Documentation', - u'LeafLabs, LLC', '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 - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# 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', 'maple', u'Maple Documentation', - [u'LeafLabs, LLC'], 1) -] - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} - - -# -- Options for breathe integration ------------------------------------------ - -breathe_projects = {'libmaple' : os.path.join(os.environ['LIB_MAPLE_HOME'], - 'docs', 'doxygen', 'xml')} - -breathe_default_project = 'libmaple' diff --git a/source/home.rtf b/source/home.rtf deleted file mode 100644 index dda3ecd..0000000 --- a/source/home.rtf +++ /dev/null @@ -1,43 +0,0 @@ -.. _home: - -=================== -Maple Documentation -=================== - -.. image:: /_static/img/maple_rev3.jpg - :align: left - -Welcome! - -Maple is a user-friendly prototyping platform developed by LeafLabs in Cambridge, MA. Using Maple, creators with any level of experience can implement beautiful ideas that require the power of a 32-bit processor. - -Based on a ARM Cortex M3 (STFM32F103RB) chip, Maple runs at up to 72 MHz and has 39 digital input/out pins, 16 analog inputs, native full speed USB, 3 USARTs, integrated SPI/I2C support, and is Arduino compatible. - -Getting Started -^^^^^^^^^^^^^^^ -.. sidebar:: Tech Specs - - Microcontroller: STM32 F103RB - Clock Speed: 72 MHz - Operating Voltage: 3.3V - Input Voltage (recommended): 3.0V-12V - Digital I/O Pins: 39 - Analog Input Pins: 16 - Flash Memory: 128 KB - SRAM: 20KB - 64 Channel nested vector interrupt handler (including external interrupt on GPIO’s) - Integrated SPI/I2C and 7 Channels of Direct Memory Access (DMA) - Supplies up to 800mA @ 3.3v - Support for low power and sleep modes (<500uA) - Dimensions: 2.05″x2.1″ - -:ref:`Quickstart ` - -:ref:`Basic Language Reference ` Program your Maple. - -:ref:`Full Documentation ` - -Problem Solving -^^^^^^^^^^^^^^^^^ - -Check out our :ref:`troubleshooting guide ` and :ref:`known problems` page. If you don't find what you're looking for, hit the `forums `_ to ask questions to the LeafLabs team and other Maple users. Good luck, and have fun! \ No newline at end of file diff --git a/source/lang/abs.rst b/source/lang/abs.rst deleted file mode 100644 index 0f71d9b..0000000 --- a/source/lang/abs.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. highlight:: cpp - -.. _lang-abs: - -abs() -====== - -(Macro) computes the absolute value of a number. - -Syntax ------- - -:: - - abs(x) - -Parameters ----------- - -**x**: the number. - -Returns -------- - -**x**: if **x** is greater than or equal to 0. - -**-x**: if **x** is less than 0. - -Warning -------- - -Because of the way ``abs()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - abs(a++); // avoid this - yields incorrect results - - abs(a); // use this instead - - a++; // keep other operations outside abs() - - -Arduino Compatibility ---------------------- - -Maple's implementation of ``abs()`` is compatible with Arduino. - - -.. include:: cc-attribution.txt diff --git a/source/lang/analogread.rst b/source/lang/analogread.rst deleted file mode 100644 index 0c93650..0000000 --- a/source/lang/analogread.rst +++ /dev/null @@ -1,152 +0,0 @@ -.. highlight:: cpp - -.. _lang-analogread: - -analogRead() -============ - -Used to perform ADC conversion. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: analogRead - -Discussion ----------- - -Reads the value from the specified analog pin. The Maple board -contains a 16-channel, 12-bit analog to digital converter. This means -that it will map input voltages between 0 and 3.3 volts into integer -values between 0 and 4095. This yields a resolution between readings -of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors -interfere with getting full accuracy and precision. For more -information, see :ref:`adc`. - -Before calling analogRead() on a pin, that pin must first be -configured for analog input, using :ref:`lang-pinMode` (you only -have to do this once, so it's usually done in :ref:`lang-setup`\ ). - -It takes about 0.8 microseconds (.0000008 seconds) to read an analog -input, so the maximum sample rate using this function is approximately -1.3 million samples per second\ [#fsamp]_. - - -Parameter Discussion --------------------- - -The pin parameter is the number of the analog input pin to read from. -Header pins on the Maple with ADC functionality (marked as "AIN" on -the silkscreen) are: - - 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 - -Note that pins 3, 27, and 28 are not marked AIN on the silkscreen -for Maple revisions through Rev 5, however, they **do work** as -analog input pins. - -Note ----- - -If the analog input pin is not connected to anything, the value -returned by analogRead() will fluctuate based on a number of factors -(e.g. the values of the other analog inputs, how close your hand is to -the board, etc.) in a seemingly random way. - - -Example -------- - - :: - - - int analogPin = 3; // potentiometer wiper (middle terminal) connected - // to analog pin 3. outside leads to ground and +3.3V - int val = 0; // variable to store the value read - - void setup() { - pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input - SerialUSB.begin(); // set up usb virtual COM port - } - - void loop() { - val = analogRead(analogPin); // read the input pin - SerialUSB.println(val); // print the value, for debugging with - // a serial monitor - } - - -Arduino Compatibility ---------------------- - -The Arduino board contains a 6 channel (8 channels on the Mini and -Nano, 16 on the Mega), 10-bit analog to digital converter with an -input voltage range of 0V--5V. This means that it will map input -voltages between 0 and 5 volts (which is **larger** than Maple's range -of 0V-3.3V) into integer values between 0 and 1023 (which is -**smaller** than the Maple's range of 0--4095). - -This yields a theoretical resolution between readings of: 5 volts / -1024 units or .0049 volts (4.9 mV) per unit on Arduino boards, which -is larger, and thus less precise, than Maple's 0.0008 volts (0.8 mV). - -If your program expects Arduino-style 10-bit ADC, you can :ref:`right -shift ` the value of a Maple readout by 2, like so:: - - // right shift means that the result will be between 0 and 1023; - // be aware that you're losing a lot of precision if you do this - int adc_reading = analogRead(pin) >> 2; - -On the Arduino, the input range and resolution can be changed using -their implementation of `analogReference() -`_\ . Because of the -way its hardware (as of Rev 5) was designed, it's not possible to -implement analogReference on the Maple, so this function doesn't -exist. If your inputs lie in a different voltage range than 0V--3.3V, -you'll need to bring them into that range before using analogRead. -Some basic tools to accomplish this are `resistor dividers -`_ and `Zener diodes -`_\ -. However, opamps and other powered components can also be used if -greater precision is required. - -Finally, On the Arduino, it takes significantly longer to read analog -input: about 100 microseconds (0.0001 s), so the maximum reading rate -is 10,000 times a second. - - -See also --------- - -- :ref:`ADC note ` -- `(Arduino) Tutorial: Analog Input Pins `_ - - -.. rubric:: Footnotes - -.. [#fsamp] This is based on the current configuration of a 55.5 cycle - sample time, at 72 MHz. However, the minimum sample time *possible* - is 1.5 cycles, leading to a theoretical maximum of approximately 48 - million samples per second (of course, doing anything with the - readings also consumes cycles, so this maximum can't be reached in - practice). - - See the `STM32 Reference Manual `_, §§11.12.4--5 - (pp. 225--226), for more information on the low-level bit twiddling - currently necessary to change the sample time. For examples of how - the ADCs are configured in libmaple, see `adc.h - `_ - and `adc.c - `_\ - . Be aware that changing the sample time has important - consequences related to the impedance of the device connected to - the input pin. If you want to make changes, as a minimum, you - should first read ST's application notes on `ADC modes - `_ and `ADC oversampling - `_. - - -.. include:: cc-attribution.txt diff --git a/source/lang/analogwrite.rst b/source/lang/analogwrite.rst deleted file mode 100644 index 2c50a42..0000000 --- a/source/lang/analogwrite.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. highlight:: cpp - -.. _lang-analogwrite: - -analogWrite() -============= - -.. note:: - - On the Maple, calling analogWrite() is the same as calling - :ref:`lang-pwmwrite`\ ; see that function's documentation for more - information. - - This is because PWM is not true analog output (i.e., is not the - output of a `DAC - `_\ ), so - the function is badly named. For instance, **analogWrite() has - absolutely nothing to do with** :ref:`lang-analogread`\ , which is - potentially confusing. - - The alias of analogWrite() to pwmWrite() is provided (sigh) for the - sake of compatibility with Arduino, but we recommend using - :ref:`lang-pwmwrite` when writing new software, for clarity. - -.. contents:: Contents - :local: - -.. _lang-analogwrite-compatibility: - -Arduino Compatibility ---------------------- - -There are a few important differences between Arduino's `analogWrite() -`_ and Maple's -:ref:`lang-pwmwrite` that you should keep in mind. In each case, we -have some recommendations you can use to help converting from Arduino -to Maple. - -Difference 1: Duty cycle range is different -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The first and most important difference is that the largest possible -value for the duty cycle is much bigger on the Maple. Using Arduino's -analogWrite(), the duty cycle ranges between 0--255 (always off -- -always on)\ [#fbytemax]_\ . Using Maple's pwmWrite(), the duty cycle -ranges from 0--65,535 by default\ [#fuint16max]_\ . - -This is a good thing! The greater range of values on the Maple gives -you much more precise control over the duty cycle of your PWM output. - -If you're porting code from the Arduino and want a quick-and-dirty -fix, one solution is to :ref:`map ` the argument to -analogWrite into the right range:: - - // Arduino code: - analogWrite(pin, duty); - - // Becomes Maple code: - analogWrite(pin, map(duty, 0, 255, 0, 65535)); - -This will convert values in the range 0-255 to values in the range -0--65,635, which is the correct default range for all of the timers -which control PWM output. See the :ref:`timers reference ` -for more information. - -Another fix is to consult the :ref:`pin mapping mega table -` to find the timer which controls PWM on the -pin you're using, then set that Timer's overflow to 255. Subsequent -calls to analogWrite() should work as on the Arduino (with the same -loss of precision). Note, however, that that affects the overflow for -the **entire timer**, so other code relying on that timer (such as any -:ref:`interrupts ` the timer controls) will -likely need to be modified as well. - -Difference 2: You must use pinMode() to set up PWM -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The second difference is that on the Maple, you **must** set up the pin -for PWM output using :ref:`lang-pinmode`\ , with argument ``PWM``. -This should just be one extra line of code in your -:ref:`lang-setup` function. Example:: - - void setup() { - // set up pin 9 for PWM - pinMode(9, PWM); - } - -This also means that you can't later call :ref:`lang-digitalread` -or :ref:`lang-digitalwrite` on that pin (unless some time in -between, you use pinMode() to reconfigure that pin for ``INPUT`` or -``OUTPUT``; see the :ref:`lang-pinmode` page for more information). - -Difference 3: No PWM on pin 10 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, -9, 11, 12, and 14, or twelve pins in total. That is at least as -*many* PWM pins as any Arduino board, but there are differences in -*which* pins support it. - -* On **most Arduino boards** (those with the ATmega168 or ATmega328; - this includes the **Arduino Uno**), this function works on pins 3, - 5, 6, 9, 10, and 11, or six pins total. Note that these boards - support PWM on pin 10, while Maple does not. - -* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins - total. Note that this board supports PWM on pins 4, 10, and 13, - while the Maple does not. Maple supports PWM on pins 0, 1, and 14, - which the Mega does not, making the total number of pins supporting - PWM equal on these boards. - -* **Older Arduino boards** with an ATmega8 only support analogWrite() on - pins 9, 10, and 11. Maple does not support PWM on pin 10. - -In all cases, Arduino boards support PWM on pin 10, unlike Maple. We -did our best to make PWM as pin-compatible as possible; however, -circuit layout constraints prevented us from achieving perfect -compatibility. - -The "safest" pins to use for PWM output are pins 9 and 11. These pins -work on any Arduino board and on Maple. The "safe" pins, which work -on most recent Arduino boards, the Arduino Mega and the Maple, are -pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as -portable as possible between Maple and Arduino, we recommend using the -"safest" pins first, then the "safe" pins, as necessary. - -Difference 4: PWM frequency -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The frequency of the PWM signal (i.e., the frequency of a complete -on/off cycle) on the Arduino is approximately 490 Hz. - -On the Maple, the frequency is configurable, defaulting to about 1100 -Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of -the timer which controls PWM output on the particular pin (\ -:ref:`the PWM tutorial has the details `\ ). - -If your application absolutely requires Arduino's PWM frequency (it -probably doesn't), then the steps are: - -1. Figure out which timer controls PWM output on your pin (\ :ref:`this table ` is your friend here). Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4. - -2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of approximately 490 Hz. - -Be aware that this will change the period for the **entire timer**\ , -and will affect anything else in your program that depends on that -timer. One example is :ref:`interrupts `\ . -You've been :ref:`warned `\ . - -See also --------- - -- :ref:`Maple PWM tutorial ` - -.. rubric:: Footnotes - -.. [#fbytemax] This is because the value for the duty cycle on Arduino - must fit in 1 byte of memory, and an unsigned (i.e., nonnegative) - integer with size 1 byte can hold the values between 0 and 255. - -.. [#fuint16max] This is because the value for the duty cycle on the - Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) - integer with size 2 bytes can hold the values between 0 and 65,535. - - -.. include:: cc-attribution.txt diff --git a/source/lang/arithmetic.rst b/source/lang/arithmetic.rst deleted file mode 100644 index 91fe22e..0000000 --- a/source/lang/arithmetic.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. highlight:: cpp - -.. _lang-arithmetic: - -Arithmetic Operators (``+``, ``-``, ``*``, ``/``) -================================================= - -The operators ``+``, ``-``, ``*``, and ``/`` respectively evaluate to -the sum, difference, product, or quotient (respectively) of the two -operands. The operation is conducted using the data type of the -operands, so, for example, ``9 / 4`` gives ``2`` since 9 and 4 are -:ref:`int variables `. - -This also means that the operation can overflow if the result is -larger than that which can be stored in the data type (e.g. adding 1 -to an :ref:`lang-int` with the value 2,147,483,647 gives --2,147,483,648). - -.. _lang-arithmetic-typeconversion: - -If the operands are of different types, the "larger" type is used for -the calculation. If one of the numbers (operands) are of the type -**float** or of type **double**, floating point math will be used for -the calculation. - -.. note:: The specifics of these rules are beyond the scope of this - documentation; for more information, see `The C++ Programming - Language `_\ , by Bjarne - Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks - entry on C++ type conversion - `_. - -.. note:: For more information on how computers represent integers, - see the Wikipedia page on `two's complement - `_. - -.. contents:: Contents - :local: - -Examples --------- - - :: - - y = y + 3; - x = x - 7; - i = j * 6; - r = r / 5; - - -Syntax ------- - - :: - - result = value1 + value2; - result = value1 - value2; - result = value1 * value2; - result = value1 / value2; - - -Parameters ----------- - -**value1**: any numeric variable or constant - -**value2**: any numeric variable or constant - -Programming Tips ----------------- - -- Know that :ref:`integer constants ` - default to :ref:`int `, so some constant calculations - may overflow (e.g., 200000 * 5000000 will yield a negative result). - -- Choose variable sizes that are large enough to hold the largest - results from your calculations. - -- Know at what point your variable will "roll over" and also what - happens in the other direction e.g. (0 - 1) for unsigned arithmetic, - or (0 - -2,147,483,648) for signed arithmetic. - -- For math that requires fractions, float variables may be used, but - be aware of their drawbacks: large size and slow computation speeds - (the STM32 has no floating point hardware, so all floating point - calculations have to be done in software). - -- Use cast operator, e.g. ``(int)myFloat`` to convert one variable type - to another on the fly. - -Arduino Compatibility ---------------------- - -Since the STM32 processor on the Maple is a 32-bit machine, the int -type overflows at a much higher value on Maple than on Arduino. In -particular, on Maple, ints do not overflow (become negative) until -they reach 2,147,483,648; on the Arduino, they overflow at 32,767. -Because of this, programs running on Maple are much less likely to run -into overflow issues. The following table summarizes the sizes and -ranges of integer datatypes on the Maple (the ranges of long long -types are approximate): - -.. _lang-arithmetic-int-sizes: - -.. csv-table:: - :header: Datatype, Unsigned range, Signed range, Size (bytes) - :widths: 8, 12, 17, 8 - - ``char``, 0 --- 255, -128 --- 127, 1 - ``short``, "0 --- 65,535", "-32,768 --- 32,767", 2 - ``int``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 - ``long``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 - ``long long``, "0 --- 1.8*10\ :sup:`19`\ " (approx.), "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 - - -See Also --------- - -- The individual sizes (in bits) of various available types are - defined in `libmaple_types.h - `_\ - . - -- :ref:`sizeof `\ () - - -.. include:: cc-attribution.txt diff --git a/source/lang/array.rst b/source/lang/array.rst deleted file mode 100644 index 30a818f..0000000 --- a/source/lang/array.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. highlight:: cpp - -.. _lang-array: - -Arrays -====== - -An array is a collection of variables that are accessed with an index -number. Arrays in the C++ programming language, in which the Maple is -programmed, can be complicated, but using simple arrays is relatively -straightforward. - -.. contents:: Contents - :local: - -Creating (Declaring) an Array ------------------------------ - -All of the methods below are valid ways to create (declare) an -array. :: - - int myInts[6]; - int myPins[] = {2, 4, 8, 3, 6}; - int mySensVals[6] = {2, 4, -8, 3, 2}; - char message[6] = "hello"; - -You can declare an array without initializing it, as with myInts. In -the line referring to myPins, we declare an array without explicitly -choosing a size. The compiler counts the elements and creates an -array of the appropriate size. - -Finally, you can both initialize and size your array, as in -mySensVals. Note that when declaring an array with elements of type -char, one more element than your initialization is required, to hold -the required `null character `_. - - -Accessing an Array ------------------- - - -.. compound:: - - Arrays are **zero indexed**; that is, referring to the array - initialization above, the first element of the array is at index 0, - hence :: - - mySensVals[0] == 2; - mySensVals[1] == 4 - - and so forth. - -It also means that in an array with ten elements, index nine is the -last element. Hence:: - - int myArray[10]={9,3,2,4,3,2,7,8,9,11}; - // myArray[9] contains 11 - // myArray[10] is invalid and contains random information (other memory address) - -For this reason, you should be careful in accessing arrays. Accessing -past the end of an array (using an index number greater than your -declared array size - 1) is reading from memory that is in use for -other purposes. Reading from these locations is probably not going to -do much except yield invalid data. Writing to random memory locations -is definitely a bad idea, and can often lead to unhappy results such -as crashes or program malfunction. This can also be a difficult bug to -track down. - -Unlike Basic or Java, the C compiler does no checking to see if array -access is within legal bounds of the array size that you have -declared. - - -To assign a value to an array ------------------------------ - :: - - mySensVals[0] = 10; - - -To retrieve a value from an array ---------------------------------- - - :: - - x = mySensVals[4]; - - -Arrays and ``for`` Loops ------------------------- - -Arrays are often manipulated inside :ref:`for loops `, where -the loop counter is used as the index for each array element. For -example, to print the elements of an array over the serial port, you -could do something like this:: - - int i; - for (i = 0; i < 5; i = i + 1) { - SerialUSB.println(myPins[i]); - } - - -Example -------- - -For a complete program that demonstrates the use of arrays, see the -Arduino `Knight Rider example -`_\ (which will run -unmodified on the Maple). - -Arduino Compatibility ---------------------- - -Arrays on Maple are identical those on Arduino. - -See also --------- - -- :ref:`Storing arrays in FLASH memory ` - - - -.. include:: cc-attribution.txt diff --git a/source/lang/assignment.rst b/source/lang/assignment.rst deleted file mode 100644 index b6ad4d5..0000000 --- a/source/lang/assignment.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. highlight:: cpp - -.. _lang-assignment: - -Assignment Operator (``=``) -=========================== - -Stores the value to the right of the equal sign in the variable to -the left of the equal sign. - -The single equal sign in the C++ programming language is called the -assignment operator. It has a different meaning than in algebra -class, where it indicated an equation or equality. The assignment -operator tells the microcontroller to evaluate whatever value or -expression is on the right side of the equal sign, and store it in -the variable to the left of the equal sign [#fgross]_. - - - -Example -------- - -:: - - int sensVal; // declare an integer variable named sensVal - senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal - - - -Programming Tips ----------------- - -The variable on the left side of the assignment operator ( = sign ) -needs to be able to hold the value stored in it. If it is not large -enough to hold a value, the value stored in the variable will be -incorrect. - -Don't confuse the assignment operator [ = ] (single equal sign) -with the comparison operator [ == ] (double equal signs), which -evaluates whether two expressions are equal. - - -Arduino Compatibility ---------------------- - -Assignments on the Maple are identical to those on Arduino. - - - -See Also --------- - - -- `if (comparison operators) `_ -- `char `_ -- `int `_ -- `long `_ - - -.. rubric:: Footnotes - -.. [#fgross] Experienced C++ programmers know this to be an - oversimplification of what happens when the variable on the left - hand side is an object. See Richard Gillam's wonderful and scary - `The Anatomy of the Assignment Operator - `_ - for more information. - - -.. include:: cc-attribution.txt diff --git a/source/lang/attachinterrupt.rst b/source/lang/attachinterrupt.rst deleted file mode 100644 index 0b8907f..0000000 --- a/source/lang/attachinterrupt.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. highlight:: cpp - -.. _lang-attachinterrupt: - -attachInterrupt() -================= - -Used to specify a function to call when an external interrupt (like an -GPIO changing from LOW to HIGH, a button getting pressed, etc.) -occurs. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: attachInterrupt - -.. doxygenenum:: ExtIntTriggerMode - -.. doxygentypedef:: voidFuncPtr - -Discussion ----------- - -Because the function will run in interrupt context, inside of it, -:ref:`lang-delay` won't work, and the value returned by -:ref:`lang-millis` will not increment. Serial data received while -in the function may be lost. You should declare as ``volatile`` any -global variables that you modify within the attached function. - -There are a few constraints you should be aware of if you're using -more than one interrupt at a time; the :ref:`external-interrupts` page -has the details. - - -Using Interrupts ----------------- - -Interrupts are useful for making things happen automatically in -microcontroller programs, and can help solve timing problems. A -good task for using an interrupt might be reading a rotary encoder, -or monitoring user input. - - -If you wanted to insure that a program always caught the pulses -from a rotary encoder, never missing a pulse, it would make it very -tricky to write a program to do anything else, because the program -would need to constantly poll the sensor lines for the encoder, in -order to catch pulses when they occurred. Other sensors have a -similar interface dynamic too, such as trying to read a sound -sensor that is trying to catch a click, or an infrared slot sensor -(photo-interrupter) trying to catch a coin drop. In all of these -situations, using an interrupt can free the microcontroller to get -some other work done while not missing the doorbell. - - -Example -------- - -:: - - int maple_led_pin = 13; - volatile int state = LOW; // must declare volatile, since it's - // modified within the blink handler - - void setup() { - pinMode(maple_led_pin, OUTPUT); - attachInterrupt(0, blink, CHANGE); - } - - void loop() { - digitalWrite(maple_led_pin, state); - } - - void blink() { - state = !state; - } - - -Arduino Compatibility ---------------------- - -Most Arduino boards have two external interrupts: numbers 0 (on -digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an -additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 -(pin 18). On the Maple, you don't have to remember which interrupt -number goes with which pin -- just tell ``attachInterrupt()`` the pin -you want. - - -See also --------- - - -- :ref:`detachInterrupt ` -- :ref:`external-interrupts` - - - -.. include:: cc-attribution.txt diff --git a/source/lang/bit.rst b/source/lang/bit.rst deleted file mode 100644 index dd5c050..0000000 --- a/source/lang/bit.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _lang-bit: - -bit() -===== - -(Macro) Computes the value of an (unsigned) integer with the specified -bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8, -16, 32, etc.). - -Syntax ------- - -``bit(n)`` - - -Parameters ----------- - -* **n** the bit to set. - - -Value ------ - -The value of an integer with the given bit set. - - -Arduino Compatibility ---------------------- - -The Maple implementation of bit is compatible with Arduino. - - -See also --------- - - -- :ref:`lang-bitread` -- :ref:`lang-bitwrite` -- :ref:`lang-bitset` -- :ref:`lang-bitclear` - - -.. include:: cc-attribution.txt diff --git a/source/lang/bitclear.rst b/source/lang/bitclear.rst deleted file mode 100644 index 941f912..0000000 --- a/source/lang/bitclear.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _lang-bitclear: - -bitClear() -========== - -(Macro) Clears (writes a 0 to) a bit of a numeric variable. - -Syntax ------- - -``bitClear(x, n)`` - - -Parameters ----------- - -* **x** the numeric variable whose bit to clear - -* **n** which bit to clear, starting at 0 for the least-significant - (rightmost) bit - - -Returns -------- - -None. - - -Arduino Compatibility ---------------------- - -This implementation is compatible with that of Arduino. - - -See also --------- - -- :ref:`bit `\ () -- :ref:`bitRead `\ () -- :ref:`bitWrite `\ () -- :ref:`bitSet `\ () - - -.. include:: cc-attribution.txt diff --git a/source/lang/bitread.rst b/source/lang/bitread.rst deleted file mode 100644 index 46b4478..0000000 --- a/source/lang/bitread.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _lang-bitread: - -bitRead() -========= - -(Macro) Gets the value of a bit in a number. - - -Syntax ------- - -``bitRead(x, n)`` - - -Parameters ----------- - -* **x** the number from which to read the bit. - -* **n** which bit to read, starting at 0 for the least-significant - (rightmost) bit - - -Value ------ - -The value of the bit (0 or 1). - - -Arduino Compatibility ---------------------- - -The Maple implementation of ``bitRead`` is compatible with Arduino. - - -See also --------- - - -- :ref:`lang-bit` -- :ref:`lang-bitwrite` -- :ref:`lang-bitset` -- :ref:`lang-bitclear` - - -.. include:: cc-attribution.txt diff --git a/source/lang/bitset.rst b/source/lang/bitset.rst deleted file mode 100644 index ccd76de..0000000 --- a/source/lang/bitset.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _lang-bitset: - -bitSet() -======== - -(Macro) Sets (writes a 1 to) a bit of a numeric variable. - - -Syntax ------- - -``bitSet(x, n)`` - - -Parameters ----------- - -* **x** the numeric variable whose bit to set - -* **n** which bit to set, starting at 0 for the least-significant - (rightmost) bit - - -Value ------ - -None. - - -Arduino Compatibility ---------------------- - -The Maple implementation of bitSet is compatible with Arduino. - - -See Also --------- - -- :ref:`lang-bit` -- :ref:`lang-bitread` -- :ref:`lang-bitwrite` -- :ref:`lang-bitclear` - - - -.. include:: cc-attribution.txt diff --git a/source/lang/bitshift.rst b/source/lang/bitshift.rst deleted file mode 100644 index e1c8de0..0000000 --- a/source/lang/bitshift.rst +++ /dev/null @@ -1,144 +0,0 @@ -.. highlight:: cpp - -.. _lang-bitshift: - -Bit Shift Operators (``<<``, ``>>``) -==================================== - -(Adapted from `The Bit Math Tutorial -`_ in `The Arduino -Playground `_\ ) - -There are two bit shift operators in C++: the left shift operator -``<<`` and the right shift operator ``>>``. These operators cause the -bits in the left operand to be shifted left or right by the number of -positions specified by the right operand. - -More information on bitwise math can be obtained in the Wikipedia -article on `bitwise operations -`_\ , especially the -section on shifts in `C, C++, and Java -`_\ . - - -Syntax ------- - -``some_int << number_of_bits`` - -``some_int >> number_of_bits`` - - -Parameters ----------- - -* **some_int** An integer value or variable. - -* **number_of_bits** integer whose value is at most ``8 * - sizeof(variable)`` (so ``number_of_bits`` can be at most 32 for - ``int`` values, at most ``8`` for ``char`` values, etc.; the various - integer sizes are summarized :ref:`in this table - `\ ). - - - -Example: --------- - -Here are some examples of bit shifting, with the binary representation of the number in comments:: - - int a = 5; // binary: 101 - int b = a << 3; // binary: 101000, or 40 in decimal - int c = b >> 3; // binary: 101, or back to 5 like we started with - - -When you left shift a value x by y bits (x << y), the leftmost y bits -in x are lost, literally shifted out of existence. We'll do this -example with ``char`` values (which are integers in the range 0-255, -and take up 8 bits of memory):: - - char a = 5; // binary (all 8 bits): 00000101 - char b = a << 7; // binary: 10000000 - the first 1 in 101 was discarded - - -If you are certain that none of the ones in a value are being shifted -into oblivion, a simple way to think of the left-shift operator is -that it multiplies the left operand by 2 raised to the right operand -power (in math notation, ``x << y`` equals x * 2\ :sup:`y`\ , as long -as none of the bits of x get shifted out). For example, to generate -powers of 2, the following expressions can be employed:: - - 1 << 0 == 1 - 1 << 1 == 2 - 1 << 2 == 4 - 1 << 3 == 8 - ... - 1 << 8 == 256 - 1 << 9 == 512 - 1 << 10 == 1024 - ... - -.. _lang-bitshift-signbit-gotcha: - -When you shift x right by y bits (``x >> y``), and the highest bit in -x is a 1, the behavior depends on the exact data type of x. If x is of -type ``int``, the highest bit is special, and determines whether x is -negative or not; the details are too complicated to explain here, but -they are thoroughly explained in the Wikipedia article on `two's -complement arithmetic -`_\ , which the -system most computers use to store integers. In that case, the sign -bit is copied into lower bits, for esoteric historical reasons:: - - int x = -16; // binary (all 32 bits): 11111111111111111111111111110000 - int y = x >> 3; // binary: 11111111111111111111111111111110 - - - -This behavior, called "sign extension", is often not what you -want. You probably wish zeros to be shifted in from the left. It -turns out that the right shift rules are different for ``unsigned -int`` values, so you can use a type cast to suppress ones being copied -from the left:: - - int x = -16; // binary: 11111111111111111111111111110000 - int y = (unsigned int)x >> 3; // binary: 00011111111111111111111111111110 - - - -If you are careful to avoid sign extension, you can use the -right-shift operator, ``>>``, as a way to divide by powers of 2. For -example:: - - int x = 1000; - int y = x >> 3; // integer division of 1000 by 8, causing y = 125. - - -Arduino Compatibility ---------------------- - -Since it's part of the C++ language, bit shifting on the Maple is -compatible with the Arduino; however, you should keep in mind that the -Maple has bigger integer types (as in, more bits) than the Arduino. - -Since the STM32 is a 32-bit processor, the ``int`` type takes up 32 -bits instead of 16, like on Arduino's 16-bit microcontroller. This -means that you can shift left, like ``x << y``, with bigger values of -``y`` on the Maple before ones in ``x`` start to get shifted out. - -To calculate the number of bits of an integer type on the Maple, -multiply its size in bytes (see :ref:`this table -` for these) by 8, since there are 8 -bits in 1 byte. For example, a ``short`` takes up 2 bytes of memory, -or 2 * 8 = 16 bits. - -See Also --------- - -- :ref:`lang-bit` -- :ref:`lang-bitread` -- :ref:`lang-bitwrite` -- :ref:`lang-bitclear` - - -.. include:: cc-attribution.txt diff --git a/source/lang/bitwisemath.rst b/source/lang/bitwisemath.rst deleted file mode 100644 index 28fe6bf..0000000 --- a/source/lang/bitwisemath.rst +++ /dev/null @@ -1,186 +0,0 @@ -.. highlight:: cpp - -.. _lang-bitwisemath: - -Bitwise Operators (``&``, ``|``, ``^``, ``~``) -============================================== - -The bitwise operators perform their calculations at the bit level of -variables. They help solve a wide range of common programming -problems. - -Much of the material here is adapted for Maple from an (Arduino) -`tutorial on bitwise math -`_\ . Another great -resource is the Wikipedia article on `bitwise operations -`_\ . - -Below are descriptions and syntax for all of the operators. - -.. contents:: Contents - :local: - -.. _lang-bitwisemath-and: - -Bitwise AND (``&``) -------------------- - -The bitwise AND operator in C++ is a single ampersand, ``&``, used -between two other integer expressions. Bitwise AND operates on each -bit position of the surrounding expressions independently, according -to this rule: if both input bits are 1, the resulting output is 1, -otherwise the output is 0. Another way of expressing this is:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 0 0 1 (operand1 & operand2) = result - - -On the Maple, the type ``int`` is a 32-bit value, so using ``&`` -between two ``int`` expressions causes 32 simultaneous AND operations -to occur. In a code fragment like:: - - int a = 92; // in binary: 00000000000000000000000001011100 - int b = 101; // in binary: 00000000000000000000000001100101 - int c = a & b; // result: 00000000000000000000000001000100, - // (or 68 in decimal). - - -Each of the 32 bits in ``a`` and ``b`` are processed using bitwise -AND, and all 32 resulting bits are stored in ``c``, resulting in the -value 1000100 in binary, which is 68 in decimal. - - -.. _lang-bitwisemath-or: - -Bitwise OR (``|``) ------------------- - -The bitwise OR operator in C++ is the vertical bar symbol, ``|``. Like -the ``&`` operator, ``|`` operates independently on each bit in its -two surrounding integer expressions, but what it does is -different. The bitwise OR of two bits is 1 if either or both of the -input bits is 1, otherwise it is 0. For example:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) = result - -Here is an example of bitwise OR used in a snippet of C++ code (using -``char``, which takes up 8 bits of memory, instead of ``int``, which -uses 32):: - - char a = 92; // in binary: 01011100 - char b = 101; // in binary: 01100101 - char c = a | b; // result: 01111101, or 125 in decimal. - -.. _lang-bitwisemath-xor: - -Bitwise XOR (``^``) -------------------- - -There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE -OR, also known as bitwise XOR. (In English, this is usually pronounced -"zor" or "ex-or"). The bitwise XOR operator is written using the caret -symbol, ``^``. This operator is very similar to the bitwise OR -operator ``|``, except it evaluates to 0 for a given bit position when -both of the input bits for that position are 1:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 0 (operand1 ^ operand2) = result - - -Another way to look at bitwise XOR is that each bit in the result -is a 1 if the input bits are different, or 0 if they are the same. - -Here is a simple example:: - - int x = 12; // binary (ignoring extra bits): 1100 - int y = 10; // binary: 1010 - int z = x ^ y; // binary: 0110, or decimal 6 - - - -The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 -to 0) some of the bits in an integer expression. In a bitwise OR -operation if there is a 1 in the mask bit, that bit is inverted; if -there is a 0, the bit is not inverted and stays the same. Below is a -program to blink digital pin 13 (the LED pin on Maple):: - - // Blink Maple LED pin - - int led_pin = 13; - int toggle = 0; - - // demo for Exclusive OR - void setup(){ - pinMode(led_pin, OUTPUT); - } - - void loop(){ - toggle = toggle ^ 1; - digitalWrite(led_pin, toggle); - delay(100); - } - -.. _lang-bitwisemath-not: - -Bitwise NOT (``~``) -------------------- - -The bitwise NOT operator in C++ is the tilde character ``~``. Unlike -``&`` and ``|``, the bitwise NOT operator is applied to a single -operand to its right. Bitwise NOT changes each bit to its opposite: 0 -becomes 1, and 1 becomes 0. For example:: - - 0 1 operand1 - ---- - 1 0 ~operand1 = result - -Another example:: - - char a = 103; // binary: 01100111 - char b = ~a; // binary: 10011000 = -104 - -You might be surprised to see a negative number like -104 as the -result of this operation. This is because the highest bit in an int -variable is the so-called "sign bit". If the highest bit is 1, the -number is interpreted as negative. This encoding of positive and -negative numbers is referred to as *two's complement*. For more -information, see the Wikipedia article on `two's -complement. `_ - -As an aside, it is interesting to note that (under two's complement -arithmetic) for any integer ``x``, ``~x`` is the same as ``-x-1``. - -At times, the sign bit in a signed integer expression can cause -some unwanted surprises. - - -Uses ----- - -One of the most common uses of bitwise operations is to select or -manipulate a particular bit (or bits) from an integer value, often -called `bit masking -`_\ . See the -linked Wikipedia article for more information and examples. - -If you really want to see bit-twiddling techniques in their full -glory, you could do much worse than to get yourself a copy of -`Hacker's Delight `_\ . - - -See Also --------- - -- :ref:`Boolean operations ` (``&&``, ``||``) -- :ref:`Compound bitwise operations ` (``&=``, - ``|=``, ``^=``). - - -.. include:: cc-attribution.txt diff --git a/source/lang/bitwrite.rst b/source/lang/bitwrite.rst deleted file mode 100644 index b3feff2..0000000 --- a/source/lang/bitwrite.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. highlight:: cpp - -.. _lang-bitwrite: - -bitWrite() -========== - -(Macro) Writes a bit of a numeric variable. - -Syntax ------- - -:: - - bitWrite(x, n, b) - -Parameters ----------- - -**x**: the numeric variable whose bit to write. - -**n**: which bit of the number to write, starting at 0 for the -least-significant (rightmost) bit. - -**b**: the value to write to the bit (0 or 1). - -Returns -------- - -Nothing. - -Arduino Compatibility ---------------------- - -Maple's version of ``bitWrite()`` is compatible with Arduino. - -See also --------- - -- :ref:`bit() ` -- :ref:`bitRead() ` -- :ref:`bitSet() ` -- :ref:`bitClear() ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/boolean.rst b/source/lang/boolean.rst deleted file mode 100644 index 8d6aa5c..0000000 --- a/source/lang/boolean.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. highlight:: cpp - -.. _lang-boolean: - -Boolean Operators -================= - -These can be used inside the condition of an :ref:`if ` -statement. Evaluate to :ref:`true ` or -:ref:`false `. - -.. contents:: Contents - :local: - -.. _lang-boolean-and: - -&& (logical and) ----------------- - -True only if both operands are true. For example:: - - if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches - // ... - } - -is true only if both inputs are high. Another example:: - - if (a >= 10 && a <= 20){} // true if a is between 10 and 20 - -**Be careful** not to say ``10 <= a <= 20``! This won't work the way -you want. You have to separately test whether ``a`` is at least 10 -using ``a >= 10``, then test whether ``a`` is at most 20 using ``a <= -20``, then combine the results using ``&&``. - - -.. _lang-boolean-or: - -\|\| (logical or) ------------------ - -True if either operand is true. For example:: - - if (x > 0 || y > 0) { - // ... - } - -is true if either ``x`` or ``y`` is greater than 0. - -.. _lang-boolean-not: - -! (logical not) ---------------- - -True if the operand is false. For example:: - - if (!x) { - // ... - } - -is true if ``x`` is false (i.e. if ``x`` is zero). - -Some Advice ------------ - -.. warning:: - - Make sure you don't mistake the boolean AND operator ``&&`` - (double ampersand) for the :ref:`bitwise AND operator - ` ``&`` (single ampersand). They are - entirely different beasts. - - Similarly, do not confuse the boolean OR operator ``||`` (double - pipe) with the :ref:`bitwise OR operator ` - ``|`` (single pipe). - - The :ref:`bitwise NOT operator ` ``~`` - (tilde) looks much different than the boolean not operator ``!`` - (exclamation point, or "bang", as some programmers say), but you - still have to be sure which one you want. - - -See Also --------- - -- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) -- :ref:`Compound bitwise operators ` (``&=``, - ``|=``, ``^=``). -- :ref:`if statement ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/booleanvariables.rst b/source/lang/booleanvariables.rst deleted file mode 100644 index 6051b8c..0000000 --- a/source/lang/booleanvariables.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. highlight:: cpp - -.. _lang-booleanvariables: - -Booleans -======== - -A **boolean** holds one of two values, :ref:`true -` or :ref:`false `. On a -Maple, each boolean variable has type ``bool``. - -.. warning:: - - On an Arduino, the type ``boolean`` is also provided. While the - Maple also has this type for compatibility, **its use is strongly - discouraged**. The ``bool`` type is a standard part of C++, while - ``boolean`` is a non-standard extension that serves no purpose. - -Example -------- - -:: - - int ledPin = 13; // LED on pin 13 - int switchPin = 12; // momentary switch on 12, other side connected to ground - - // running is a boolean variable: - bool running = false; - - void setup() { - pinMode(ledPin, OUTPUT); - pinMode(switchPin, INPUT); - digitalWrite(switchPin, HIGH); // turn on pullup resistor - } - - void loop() { - if (digitalRead(switchPin) == LOW) { - // switch is pressed - pullup keeps pin high normally - delay(100); // delay to debounce switch - running = !running; // toggle running variable - digitalWrite(ledPin, running) // indicate via LED - } - } - -See also --------- - - -- :ref:`Boolean constants ` -- :ref:`Boolean operators ` -- :ref:`Variables ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/break.rst b/source/lang/break.rst deleted file mode 100644 index ce8ac17..0000000 --- a/source/lang/break.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. highlight:: cpp - -.. _lang-break: - -``break`` -========= - -``break`` is used to exit from a :ref:`while `\ , -:ref:`for `\ , or :ref:`do/while ` loop, -bypassing the normal loop condition. It is also used to exit from a -:ref:`switch ` statement. - - -Example -------- - -:: - - for (x = 0; x < 255; x ++) - { - digitalWrite(PWMpin, x); - sens = analogRead(sensorPin); - if (sens > threshold){ // bail out on sensor detect - x = 0; - // this line of code means that we'll immediately exit - // from the "for" loop: - break; - } - delay(50); - } - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/byte.rst b/source/lang/byte.rst deleted file mode 100644 index 45c9d5f..0000000 --- a/source/lang/byte.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. highlight:: cpp - -.. _lang-byte: - -byte -==== - -The ``byte`` type stores a 1-byte (8-bit) unsigned integer number, -from 0 to 255. - -.. warning:: - - The ``byte`` type is provided for compatibility with Arduino. - However, it is a non-standard extension. The standard C++ type for - storing an 8-bit unsigned integer is ``unsigned char``; we - recommend using that instead. (Your code will still work on an - Arduino). - - -Example -------- - -:: - - byte b = 134; - -See Also --------- - -- :ref:`byte() ` (casting a value to a byte) -- :ref:`Variables ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/bytecast.rst b/source/lang/bytecast.rst deleted file mode 100644 index b3f0de2..0000000 --- a/source/lang/bytecast.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. highlight:: cpp - -.. _lang-bytecast: - -byte() (cast) -============= - -Converts a value to the :ref:`byte ` data type. - -.. note:: - - Casting to the byte type is provided for compatibility with - Arduino. However, the recommended Maple type for storing an 8-bit - unsigned integer is ``uint8``. (C and C++ programmers: ``stdint.h`` - is also available). - - In order to cast a variable ``x`` to a ``uint8``, the - following syntax can be used:: - - uint8(x); - -Syntax ------- - -``byte(x)`` - - -Parameters ----------- - -**x**: a value of any integer type - - -Returns -------- - -The value, converted to a ``byte``. Note, however, that if the value -is larger than the maximum value you can store in a byte (255), then -the results might be strange and unexpected. - - -See Also --------- - -- :ref:`lang-byte` - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/char.rst b/source/lang/char.rst deleted file mode 100644 index b8747f3..0000000 --- a/source/lang/char.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. highlight:: cpp - -.. _lang-char: - -``char`` -======== - -The ``char`` type stores a 1-byte character value (or integer with -value from -128 to 127). Character literals are written in single -quotes, like this: ``'A'`` (for multiple characters - strings - use -double quotes: ``"ABC"``). - - -Just like everything else on a computer, characters are stored as -numbers. You can see the specific encoding in the `ASCII chart -`_\ -. This means that it is possible to do arithmetic on characters, in -which the ASCII value of the character is used (e.g. ``'A' + 1`` has the -decimal value 66, since the ASCII value of the capital letter A in -decimal is 65). See the :ref:`Serial.println() -` documentation for more information about how -characters are converted into numbers. - -The ``char`` datatype is a signed type, meaning that it encodes -numbers from -128 to 127. For an unsigned type, which stores values -from 0 to 255, just use the type ``unsigned char`` (two words). - - -Example -------- - -:: - - // the following two lines are equivalent, using the ASCII - // character encoding: - char c = 'A'; - char c = 65; - - -See also --------- - - -- :ref:`lang-int` -- :ref:`lang-array` (a string is just an array of ``char``\ s) -- :ref:`Serial.println() ` - - - -.. include:: cc-attribution.txt diff --git a/source/lang/charcast.rst b/source/lang/charcast.rst deleted file mode 100644 index a480dec..0000000 --- a/source/lang/charcast.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. highlight:: cpp - -.. _lang-charcast: - -``char()`` (cast) -================= - -Converts a value to the :ref:`char ` data type. - -Syntax ------- - -``char(x)`` - - -Parameters ----------- - -**x**: a value of any type - - -Returns -------- - -The value, converted to a ``char``. Note, however, that if the value -is outside the range of a ``char`` (-128 to 127), then the results -might be strange and unexpected. - - -See Also --------- - -- :ref:`char ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/comments.rst b/source/lang/comments.rst deleted file mode 100644 index c5f118a..0000000 --- a/source/lang/comments.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. highlight:: cpp - -.. _lang-comments: - -Comments -======== - -Comments are lines in the program that are used to inform yourself or -others about the way the program works. They are ignored by the -compiler, and not exported to the processor, so they don't take up any -space in RAM or Flash. - -One use for comments is to help you understand (or remember) how your -program works, or to inform others how your program works. There are -two different ways of making comments. - -.. _lang-comments-singleline: - -**Single line comment**: Anything following two slashes, ``//``, until -the end of the line, is a comment:: - - x = 5; // the rest of this line is a comment - -.. _lang-comments-multiline: - -**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` -is a comment:: - - /* <-- a slash-star begins a multi-line comment - - all of this in the multi-line comment - you can use it to comment - out whole blocks of code - - if (gwb == 0){ // single line comment is OK inside a multi-line comment - x = 3; - } - - // don't forget the "closing" star-slash - they have to be balanced: - */ - -Note that it's okay to use single-line comments within a multi-line -comment, but you can't use multi-line comments within a multi-line -comment. Here's an example:: - - /* ok, i started a multi-line comment - - x = 3; /* this next star-slash ENDS the multi-line comment: */ - - x = 4; // this line is outside of the multi-line comment - - // next line is also outside of the comment, and causes a compile error: - */ - -Programming Tip ---------------- - -When experimenting with code, "commenting out" parts of your program -is a convenient way to remove lines that may be buggy. This leaves -the lines in the code, but turns them into comments, so the compiler -just ignores them. This can be especially useful when trying to locate -a problem, or when a program refuses to compile and the compiler error -is cryptic or unhelpful. - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/comparison.rst b/source/lang/comparison.rst deleted file mode 100644 index b24355f..0000000 --- a/source/lang/comparison.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. highlight:: cpp - -.. _lang-comparison: - -Comparison Operators (``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``) -=================================================================== - -The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and -``>=`` are used to compare two numbers. They are :ref:`true -` when the comparison is true, and :ref:`false -` otherwise. They are based on the symbols -=, ≠, <, >, ≤, and ≥ from mathematics. - -Here are some examples, with their meaning in comments:: - - // "eq" is true when x is equal to y - bool eq = (x == y); - - // "neq" is true when x is different than y - bool neq = (x != y); - - // "lt" is true when x is less than, but NOT equal to, y - bool lt = (x < y); - - // "gt" is true when x is greater than, but NOT equal to, y - bool gt = (x > y); - - // "lte" is true when x is less than or equal to y - bool lte = (x <= y); - - // "gte" is true when x is greater than or equal to y - bool gte = (x >= y); - -The parentheses are optional; they are present only for clarity. For -example, the following two lines are the same:: - - bool eq = x == y; - - bool eq = (x == y); - -Uses ----- - -Comparison operators, along with :ref:`boolean operators -`, are useful inside the conditionals of :ref:`if -` statements. Here's one example:: - - if (x < 50) { - // only execute these lines if x is less than 50 - SerialUSB.println("delaying:"); - SerialUSB.println(x); - delay(x); - } - -.. warning:: - Beware of accidentally using the single equal sign (``=``) when you - meant to test if two numbers are equal (``==``). This is a common - mistake inside of ``if`` statement conditionals, e.g.:: - - // DON'T MAKE THIS MISTAKE - if (x = 10) { - // body - } - - The single equal sign is the assignment operator, and sets x to 10 - (puts the value 10 into the variable x). Instead use the double equal - sign (e.g. ``if (x == 10)``), which is the comparison operator, and - tests *whether* x is equal to 10 or not. The latter statement is only - true if x equals 10, but the former statement will always be true. - - This is because C evaluates the statement ``if (x=10)`` as follows: 10 - is assigned to x (remember that the single equal sign is the - :ref:`assignment operator `), so x now - contains 10. Then the 'if' conditional evaluates 10, which evaluates - to :ref:`true `, since any non-zero number - evaluates to ``true``. - - Consequently, the conditional of an ``if`` statement like ``if (x = - 10) {...}`` will always evaluate to ``true``, and the variable x - will be set to 10, which is probably not what you meant. - - (This sometimes has uses, though, so just because an assignment - appears within a conditional doesn't mean it's automatically wrong. - Be careful to know what you mean.) - - -.. include:: cc-attribution.txt diff --git a/source/lang/compoundarithmetic.rst b/source/lang/compoundarithmetic.rst deleted file mode 100644 index 420f1db..0000000 --- a/source/lang/compoundarithmetic.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. highlight:: cpp - -.. _lang-compoundarithmetic: - -Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) -=============================================================== - -These oparators perform a mathematical operation on a variable with -another constant or variable. These operators are just a convenient -shorthand:: - - x += y; // equivalent to the expression x = x + y; - x -= y; // equivalent to the expression x = x - y; - x *= y; // equivalent to the expression x = x * y; - x /= y; // equivalent to the expression x = x / y; - -Here is an example:: - - int x = 2; - int y = 10; - - x += 4; // x now contains 6 - x -= 3; // x now contains 3 - x *= y; // x now contains 30 - x /= 2; // x now contains 15 - x += max(20, 6); // x now contains 35 - x -= sq(5); // x now contains 15 - -Parameters ----------- - -**x**: a numeric variable - -**y**: a numeric variable, number constant, or any other expression -that evaluates to a number (e.g. call to a function that returns a -number). - -See Also --------- - -- :ref:`Arithmetic operators ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/compoundbitwise.rst b/source/lang/compoundbitwise.rst deleted file mode 100644 index a4bbb24..0000000 --- a/source/lang/compoundbitwise.rst +++ /dev/null @@ -1,231 +0,0 @@ -.. highlight:: cpp - -.. _lang-compoundbitwise: - -Compound Bitwise Operators (``&=``, ``|=``, ``^=``) -=================================================== - -The compound bitwise operators perform their calculations at the -bit level of variables. They are often used to clear and set -specific bits of a variable. - -See the :ref:`bitwise math tutorial ` for more -information on bitwise operators. - -.. contents:: Contents - :local: - -.. _lang-compoundbitwise-and: - -Compound bitwise AND (``&=``) ------------------------------ - -The compound bitwise AND operator ``&=`` is often used with a variable -and a constant to force particular bits in a variable to be zero. This -is often referred to in programming guides as "clearing" or -"resetting" bits. In a program, writing the line ``x &= y;`` is -equivalent to writing ``x = x & y;``. That is, the value of ``x`` -after the line will be equal to its old value bitwise ANDed with the -value of ``y``:: - - x &= y; // equivalent to x = x & y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any :ref:`integer value -` (like ``3`` or ``0x20``) for ``y``. - -Before doing an example of ``&=``, let's first review the Bitwise AND -(``&``) operator:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 0 0 1 (operand1 & operand2) = result - -As shown above, bits that are "bitwise ANDed" with 0 become 0, while -bits that are "bitwise ANDed" with 1 are left unchanged. So, if ``b`` -is a ``byte`` variable, then ``b & B00000000`` equals zero, and ``b & -B11111111`` equals ``b``. - -.. _lang-compoundbitwise-binconst: - -.. note:: The above uses :ref:`binary constants - `\ . The numbers are still the same - value in other representations, they just might not be as easy to - understand. - - Normally, in C and C++ code, :ref:`hexadecimal - ` or :ref:`octal - ` are used when we're interested in - an integer's bits, rather than its value as a number. - - While hexadecimal and octal literals might be harder to understand - at first, you should really take the time to learn them. They're - part of C, C++, and many other programming languages, while binary - constants are available only for compatibility with Arduino. - - Also, ``B00000000`` is shown for clarity, but zero in any number - format is zero. - -So, to clear (set to zero) bits 0 and 1 of a one-byte variable, while -leaving the rest of the variable's bits unchanged, use the compound -bitwise AND operator ``&=`` with the constant ``B11111100`` -(hexadecimal ``0xFC``\ ):: - - 1 0 1 0 1 0 1 0 variable - 1 1 1 1 1 1 0 0 mask - ---------------------- - 1 0 1 0 1 0 0 0 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged cleared - - -Here is the same representation with the variable's bits replaced -with the symbol ``x``\ :: - - x x x x x x x x variable - 1 1 1 1 1 1 0 0 mask - ---------------------- - x x x x x x 0 0 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged cleared - - -So, using a byte variable ``b``\ , if we say:: - - b = B10101010; // B10101010 == 0xAA - b &= B11111100; // B11111100 == 0xFC - -then we will have :: - - b == B10101000; // B10101000 == 0xA8 - -.. _lang-compoundbitwise-or: - -Compound bitwise OR (``|=``) ----------------------------- - -The compound bitwise OR operator ``|=`` is often used with a variable -and a constant to "set" (set to 1) particular bits in a variable. In -a program, writing the line ``x |= y;`` is equivalent to writing ``x = -x | y;``. That is, the value of ``x`` after the line will be equal to -its old value bitwise ORed with the value of ``y``:: - - x |= y; // equivalent to x = x | y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`compound bitwise AND -`\ , ``&=``). - -Before doing an example of ``|=``, let's first review the Bitwise OR -(``|``) operator:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) = result - -Bits that are "bitwise ORed" with 0 are unchanged, while bits that are -"bitwise ORed" with 1 are set to 1. So if ``b`` is a ``byte`` -variable, then ``b | B00000000`` equals ``b``, and ``b & B11111111`` -equals ``B11111111`` (here we've used binary constants; see the -:ref:`note ` above). - -So, to set bits 0 and 1 of a one-byte variable, while leaving the rest -of the variable unchanged, use the compound bitwise OR operator -(``|=``) with the constant ``B00000011`` (hexadecimal ``0x3``):: - - 1 0 1 0 1 0 1 0 variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - 1 0 1 0 1 0 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged set - -Here is the same representation with the variable's bits replaced with -the symbol ``x``:: - - x x x x x x x x variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - x x x x x x 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged set - -So, using a byte variable ``b``, if we say:: - - b = B10101010; // B10101010 == 0xAA - b |= B00000011; // B00000011 == 0x3 - -then we will have :: - - b == B10101011; // B10101011 == 0xAB - -.. _lang-compoundbitwise-xor: - -Compound bitwise XOR (``^=``) ------------------------------ - -The compound bitwise XOR operator ``^=`` is used with a variable and a -constant to "toggle" (change 0 to 1, and 1 to 0) particular bits in a -variable. In a program, writing the line ``x ^= y;`` is equivalent to -writing ``x = x ^ y;``. That is, the value of ``x`` after the line -will be equal to its old value bitwise XORed with the value of ``y``:: - - x ^= y; // equivalent to x = x ^ y; - -You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`&= -` and :ref:`\|= -`; in fact, these three operators all -work the same in this way). - -Before doing an example of ``^=``, let's first review the Bitwise -XOR operator, ``^``:: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 0 (operand1 ^ operand2) = result - -One way to look at bitwise XOR is that each bit in the result is a 1 -if the input bits are different, or 0 if they are the same. Another -way to think about it is that the result bit will be 1 when *exactly* -one (no more, no less) of the input bits is 1; otherwise, it will be -zero. This means that if you XOR a bit with 1, it will change (or -toggle) its value, while if you XOR a bit with 0, it stays the same. - -So, to toggle bits 0 and 1 of a one-byte variable, while leaving the -rest of the variable unchanged, use the compound bitwise XOR operator -``^=`` with the constant ``B00000011`` (hexadecimal ``0x3``\ ; see -:ref:`note ` above):: - - 1 0 1 0 1 0 1 0 variable - 0 0 0 0 0 0 1 1 mask - ---------------------- - 1 0 1 0 1 0 1 1 - ^^^^^^^^^^^^^^^^ ^^^^ - unchanged toggled - -So, using a byte variable ``b``, if we say:: - - b = B10101010; // B10101010 == 0xAA - b ^= B00000011; // B00000011 == 0x3 - -then we will have :: - - b == B10101001; // B10101001 == 0xA9 - -See Also --------- - -- :ref:`Boolean operations ` (``&&``, ``||``) -- :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) - - -.. include:: cc-attribution.txt diff --git a/source/lang/const.rst b/source/lang/const.rst deleted file mode 100644 index 52de85f..0000000 --- a/source/lang/const.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _lang-const: - -``const`` -========= - -The ``const`` keyword stands for "constant". It is a variable -*qualifier* that modifies the behavior of the variable, making a -variable "*read-only*". This means that the variable can be used just -as any other variable of its type, but its value cannot be -changed. You will get a compiler error if you try to assign a value to -a ``const`` variable. - -Constants defined with the ``const`` keyword obey the same rules of -:ref:`variable scoping ` that govern other -variables. This, and the pitfalls of using :ref:`#define -`, often makes using the ``const`` keyword a superior -method for defining constants than ``#define``. - -Example -------- - -:: - - // this defines a variable called "pi", which cannot be changed: - const float pi = 3.14; - float x; - - // .... - - x = pi * 2; // it's fine to find the value of a const variable - - pi = 7; // illegal - you can't write to (modify) a constant - - -**#define** or **const** ------------------------- - -You can use either ``const`` or ``#define`` for creating numeric or -string constants. For :ref:`arrays `\ , you will need -to use ``const``. In general, ``const`` is preferred over ``#define`` -for defining constants. - -See Also --------- - -- :ref:`#define ` -- :ref:`volatile ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/constants.rst b/source/lang/constants.rst deleted file mode 100644 index bc5c894..0000000 --- a/source/lang/constants.rst +++ /dev/null @@ -1,304 +0,0 @@ -.. _lang-constants: - -Constants -========= - -Constants are like predefined variables, whose values can't -change. They are used to make the programs easier to read and modify. -This page describes the most commonly used constants. - -.. contents:: Contents - :local: - -.. _lang-constants-bool: - -Boolean Constants ------------------ - -There are two constants used to represent truth and falsity: ``true``, -and ``false``. - -.. _lang-constants-false: - -false -^^^^^ - -``false`` is the false ``bool`` value. An integer which is 0 evaluates -to ``false`` as a boolean. - -.. _lang-constants-true: - -true -^^^^ - -``true`` is the true ``bool`` value. As an integer, ``true`` is often -said to be 1. This is correct in the sense that ``true`` evaluates to -1 as an integer. However, any integer which is *non-zero* is ``true`` -as a :ref:`bool `. So -1, 2 and -200 are all -"true", in the sense that these numbers are treated the same as -``true`` in a boolean context. - -Note that the ``true`` and ``false`` constants are typed in lowercase; -unlike e.g. ``HIGH``, ``LOW``, ``INPUT``, and ``OUTPUT`` (which are -described below). - - -Pin Levels: HIGH and LOW ------------------------- - -When reading or writing to a digital pin there are only two possible -values a pin can be set to: ``HIGH`` and ``LOW``. - -.. _lang-constants-high: - -HIGH -^^^^ - -The meaning of ``HIGH`` (in reference to a pin) is somewhat different -depending on whether the pin is set to ``INPUT`` or ``OUTPUT``. When a -pin is configured as an ``INPUT`` (using :ref:`pinMode() -`), and read with :ref:`digitalRead() -`, the microcontroller will report ``HIGH`` if a -voltage of 3 volts or more is present at the pin. - -.. TODO? Following seems false; check it out sometime, leave out for now: - -.. A pin may also be configured as an ``INPUT`` with ``pinMode()``, and -.. subsequently made ``HIGH`` with :ref:`digitalWrite() -.. `, this will set the internal pullup resistors, -.. which will *steer* the input pin to a HIGH reading unless it is pulled -.. LOW by external circuitry. - -When a pin is configured to ``OUTPUT`` with pinMode, and set to -``HIGH`` with :ref:`digitalWrite() `, the pin is at -3.3 volts. In this state it can *source* current, e.g. light an LED -that is connected through a series resistor to ground, or to another -pin configured as an output and set to ``LOW``. - -.. _lang-constants-low: - -LOW -^^^ - -The meaning of ``LOW`` also has a different meaning depending on -whether a pin is set to ``INPUT`` or ``OUTPUT``. When a pin is -configured as an ``INPUT`` with :ref:`pinMode() `, and -read with :ref:`digitalRead() `, the microcontroller -will report ``LOW`` if a voltage of 2 volts or less is present at the -pin. - -When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to -``LOW`` with :ref:`digitalWrite() `, the -microcontroller will attempt to keep that pin's voltage at 0V. In this -state it can *sink* current, e.g. light an LED that is connected -through a series resistor to +3.3V, or to another pin configured as an -output, and set to ``HIGH``. - -Pin Modes ---------- - -Digital pins can be used in a variety of modes. The basic modes, -``INPUT`` and ``OUTPUT``, have been introduced above. Changing a pin -from ``INPUT`` TO ``OUTPUT`` with :ref:`pinMode() ` -drastically changes the electrical behavior of the pin. - -This section describes the basic digital pin modes (``INPUT`` and -``OUTPUT``) only. For a detailed description of all possible pin -modes, see the :ref:`pinMode() ` reference page. - -.. _lang-constants-input: - -INPUT -^^^^^ - -Maple (STM32) pins configured as ``INPUT`` are said to be in a -high-impedance state. One way of explaining this is that pins -configured as ``INPUT`` make extremely small demands on the circuit -that they are sampling. This makes them useful for reading a sensor, -but not powering an LED. - -.. _lang-constants-output: - -OUTPUT -^^^^^^ - -Pins configured as ``OUTPUT`` with :ref:`pinMode() ` are -said to be in a low-impedance state. This means that they can provide -a substantial amount of current to other circuits. STM32 pins can -source (provide positive current) or sink (provide negative current) -up to 50 mA (milliamps) of current to other devices/circuits. This -makes them useful for powering LEDs, but useless for reading sensors. - -Pins configured as outputs can also be damaged or destroyed if short -circuited to either ground or 3.3V power rails. The amount of current -provided by an STM32 pin is also not enough to power most relays or -motors, and some interface circuitry will be required. - -.. _lang-constants-integers: - -Integer Constants ------------------ - -Integer constants (or more properly speaking, integer *literals*) are -numbers used directly in a sketch, like ``123``. By default, an -integer literal is treated as a (signed) :ref:`int `, but -you can change this with the U and L modifiers (see :ref:`below -`). You can specify negative numbers by -putting a minus sign in front, like ``-123``. - -Normally, integer literals are treated as base 10 (decimal) integers, -but special notation (formatters) may be used to enter numbers in -other bases. These are summarized in the following table: - -.. list-table:: - :header-rows: 1 - - * - Base - - Example - - Formatter - - Comment - - * - 10 (decimal) - - ``123`` - - None - - - - * - 2 (binary) - - ``0b1111011`` - - Leading "0b" - - GCC extension; not standard C++ - - * - 8 (octal) - - ``0173`` - - Leading "0" - - Characters 0-7 valid - - * - 16 (hexadecimal) - - ``0x7B`` - - Leading "0x" - - Characters 0-9, A-F (or a-f) valid - -Binary constants (like ``B1111011``) for values between 0 and 255 are -supported for compatibility with Arduino only. Their use in new -programs is discouraged. - -.. _lang-constants-integers-dec: - -**Decimal** is base 10. This is the common number system we learn in -school. Integer literals without other prefixes are assumed to be in -decimal format. - -For example, the decimal literal ``101`` is one hundred and one: 1×10\ -:sup:`2` + 0×10\ :sup:`1` + 1×10\ :sup:`0` = 101. - -.. _lang-constants-integers-bin: - -**Binary** is base two. Only characters 0 and 1 are valid. Binary -literals are indicated by the prefix ``0b`` (this is a :ref:`GCC -` extension; it's not standard C++). - -For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` + -0×2\ :sup:`1` + 1×2\ :sup:`0` = 5. - -.. _lang-constants-integers-oct: - -**Octal** is base eight. Only characters 0 through 7 are valid. Octal -literals are indicated by the prefix ``0``. - -For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` + -0×8\ :sup:`1` + 1×8\ :sup:`0` = 65. - -.. warning:: Bugs sometimes result by (unintentionally) including a - leading "0" before an integer literal, which makes the compiler - interpret it in octal. - -.. _lang-constants-integers-hex: - -**Hexadecimal** (or "hex") is base sixteen. Valid characters are 0 -through 9 and letters A through F; A has the value 10, B is 11, up to -F, which is 15. Hex values are indicated by the prefix ``0x``. A-F -may be typed in upper or lower case (a-f). - -For example, the hexadecimal literal ``0x101`` is two hundred fifty -seven: 1×16\ :sup:`2` + 0×16\ :sup:`1` + 1×16\ :sup:`0` = 257. - -The hexadecimal literal ``0xCF2`` is three thousand, three hundred -fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314. - -(Remember that in hex, ``A`` means 10, and counting up, ``B``\ =11, so -``C``\ =12 and ``F``\ =15). - -.. _lang-constants-integers-u-l: - -U and L Suffixes -^^^^^^^^^^^^^^^^ - -By default, an integer constant is treated as an :ref:`int -`, with the attendant :ref:`limitations in values -`. To specify an integer constant with another data -type, follow it with: - -- a ``u`` or ``U`` to interpret the constant as an unsigned value. - For example, ``33U`` is an :ref:`unsigned int `. - -- an ``l`` or ``L`` to interpret the constant as a long value. For - example, ``100000L`` is a :ref:`long `. - -- a ``ul`` or ``UL`` to do both. For example, ``32767UL`` is an - :ref:`unsigned long `. - -.. _lang-constants-fp: - -Floating-Point Constants ------------------------- - -Similar to integer literals, floating point constants (properly: -floating-point *literals*) are used to make code more readable. -Floating point literals are swapped at compile time for the value to -which the expression evaluates. - -A floating point literal is any number which includes a decimal point. -For instance, ``3.0`` is a floating-point literal for the number 3. -By default, a floating-point literal is a :ref:`double `. -In order for the literal to be interpreted as a :ref:`float -`, you can write ``f`` directly after it. For example, -``3.0f`` is a floating-point literal with type ``float``. - -Floating point constants can also be expressed in a variety of -scientific notation. ``E`` and ``e`` are both accepted as valid -exponent indicators. Some examples are given in the following table: - - -.. list-table:: - :header-rows: 1 - - * - Floating-point literal - - Evaluates to - - Alternate expression - - * - ``10.0`` - - 10 - - - - * - ``2.34E5`` - - 2.34×10\ :sup:`5` - - ``234000.0`` - - * - ``67e-12`` - - 67.0×10\ :sup:`-12` - - ``0.000000000067`` - -See Also --------- - -- :ref:`pinMode() ` -- :ref:`Boolean Variables ` -- :ref:`#define ` -- :ref:`int ` -- :ref:`unsigned int ` -- :ref:`long ` -- :ref:`unsigned long ` -- :ref:`float ` -- :ref:`double ` - -.. include:: cc-attribution.txt diff --git a/source/lang/constrain.rst b/source/lang/constrain.rst deleted file mode 100644 index d19b61c..0000000 --- a/source/lang/constrain.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. highlight:: cpp - -.. _lang-constrain: - -constrain() -=========== - -(Macro) Constrains a number to be within a range. - -Syntax ------- - -:: - - constrain(x, a, b) - - -Parameters ----------- - -**x**: the number to constrain - -**a**: the lower end of the range - -**b**: the upper end of the range - -Returns -------- - -**x**: if **x** is between **a** and **b** - -**a**: if **x** is less than **a** - -**b**: if **x** is greater than **b** - -Example -------- - -:: - - // limits range of sensor values to between 10 and 150: - sensVal = constrain(sensVal, 10, 150); - - -Warning -------- - -Because of the way ``constrain()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - constrain(x,a++,b); // avoid this - yields incorrect results - - constrain(x,a,b); // use this instead- - a++; // keep other math outside constrain() - -Arduino Compatibility ---------------------- - -Maple's implementation of ``constrain()`` is compatible with Arduino. - -See also --------- - -- :ref:`min() ` -- :ref:`max() ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/continue.rst b/source/lang/continue.rst deleted file mode 100644 index 13d1815..0000000 --- a/source/lang/continue.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. highlight:: cpp - -.. _lang-continue: - -``continue`` -============ - -The ``continue`` keyword skips the rest of the current iteration of a -:ref:`while `\ , :ref:`for `\ , or -:ref:`do/while ` loop. It continues by checking the -conditional expression of the loop, and proceeding with any subsequent -iterations. - -Example -------- - -:: - - - for (x = 0; x < 255; x ++) { - if (x > 40 && x < 120) { // create jump in values - continue; // skips the next two lines and goes to the - // beginning of the loop, with the next value of x - } - - digitalWrite(PWMpin, x); - delay(50); - } - - - -.. include:: cc-attribution.txt diff --git a/source/lang/cos.rst b/source/lang/cos.rst deleted file mode 100644 index 3fbb0af..0000000 --- a/source/lang/cos.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _lang-cos: - -cos() -===== - -Calculates the cosine of an angle. - -Library Documentation ---------------------- - -.. doxygenfunction:: cos - -Arduino Compatibility ---------------------- - -The Maple ``cos()`` implementation is compatible with Arduino. - -Note that the Maple implementation comes from `newlib -`_\ , while Arduino's is that of -`avr-libc `_\ . - -See also --------- - - -- :ref:`sin() ` -- :ref:`tan() ` -- :ref:`float ` -- :ref:`double ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/curly-braces.rst b/source/lang/curly-braces.rst deleted file mode 100644 index a4bd3dc..0000000 --- a/source/lang/curly-braces.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. highlight:: cpp - -.. _lang-curly-braces: - -Curly Braces (``{``, ``}``) -=========================== - -.. contents:: Contents - :local: - -Introduction ------------- - -Curly braces (also referred to as just "braces" or as "curly -brackets") are a major part of the C and C++ programming -languages. They are used in several different constructs, outlined -below, and this can sometimes be confusing for beginners. - -An opening curly brace, ``{`` must always be followed by a closing -curly brace ``}``. This is a condition that is often referred to as -the braces being *balanced*. The Maple IDE (integrated development -environment) includes a convenient feature to check the balance of -curly braces. Just select a brace, or even click the insertion point -immediately following a brace, and its companion will be highlighted\ -[#fbug]_\ . - -Beginning programmers, and programmers coming to C++ from languages -without braces, often find using them confusing or daunting. - -Because the use of the curly brace is so varied, it is good -programming practice to type the closing brace immediately after -typing the opening brace when inserting a construct which requires -curly braces. Then insert some blank lines between your braces and -begin inserting statements. Your braces, and your attitude, will never -become unbalanced. - -Unbalanced braces can often lead to cryptic, impenetrable compiler -errors that can sometimes be hard to track down in a large program. -Because of their varied usages, braces are also incredibly important -to the syntax of a program and moving a brace one or two lines will -usually dramatically affect the meaning of a program. - -The main uses of curly braces ------------------------------ - -**Functions**:: - - // a function body needs braces around it - void myFunction(datatype argument) { - // ... function body goes in here ... - } - -**Loops** (see the :ref:`while `\ , :ref:`for -`\ , and :ref:`do/while ` loop reference -pages for more information):: - - // you should put braces around the body of a loop: - - while (boolean expression) { - // code inside the loop goes here - } - - for (initialisation; termination condition; incrementing expr) { - // code inside the loop goes here - } - - do { - // code inside the loop goes here - } while (boolean expression); - - -**Conditional statements** (see the :ref:`if statement ` -reference page for more information):: - - // you should put braces around the body of an "if", "else if", - // or "else": - - if (boolean expression) { - // code inside the "if" - } - else if (boolean expression) { - // code inside the "else if" - } - else { - // code inside the "else" - } - -**Switch statements** (see the :ref:`switch statement -` reference page for more information):: - - switch (var) { - case 1: - doThing1(); - break; - case 2: - doThing2(); - break; - } - -.. rubric:: Footnotes - -.. TODO remove this once IDE 0.1.0 released - -.. [#fbug] At present this feature is slightly buggy as the IDE will - often find (incorrectly) a brace in text that has been commented - out. - - -.. include:: cc-attribution.txt diff --git a/source/lang/define.rst b/source/lang/define.rst deleted file mode 100644 index 677390d..0000000 --- a/source/lang/define.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. highlight:: cpp - -.. _lang-define: - -``#define`` -=========== - -``#define`` is a useful C and C++ feature that allows the programmer -to give a name to a constant value before the program is compiled. -The compiler will replace references to these constants with the -defined value at compile time. - -This can have some unwanted side effects. In general, the :ref:`const -` keyword is preferred for defining constants. - - -Syntax ------- - -The following line would define the name ``MY_CONSTANT`` to have value -``value``:: - - #define MY_CONSTANT value - -Note that the ``#`` is necessary. It is usually good style for the -name to be capitalized, although this is not required. - -There is no semicolon after the #define statement. If you include one, -the compiler will likely throw cryptic errors in unrelated places. -That is, **don't do this**:: - - // DON'T DO THIS! THE SEMICOLON SHOULDN'T BE THERE! - #define NAME value; - -Similarly, including an equal sign after the ``#define`` line will -also generate a cryptic compiler error further down the page. That -is, **don't do this, either**:: - - // DON'T DO THIS, EITHER! THE EQUALS SIGN SHOULDN'T BE THERE! - #define NAME = value - -Example -------- - -:: - - #define LED_PIN 13 - // The compiler will replace any mention of LED_PIN with - // the value 3 at compile time. - -See Also --------- -- :ref:`const ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/delay.rst b/source/lang/delay.rst deleted file mode 100644 index 90ca268..0000000 --- a/source/lang/delay.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. highlight:: cpp - -.. _lang-delay: - -delay() -======= - -Pauses the program for at least a given number of milliseconds. (There -are 1000 milliseconds in a second.) - -Library Documentation ---------------------- - -.. doxygenfunction:: delay - - -Discussion ----------- - -While it is easy to create a blinking LED with the ``delay()`` -function, and many sketches use short delays for such tasks as switch -debouncing, the use of ``delay()`` in a sketch has significant -drawbacks. No other reading of sensors, mathematical calculations, or -pin manipulation can go on during the delay function, so in effect, it -brings most other activity to a halt. For alternative approaches to -controlling timing see the :ref:`millis() ` function -and the "Blink Without Delay" sketch cited :ref:`below -`\ . More knowledgeable programmers usually -avoid the use of ``delay()`` for timing of events longer than tens of -milliseconds, unless the sketch is very simple. - -Certain things *do* go on while the ``delay()`` function is -controlling the STM32 chip, however, because the delay function does -not disable interrupts. Serial communication that appears at the RX -pin is recorded, PWM (see :ref:`pwmWrite() `\ ) values -and pin states are maintained, and :ref:`interrupts -` will work as they should. - - -Example -------- - -:: - - int ledPin = 13; // LED connected to pin 13 - - void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output - } - - void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second - } - -.. _lang-delay-seealso: - -See also --------- - - -- :ref:`millis() ` -- :ref:`micros() ` -- :ref:`delayMicroseconds() ` -- (Arduino) `Blink Without Delay - `_ example (works - unmodified on Maple) - - -.. include:: cc-attribution.txt diff --git a/source/lang/delaymicroseconds.rst b/source/lang/delaymicroseconds.rst deleted file mode 100644 index 24a8286..0000000 --- a/source/lang/delaymicroseconds.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. highlight:: cpp - -.. _lang-delaymicroseconds: - -delayMicroseconds() -=================== - -Pauses the program for the amount of time (in microseconds) -specified as parameter. There are a thousand microseconds in a -millisecond, and a million microseconds in a second. - -Library Documentation ---------------------- - -.. doxygenfunction:: delayMicroseconds - - -Example -------- - -The following example configures pin number 8 to work as an output -pin, and sends a train of pulses with a period of roughly 100 -microseconds:: - - int outPin = 8; - - void setup() { - pinMode(outPin, OUTPUT); // sets the digital pin as output - } - - void loop() { - digitalWrite(outPin, HIGH); // sets the pin on - delayMicroseconds(50); // pauses for 50 microseconds - digitalWrite(outPin, LOW); // sets the pin off - delayMicroseconds(50); // pauses for 50 microseconds - } - - -Caveats and Known Issues ------------------------- - -The longest time ``delayMicroseconds()`` can delay is bounded by its -argument type and the STM32 clock rate to be (2^32 - 1) / 12 -microseconds, or less than 6 minutes. For longer pauses, use of -:ref:`lang-delay` is possible. - -Arduino Compatibility ---------------------- - -While we have made every effort we could to ensure that the timing of -delayMicroseconds is as accurate as possible, we cannot guarantee it -will behave as the Arduino implementation down to the microsecond, -especially for smaller values of ``us``. - -See Also --------- - -- :ref:`millis ` -- :ref:`micros ` -- :ref:`delay ` - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/detachinterrupt.rst b/source/lang/detachinterrupt.rst deleted file mode 100644 index adb2439..0000000 --- a/source/lang/detachinterrupt.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _lang-detachinterrupt: - -detachInterrupt() -================= - -Used to disable an interrupt specified with -:ref:`lang-attachinterrupt`\ . - - -Library Documentation ---------------------- - -.. doxygenfunction:: detachInterrupt - -Arduino Compatibility ---------------------- - -There is one important difference between the Maple version of -detachInterrupt and the Arduino version. On the Maple, the argument -to ``detachInterrupt()`` is the *pin* on which the interrupt is -attached, while on the Arduino, the argument is the *interrupt -number*, which is different from the pin the interrupt is enabled on. - -If you're calling this function, you've already called -:ref:`lang-attachinterrupt` to set up your interrupt handler, so -just call ``detachInterrupt()`` with the same pin argument you gave to -``attachInterrupt()``. - -See Also --------- - -- :ref:`attachInterrupt() ` - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/digitalread.rst b/source/lang/digitalread.rst deleted file mode 100644 index 3502587..0000000 --- a/source/lang/digitalread.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. highlight:: cpp - -.. _lang-digitalread: - -digitalRead() -============= - -Reads the value from a specified digital pin, either :ref:`HIGH -` or :ref:`LOW `. - - -Library Documentation ---------------------- - -.. doxygenfunction:: digitalRead - - -Example -------- - -The following example turns the LED on when the button is pressed:: - - int ledPin = 13; // LED connected to Maple pin 13 - int buttonPin = 38; // BUT connected to Maple pin 38 - - void setup() { - pinMode(ledPin, OUTPUT); - pinMode(buttonPin, INPUT); - } - - void loop() { - int val = digitalRead(buttonPin); // reads the input pin - digitalWrite(ledPin, val); - } - -Note ----- - -If the pin isn't connected to anything, ``digitalRead()`` can return -either HIGH or LOW (and this can change in a way that seems random). - -Arduino Compatibility ---------------------- - -The Maple version of ``digitalRead()`` is compatible with Arduino. - - -See Also --------- - -- :ref:`pinMode ` -- :ref:`digitalWrite ` - - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/digitalwrite.rst b/source/lang/digitalwrite.rst deleted file mode 100644 index 6124d5f..0000000 --- a/source/lang/digitalwrite.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. highlight:: cpp - -.. _lang-digitalwrite: - -digitalWrite() -============== - -Write a :ref:`HIGH ` or a :ref:`LOW -` value to a pin configured as :ref:`OUTPUT -`. - -Library Documentation ---------------------- - -.. doxygenfunction:: digitalWrite - -Discussion ----------- - -If the pin has been configured as an ``OUTPUT`` with :ref:`pinMode() -` its voltage will be set to the corresponding value: -3.3V for ``HIGH``, and 0V (ground) for ``LOW``. - -.. TODO make the following paragraphs true, but refer the reader to -.. INPUT_PULLUP and INPUT_PULLDOWN: - -If the pin is configured as an ``INPUT``, writing a ``HIGH`` value -with ``digitalWrite()`` will enable an internal pullup resistor. -Writing ``LOW`` will disable the pullup. The pullup resistor is enough -to light an LED dimly, so if LEDs appear to work, but very dimly, this -is a likely cause. The remedy is to set the pin to an output with the -:ref:`pinMode() ` function. - -.. note:: Pin 13 is harder to use as an input than the other pins - because it has an LED and resistor soldered to it in series. If you - enable its internal pull-up resistor, it will likely hang at around - 1.1V instead of the expected 3.3V because the onboard LED and - series resistor pull the voltage level down. If you must use pin 13 - as a digital input, use an external pull-down resistor. - -Example -------- - -The following example sets pin 13 to ``HIGH``, makes a one-second-long -delay, sets the pin back to ``LOW``, and delays again, causing a -blinking pattern:: - - - int ledPin = 13; // LED connected to digital pin 13 - - void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output - } - - void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second - } - -See Also --------- - -- :ref:`pinMode ` -- :ref:`digitalRead ` - -.. include:: cc-attribution.txt diff --git a/source/lang/double.rst b/source/lang/double.rst deleted file mode 100644 index 1527778..0000000 --- a/source/lang/double.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _lang-double: - -``double`` -========== - -Double precision floating point type. Occupies 8 bytes. On Maple, the -``double`` type has a range of approximately -1.79769×10^308 to -1.79769×10^308; the ``double`` type subject to the same :ref:`overflow -issues ` as any numeric data type. - -Floating point numbers are not exact, and may yield strange results -when compared. For example ``6.0 / 3.0`` may not equal ``2.0``. You -should instead check that the absolute value of the difference between -the numbers is less than some small number. - -Floating point math is also much slower than integer math in -performing calculations, so should be avoided if, for example, a loop -has to run at top speed for a critical timing function. Programmers -often go to some lengths to convert floating point calculations to -integer math to increase speed. - -For more information, see the `Wikipedia article on floating point -math `_\ . - -Floating-point numbers represent numbers with "decimal point", unlike -integral types, which always represent whole numbers. Floating-point -numbers are often used to approximate analog and continuous values -because they have greater resolution than integers. - -The double implementation on the Maple uses twice the number of bytes -as a :ref:`float `, with the corresponding gains in -precision. - -Tip ---- - -Users who borrow code from other sources that includes ``double`` -variables may wish to examine the code to see if the implied range and -precision are different from that actually achieved on the Maple. - -See Also --------- - -- :ref:`float ` - - - -.. include:: cc-attribution.txt diff --git a/source/lang/doublecast.rst b/source/lang/doublecast.rst deleted file mode 100644 index 511fe24..0000000 --- a/source/lang/doublecast.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. highlight:: cpp - -.. _lang-doublecast: - -``double()`` (cast) -=================== - -Converts a value to the :ref:`double ` floating point -data type. Here is an example:: - - int x = 2; - double d = double(x); // d now holds 2.0, a double value - -The value ``x`` can be of any type. However, if ``x`` is not a number -(like an ``int`` or ``long``), you will get strange results. - -See the :ref:`double ` reference for details about the -precision and limitations of ``double`` values on the Maple. - -See Also --------- - -- :ref:`double ` -- :ref:`float ` -- :ref:`float() ` - -.. include:: cc-attribution.txt diff --git a/source/lang/dowhile.rst b/source/lang/dowhile.rst deleted file mode 100644 index fe92226..0000000 --- a/source/lang/dowhile.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. highlight:: cpp - -.. _lang-dowhile: - -``do``/``while`` -================ - -A ``do`` loop works in the same manner as a :ref:`while -` loop, with the exception that the condition is tested -at the end of the loop, so the ``do`` loop will *always* run at least -once. - -This is the basic syntax:: - - do { - // statement block - } while (test condition); - -Example:: - - do { - delay(50); // wait for sensors to stabilize - x = readSensors(); // check the sensors - } while (x < 100); - - -.. include:: cc-attribution.txt diff --git a/source/lang/enum.rst b/source/lang/enum.rst deleted file mode 100644 index ba82383..0000000 --- a/source/lang/enum.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. highlight:: cpp - -.. _lang-enum: - -``enum`` -======== - -The ``enum`` keyword is used to specify an enumeration type. An -enumeration type is a type whose values are taken from a specified, -fixed list of constant values. - -Example -------- - -Here's an example defining an enumeration type called ``weather``, -which has values ``HOT``, ``COMFY``, and ``COLD``:: - - enum weather {HOT, COMFY, COLD}; - -Once you've defined this type, you can create variables of type -``weather``, in the same way you would with an :ref:`int ` -or a :ref:`long `:: - - // create a weather variable named theWeather, with value COMFY: - weather theWeather = COMFY; - -Enumeration types are useful within :ref:`switch statements -`. If you know that an argument is of an enumeration -type, you can make ``case`` statements for all of that type's possible -values, so you know you won't miss anything:: - - void describeWeather(weather currentWeather) { - switch(currentWeather) { - case HOT: - SerialUSB.println("it's hot out"); - break; - case COMFY: - SerialUSB.println("it's nice today"); - break; - case COLD: - SerialUSB.println("it's freezing!"); - break; - } - } - -Such a ``switch`` statement would need no :ref:`default -`, since we know that ``currentWeather`` must -be either ``HOT``, ``COMFY``, or ``COLD``. - -See Also --------- - -- :ref:`lang-switchcase` diff --git a/source/lang/float.rst b/source/lang/float.rst deleted file mode 100644 index 6937c8c..0000000 --- a/source/lang/float.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. highlight:: cpp - -.. _lang-float: - -``float`` -========= - -Single-precision floating point number. Occupies 4 bytes. On Maple, -the ``float`` type has a range of approximately -3.40282×10^38 to -3.40282×10^38; the ``float`` type is subject to the same -:ref:`overflow issues ` as any numeric data -type. - -``float``\ s have only 6-7 decimal digits of precision. That means the -total number of digits, not the number to the right of the decimal -point. You can get more precision by using a :ref:`double -` (which has a precision of about 16 decimal digits). - -The following example declares a ``float`` value named ``myfloat``:: - - float myfloat; - -This example declares a ``float`` value named ``sensorCalibrate``, -with value 1.117:: - - float sensorCalibrate = 1.117; - -The general syntax for declaring a float named ``var`` with value -``val`` is:: - - float var = val; - -Here is a more extended example involving a :ref:`float cast -`:: - - int x; - int y; - float z; - - x = 1; - y = x / 2; // y now contains 0, ints can't hold fractions - z = float(x) / 2; // z now contains .5 - -See Also --------- - -- :ref:`double ` -- :ref:`Variables ` - -.. include:: cc-attribution.txt diff --git a/source/lang/floatcast.rst b/source/lang/floatcast.rst deleted file mode 100644 index 4766478..0000000 --- a/source/lang/floatcast.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. highlight:: cpp - -.. _lang-floatcast: - -``float()`` (cast) -================== - -Converts a value to the :ref:`float ` data type. Here is -an example (see the :ref:`constants reference ` for -an explanation of the "2.0f"):: - - int x = 2; - float f = float(x); // f now holds 2.0f, a float value - -The value ``x`` can be of any type. However, if ``x`` is not a number -(like an ``int``), you will get strange results. - -See the :ref:`float ` reference for details about the -precision and limitations of ``float`` values on the Maple. - -See Also --------- - -- :ref:`float ` -- :ref:`double ` -- :ref:`double() ` - -.. include:: cc-attribution.txt diff --git a/source/lang/for.rst b/source/lang/for.rst deleted file mode 100644 index 71c5aca..0000000 --- a/source/lang/for.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. highlight:: cpp - -.. _lang-for: - -``for`` -======= - -A ``for`` loop is used to repeat a block of statements enclosed in -curly braces. ``for`` loops are useful for performing repetitive -operations, and are often used in combination with :ref:`arrays -` to operate on collections of data or multiple -:ref:`pins `. A ``for`` loop is composed of two parts: first, a -*header*, which sets up the for loop, and then a *body*, which is made -up of lines of code enclosed in curly braces. - -.. contents:: Contents - :local: - -Syntax ------- - -There are three parts to the ``for`` loop header: an *initialization* -expression, *loop condition* expression, and a *post-loop* -expression. The general syntax looks like this:: - - for (initialization; condition; post-loop) { - // all of these lines inside the curly braces are part - // of the loop body. - statement 1; - statement 2; - ... - } - -(Note that there is no semicolon after the post-loop). The -initialization happens first and exactly once, before the loop begins. -Each time through the loop, the condition is tested. The condition is -a :ref:`boolean ` expression. If it is true, then the -list of statements inside the curly braces are executed. Next, the -post-loop is executed. The loop then begins again by evaluating the -condition again, entering the loop body if it is true. This proceeds -until the condition becomes false. - -Examples --------- - -Here's an example:: - - // Dim an LED using a PWM pin - int pwmPin = 9; // LED in series with 470 ohm resistor on pin 9 - - void setup() { - pinMode(pwmPin, PWM); - } - - void loop() { - for (int i=0; i <= 65535; i++) { - pwmWrite(pwmPin, i); - delay(1); - } - } - -There is a ``for`` loop In the :ref:`loop() ` function of -the above example. This loop starts by declaring an ``int`` variable -named ``i``, whose value starts out at zero. The loop proceeds by -checking if ``i`` is less than or equal to 65535. Since ``i`` is -zero, this is true, and so the calls to :ref:`pwmWrite() -` and :ref:`delay() ` happen next. At this -point, the post-loop expression ``i++`` is evaluated, which -:ref:`increments ` ``i``, so that ``i`` becomes one. -That concludes the first time through the loop. Each "time through -the loop" is referred to as an *iteration*. - -The loop then jumps back to the beginning, checking the condition as -the beginning of its second iteration (initialization is skipped, -since this only happens once, before the first iteration). One is -less than 65535, so the loop statements are executed again. This -proceeds over and over until the iteration when ``i`` finally -reaches 65536. At that point, the condition is no longer true, so the -loop stops executing, and the ``loop()`` function returns. - -Here's another example, using a ``for`` loop to brighten and fade an -LED (see the :ref:`pwmWrite() ` reference for more -information):: - - int pwmPin = 9; // hook up the LED to pin 9 - void loop() { - int x = 1; - for (int i = 0; i >= 0; i += x) { - analogWrite(pwmPin, i); // controls the brightness of the LED - if (i == 65535) { - x = -1; // switch direction, so i starts decreasing - } - delay(1); - } - } - -Coding Tips ------------ - -The C ``for`` loop is more flexible than ``for`` loops found in some -other computer languages, including BASIC. Any or all of the three -header elements may be left blank, although the semicolons are -required. Also the statements for initialization, condition, and -post-loop can be any valid C statements, and use any C datatypes, -including :ref:`floating point numbers `. These types -of unusual ``for`` loops sometimes provide solutions to less-common -programming problems. - -For example, using a multiplication in the post-loop line will -generate a `geometric progression -`_:: - - for(int x = 1; x <= 100; x = x * 2) { - SerialUSB.println(x); - } - - -This loop prints out the numbers 1, 2, 4, 8, ..., 64. Check -your understanding of ``for`` loops by answering the following two -questions (answers are in footnote [#fanswers]_\ ): - -1. How many iterations occur before the loop finishes? - -2. Why does it stop at 64? - -See also --------- - -- :ref:`while ` loops -- :ref:`do ` loops - -.. rubric:: Footnotes - -.. [#fanswers] - 1. Seven. - - 2. After the seventh iteration, the post-loop causes ``x`` to - equal 128. This is larger than 100, so the loop condition is - false, and the loop stops. - - -.. include:: cc-attribution.txt diff --git a/source/lang/goto.rst b/source/lang/goto.rst deleted file mode 100644 index ff2f248..0000000 --- a/source/lang/goto.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. highlight:: cpp - -.. _lang-goto: - -Labels and ``goto`` -=================== - -A *label* gives a name to a line of code within a function. You can -label a line by writing a name for it, then a colon (``:``), before -the line starts. The ``goto`` keyword allows program flow to transfer -to a labeled line from anywhere within the same function. - -.. warning:: The use of ``goto`` is discouraged in C and C++ - programming. It is *never necessary* to use ``goto`` to write a - program. - - Unless you know what you're doing, using ``goto`` tends to - encourage code which is harder to debug and understand than - programs without ``goto`` that do the same thing. That said, - however, it's sometimes useful; :ref:`see below ` - for a concrete example. - -Using Labels and goto ---------------------- - -Labels and ``goto`` are probably best explained through example. -Let's start with an example of how to label lines. The first line -(``int x = analogRead(some_pin);``) in the :ref:`loop ` -function below has label ``readpin``. The third line (``delay(x);``) -has label ``startdelay``. The second line (``SerialUSB.println(x);``) -does not have a label:: - - void loop() { - readpin: - int x = analogRead(some_pin); - SerialUSB.println(x); // for debugging - startdelay: - delay(x); - // ... more code ... - } - -Anything which can be a :ref:`variable ` name can -be a label. - -Let's say that we wanted to print ``x`` only if it was very large, say -at least 2000. We might want to do this just so anybody watching on a -:ref:`serial monitor ` would know they were in for -a longer wait than usual. We can accomplish this through the use of a -``goto`` statement that skips the printing if ``x`` is less than -2000:: - - void loop() { - readpin: - int x = analogRead(some_pin); - if (x < 2000) { - goto startdelay; - } - SerialUSB.println(x); // for debugging - startdelay: - delay(x); - // ... more code ... - } - -In this modified program, whenever ``x`` is less than 2000, the body -of the :ref:`if ` statement in the second line is -executed. The ``goto`` statement inside the ``if`` body skips -straight to the line labeled ``startdelay``, passing over the line -doing the printing. - -A ``goto`` does not have to "move forwards"; it can go "backwards", -too. For example, the following program prints "5" forever (why?):: - - void loop() { - printfive: - SerialUSB.println(5); - goto printfive; - SerialUSB.println(6); - } - -.. _goto-when-to-use: - -When to Use goto ----------------- - -As mentioned above, use of ``goto`` is `generally discouraged -`_. However, -when used with care, ``goto`` can simplify certain programs. One -important use case for ``goto`` is breaking out of deeply nested -:ref:`for ` loops or :ref:`if ` logic blocks. -Here's an example:: - - for(int r = 0; r < 255; r++) { - for(int g = 255; g > -1; g--) { - for(int b = 0; b < 255; b++) { - if (analogRead(0) > 250) { - goto bailout; - } - // more statements ... - } - // innermost loop ends here - } - } - bailout: - // more code here - -In the above example, whenever the :ref:`analog reading -` on pin 0 was greater than 250, the program would -jump to the line labeled ``bailout``, exiting all three loops at once. - -While there is already a :ref:`break ` keyword for -breaking out of a loop, it will only break out of the *innermost* -loop. So, if instead of saying "``goto bailout;``", there was a -"``break;``" instead, the program would only exit from the loop with -header "``for(int b = 0; b < 255; b++)``". The program would continue -at the line which reads "``// innermost loop ends here``", which is -clearly undesirable if you wanted to leave all three loops at once. - -More examples of when ``goto`` is a good choice are given in Donald -Knuth's paper, "Structured Programming with go to Statements"; see -below for a link. - -See Also --------- - -- Dijkstra, Edsger W. `Go To Statement Considered Harmful `_ (PDF) - -- Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) - - -.. include:: cc-attribution.txt diff --git a/source/lang/highbyte.rst b/source/lang/highbyte.rst deleted file mode 100644 index 50a1fa6..0000000 --- a/source/lang/highbyte.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. highlight:: cpp - -.. _lang-highbyte: - -highByte() -========== - -(Macro) Extracts the second lowest byte of an integral data type. - -.. warning:: This macro is provided for compatibility with Arduino - only. It returns the second-least significant byte in an integral - value. It makes sense to call this the "high" byte on a 16-bit - ``int`` microcontroller like the Atmel chips on Arduinos, but it - makes no sense at all on a 32-bit microcontroller like the STM32s - in the Maple line. - - In short: we provide this so that existing Arduino code works as - expected, but **strongly discourage its use** in new programs. - -Syntax ------- - -:: - - highByte(x) - -Parameters ----------- - -**x**: a value of any integral type. - -Returns -------- - -Second lowest byte in **x**. - -Example -------- - -:: - - int x = 0xDEADBEEF; - SerialUSB.println(x, HEX); // prints "BE" - -Arduino Compatibility ---------------------- - -The Maple version of ``highByte()`` is compatible with Arduino. - -See Also --------- - -- :ref:`lowByte() ` - - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/if.rst b/source/lang/if.rst deleted file mode 100644 index bef89e2..0000000 --- a/source/lang/if.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. highlight:: cpp - -.. _lang-if: - -``if``/``else`` -=============== - -An ``if`` statement is used to execute code when certain conditions -are met. The general syntax for an ``if`` statement is:: - - if (condition) { - body - } - -An ``if`` statement first tests whether its *condition* is true (such -as an input being above a certain number). If the condition is true, -the ``if`` statement executes its *body*, which is made up of lines of -code inside :ref:`curly braces `. If the condition -is false, the body is not executed. Here's a more concrete example:: - - if (someVariable > 50) { - // do something here - } - -The program tests to see if ``someVariable`` is greater than 50. If it -is, the program executes every line in the curly braces (which in the -above example does nothing, since the body is just the :ref:`comment -` line "``// do something here``"). - -Put another way, if the statement in parentheses is true, the -statements inside the braces are run. If not, the program skips over -the code. - -An ``if`` statement's condition (which is inside the parentheses after -``if``) often uses one or more :ref:`boolean ` or -:ref:`comparison ` operators. - -Writing the if Body -------------------- - -The brackets may be omitted after an ``if`` statement's -conditional. If this is done, the next line (which ends in a -semicolon) becomes the only line in the body. The following three -``if`` statements all do the same thing:: - - if (x > 120) digitalWrite(ledPin, HIGH); - - if (x > 120) - digitalWrite(ledPin, HIGH); - - if (x > 120) { - digitalWrite(ledPin, HIGH); - } - -However, the following two examples are different:: - - // example 1: two lines of code in the if body - if (x > 120) { - digitalWrite(ledPin1, HIGH); - digitalWrite(ledPin2, HIGH); - } - - // example 2: one line of code in the if body, and - // another line of code after the if statement - if (x > 120) - digitalWrite(ledPin1, HIGH); // this is in the if body - digitalWrite(ledPin2, HIGH); // this is NOT in the if body - -In the first example, since the body is enclosed in curly braces, both -lines are included. In the second example, since the curly braces are -missing, only the first line is in the ``if`` body. - -``else`` --------- - -``if``/\ ``else`` allows greater control over the flow of code than -the basic :ref:`if ` statement, by allowing multiple tests to -be grouped together. For example, an :ref:`analog input -` could be tested, with one action taken if the input -was less than 500, and another action taken if the input was 500 or -greater. The code would look like this:: - - if (pinFiveInput < 500) { - // action A - } else { - // action B - } - -``else`` can precede another ``if`` test, so that multiple, mutually -exclusive tests can be run at the same time. - -Each test will proceed to the next one until a true test is -encountered. When a true test is found, its associated block of code -is run, and the program then skips to the line following the entire -if/else construction. If no test proves to be true, the default -``else`` block is executed, if one is present, and sets the default -behavior. - -Note that an ``else if`` block may be used with or without a -terminating ``else`` block, and vice-versa. An unlimited number of -such ``else if`` branches is allowed. Here is a code example:: - - if (pinFiveInput < 500) { - // do Thing A - } else if (pinFiveInput >= 1000) { - // do Thing B - } else { - // do Thing C - } - -Another way to express branching, mutually exclusive tests, is with a -:ref:`switch/case ` statement. - - -See Also --------- - -- :ref:`boolean operators ` -- :ref:`comparison operators ` - -.. include:: cc-attribution.txt diff --git a/source/lang/include.rst b/source/lang/include.rst deleted file mode 100644 index 74fe7af..0000000 --- a/source/lang/include.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. highlight:: cpp - -.. _lang-include: - -``#include`` -============ - -``#include`` is used to include outside libraries in your sketch. -This gives the programmer access to a large group of standard C -libraries (groups of pre-made functions and data types), and also -libraries written especially for Maple. - -Example -------- - -This example (from the `Arduino LiquidCrystal Tutorial -`_) includes a library -that is used to control :ref:`LCD displays -`:: - - // include the library code: - #include - - // initialize the library with the numbers of the interface pins - LiquidCrystal lcd(12, 11, 5, 4, 3, 2); - - void setup() { - // set up the LCD's number of columns and rows: - lcd.begin(16, 2); - // Print a message to the LCD. - lcd.print("hello, world!"); - } - - void loop() { - // set the cursor to column 0, line 1 - // (note: line 1 is the second row, since counting begins with 0): - lcd.setCursor(0, 1); - // print the number of seconds since reset: - lcd.print(millis()/1000); - } - -Note that a ``#include`` line, like :ref:`#define `, -has **no semicolon**. The compiler will print strange error messages -if you add one. - -C Standard Library ------------------- - -The standard C library that comes with Maple is called `newlib -`_. Its main sources of documentation -are its `main reference `_ -page and its `math functions -`_ reference page. Here's an -example that imports the math.h library in order to take the `cube -root `_ of a number:: - - #include - - void setup() { - // no setup necessary - } - - void loop() { - // "cbrt" stands for "cube root" - double cubeRootOf3 = cbrt(3.0); - // prints a number that is approximately the cube root of 3: - SerialUSB.println(cubeRootOf3); - } - - - -.. include:: cc-attribution.txt diff --git a/source/lang/increment.rst b/source/lang/increment.rst deleted file mode 100644 index 6dffa80..0000000 --- a/source/lang/increment.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. highlight:: cpp - -.. _lang-increment: - -Increment and Decrement Operators (``++``, ``--``) -================================================== - -These operators increment (add one to) or decrement (subtract one -from) a variable. If they come before the variable, they return its -new value; otherwise, they return its old value. - -Some quick examples:: - - x++; // adds one to x, and returns the old value of x - ++x; // adds one to x, and returns the new value of x - - x--; // decrement x by one and returns the old value of x - --x; // decrement x by one and returns the new value of x - -A more extended example:: - - x = 2; - y = ++x; // x now contains 3, y contains 3 - y = x--; // x contains 2 again, y still contains 3 - -.. warning:: Be careful! You cannot put a space in between the two - ``+`` or ``-`` signs. This example is broken:: - - // this line won't compile (notice the extra space): - int y = x+ +; - -See Also --------- - -- :ref:`lang-compoundarithmetic` - -.. include:: cc-attribution.txt diff --git a/source/lang/int.rst b/source/lang/int.rst deleted file mode 100644 index ca75f75..0000000 --- a/source/lang/int.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. highlight:: cpp - -.. _lang-int: - -``int`` -======= - -The ``int`` data type represents integers. Integers are your primary -data type for number storage, and store a 4 byte value. This yields a -range of -2,147,483,648 to 2,147,483,647 (minimum value of -2^31 and a -maximum value of (2^31) - 1; that's about negative 2 billion to -positive 2 billion). - -An ``int`` stores a negative number with a technique called `two's -complement math -`_\ . -The highest bit in an ``int``, sometimes refered to as the "sign" bit, -flags the number as a negative number. (See the linked article on -two's complement for more information). - -The Maple takes care of dealing with negative numbers for you, so that -arithmetic operations work mostly as you'd expect. There can be an -:ref:`unexpected complication ` in -dealing with the :ref:`bitshift right operator (>>) -`, however. - -Here is an example of declaring an ``int`` variable named ``ledPin``, -then giving it value 13:: - - int ledPin = 13; - -The general syntax for declaring an ``int`` variable named ``var``, -then giving it value ``val``, looks like:: - - int var = val; - -.. _lang-int-overflow: - -Integer Overflow ----------------- - -When ``int`` variables leave the range specified above, they -:ref:`roll over ` in the other direction. -Here are some examples:: - - int x; - x = -2,147,483,648; - x--; // x now contains 2,147,483,647; rolled over "left to right" - - x = 2,147,483,647; - x++; // x now contains -2,147,483,648; rolled over "right to left" - -See Also --------- - -- :ref:`unsigned int ` -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`long ` -- :ref:`unsigned long ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - -.. include:: cc-attribution.txt diff --git a/source/lang/intcast.rst b/source/lang/intcast.rst deleted file mode 100644 index 386fe14..0000000 --- a/source/lang/intcast.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. highlight:: cpp - -.. _lang-intcast: - -``int()`` (cast) -================ - -Converts a value to the :ref:`int ` data type. Here is -an example:: - - double d = 2.5; - int i = int(d); // i holds "2", an int value - -The value inside of the parentheses (``int(...)``) can be of any type. -However, if it is not a numeric type (like ``double``, ``char``, -etc.), you will get strange results. - -See the :ref:`int ` reference for details about the -precision and limitations of ``int`` variables on the Maple. - -See Also --------- - -- :ref:`int ` - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/keywords.rst b/source/lang/keywords.rst deleted file mode 100644 index e4ebe99..0000000 --- a/source/lang/keywords.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. _lang-keywords: - -Keywords -======== - -This page lists all of the C++ keywords, and either links to a -reference page explaining their use, or provides a brief description. - -List of Keywords ----------------- - -The C++ keywords are: - -``and``, ``and_eq``, ``asm``, ``auto``, ``bitand``, ``bitor``, -``bool``, ``break``, ``case``, ``catch``, ``char``, ``class``, -``compl``, ``const``, ``const_cast``, ``continue``, ``default``, -``delete``, ``do``, ``double``, ``dynamic_cast``, ``else``, ``enum``, -``explicit``, ``export``, ``extern``, ``false``, ``float``, ``for``, -``friend``, ``goto``, ``if``, ``inline``, ``int``, ``long``, -``mutable``, ``namespace``, ``new``, ``not``, ``not_eq``, -``operator``, ``or``, ``or_eq``, ``private``, ``protected``, -``public``, ``register``, ``reinterpret_cast``, ``return``, ``short``, -``signed``, ``sizeof``, ``static``, ``static_cast``, ``struct``, -``switch``, ``template``, ``this``, ``throw``, ``true``, ``try``, -``typedef``, ``typeid``, ``typename``, ``union``, ``unsigned``, -``using``, ``virtual``, ``void``, ``volatile``, ``wchar_t``, -``while``, ``xor``, ``xor_eq`` - -Boolean Operator Synonyms -------------------------- - -- ``and`` is a synonym for :ref:`&& `. -- ``not`` is a synonym for :ref:`\! `. -- ``not_eq`` is a synonym for :ref:`\!= `. -- ``or`` is a synonym for :ref:`|| `. - -Bitwise Operator Synonyms -------------------------- - -- ``and_eq`` is a synonym for :ref:`&= `. -- ``bitand`` is a synonym for (bitwise) :ref:`& `. -- ``bitor`` is a synonym for :ref:`\| `. -- ``compl`` is a synonym for :ref:`~ `. -- ``or_eq`` is a synonym for :ref:`|= `. -- ``xor`` is a synonym for :ref:`^ `. -- ``xor_eq`` is a synonym for :ref:`^= `. - -Constants ---------- - -- ``true`` and ``false`` are the :ref:`boolean constants - `. - -Control Flow ------------- - -- ``break`` can exit out of a :ref:`switch statement - ` or a :ref:`for `, :ref:`do - `, or :ref:`while ` loop. - -- ``case`` defines alternatives in a :ref:`switch statement `. - -- ``continue`` will move control flow to the next iteration of the - enclosing :ref:`for `, :ref:`do `, or - :ref:`while ` loop. - -- ``default`` defines the default alternative in a :ref:`switch - statement `. - -- ``do`` introduces a :ref:`do ` loop. - -- ``else`` is used in :ref:`if statements `. - -- ``for`` introduces a :ref:`for ` loop. - -- ``goto`` :ref:`jumps ` to a label. - -- ``if`` introduces an :ref:`if statement `. - -- ``return`` :ref:`transfers flow to a function's caller `. - -- ``switch`` introduces a :ref:`switch statement `. - -- ``while`` introduces a :ref:`while ` loop. - -Types ------ - -The following keywords are used for built-in types. - -- :ref:`bool ` -- :ref:`lang-char` -- :ref:`lang-double` -- :ref:`lang-float` -- :ref:`lang-int` -- :ref:`lang-long` -- :ref:`short ` -- :ref:`void ` (not really a type, but used in the absence - of one) - -The following keywords are used to introduce new types. - -- :ref:`enum ` - -Qualifiers ----------- - -- :ref:`static ` can be used to declare persistent local - variables; it has other uses not documented here. - -- ``unsigned`` is used to specify an unsigned integral type. - Examples: :ref:`lang-unsignedint`, :ref:`lang-unsignedchar`, - :ref:`lang-unsignedlong`. - -- :ref:`volatile ` is useful when declaring variables - that may be modified by external interrupts. - -- :ref:`const ` is used to define constants. - -Other ------ - -These keywords are not described in the Maple documentation. For more -information, consult a C++ reference. - -- ``asm`` is used to insert literal assembly language. - -- ``auto`` is used to declare that a variable has automatic storage. - -- ``catch`` is used in exception handling. Note that the default - flags we pass to :ref:`GCC ` include ``-fno-exceptions``. - -- ``class`` is used to define classes. - -- ``const_cast`` is used in typecasting. - -- ``delete`` is used to free ``new``\ -allocated storage. Note that - dynamic memory allocation is not available by default on the Maple, - so you'll have to bring your own ``new`` and ``delete`` if you want - this. - -- ``dynamic_cast`` is used in typecasting. - -- ``explicit`` is used to declare constructors that can be called only - explicitly. - -- ``export`` declares a template definition accessible to other - compilation units. - -- ``extern`` can mark a declaration as a declaration and not a - definition, and also grant external linkage to a ``const`` or - ``typedef``. - -- ``friend`` is used to declare that certain functions have access to - a class's private variables. - -- ``inline`` is a compiler hint to inline a function. - -- ``mutable`` specifies that a member can be updated, even when a - member of a ``const`` object. - -- ``namespace`` declares a new namespace. - -- ``new`` dynamically allocates space for a value. Note that dynamic - memory allocation is not available by default on the Maple, so - you'll have to bring your own ``new`` and ``delete`` if you want - this. - -- ``operator`` is used to define type-specific operator overrides. - -- ``private`` declares a private class member. - -- ``protected`` declares a protected class member. - -- ``public`` declares a public class member. - -- ``register`` is a compiler hint to store a variable in a register. - -- ``reinterpret_cast`` is used in typecasting. - -- ``signed`` is the opposite of ``unsigned``. - -- ``static_cast`` is used in typecasting. - -- ``struct`` declares a new struct. - -- ``template`` introduces a template class, function, etc. - -- ``this`` is a pointer to the receiver object. - -- ``throw`` is used in exception handling. Note that the default - flags we pass to :ref:`GCC ` include ``-fno-exceptions``. - -- ``try`` is used in exception handling. Note that the default - flags we pass to :ref:`GCC ` include ``-fno-exceptions``. - -- ``typedef`` defines a type synonym. - -- ``union`` defines an untagged union. - -- ``using`` is a directive related to namespaces. - -- ``virtual`` declares a method which may be overridden. - -- ``wchar_t`` is the wide character type. diff --git a/source/lang/long.rst b/source/lang/long.rst deleted file mode 100644 index d8498c0..0000000 --- a/source/lang/long.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _lang-long: - -``long`` -======== - -The ``long`` data type stores extended size integer values. You can -use a ``long`` when your values are too large to fit into an :ref:`int -`. A ``long`` occupies 8 bytes of memory. This yields a -range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion -billion, or about 92 million times the number of stars in the Milky -Way galaxy). The exact range of a ``long`` on the Maple is from --9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to -(2^63-1). A ``long`` it is subject to the same :ref:`overflow issues -` as any numeric data type. - -Here's an example of declaring a long (see :ref:`integer constants -` for an explanation of the "L" at the end of the -number):: - - // Speed of light in nanometers per second (approximate). - long c = 299792458000000000L; - -The general syntax for declaring an ``long`` variable named ``var``, -then giving it value ``val``, looks like:: - - long var = val; - -This is identical to the ``int`` syntax, with ``long`` replacing -``int``. - -Note that ``long`` values will still :ref:`overflow -`, just like ``int`` values, but their much -larger range makes this less likely to happen. - -The downside to using a ``long`` instead of an ``int`` (besides the -extra storage) is that :ref:`arithmetic ` operations -on ``long``\ s will take slightly longer than on ``int``\ s. - -See Also --------- - -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`int ` -- :ref:`unsigned int ` -- :ref:`unsigned long ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - -.. include:: cc-attribution.txt diff --git a/source/lang/longcast.rst b/source/lang/longcast.rst deleted file mode 100644 index 2b92345..0000000 --- a/source/lang/longcast.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. highlight:: cpp - -.. _lang-longcast: - -``long()`` (cast) -================= - -Converts a value to the :ref:`long ` data type. Here is -an example:: - - double d = 2.5; - long i = long(d); // i holds "2L", an long value - -The value inside of the parentheses (``long(...)``) can be of any type. -However, if it is not a numeric type (like ``double``, ``char``, -etc.), you will get strange results. - -See the :ref:`long ` reference for details about the -precision and limitations of ``long`` variables on the Maple. - -See Also --------- - -- :ref:`long ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/loop.rst b/source/lang/loop.rst deleted file mode 100644 index d8f6183..0000000 --- a/source/lang/loop.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. highlight:: cpp - -.. _lang-loop: - -loop() -====== - -After creating a :ref:`setup() ` function, which -initializes your sketch, the ``loop()`` function gets called -repeatedly, allowing your program to change and respond. Use it to -actively control your Maple board. - -Example -------- - -:: - - - int buttonPin = 38; - - // setup initializes serial and the button pin - void setup() { - SerialUSB.begin(); - pinMode(buttonPin, INPUT); - } - - // loop() checks the button pin each time it executes, - // and will print 'H' if it is pressed, 'L' otherwise - void loop() { - if (digitalRead(buttonPin) == HIGH) { - SerialUSB.println('H'); - } else { - SerialUSB.println('L'); - } - - delay(1000); - } - -See Also --------- - -- :ref:`setup() ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/lowbyte.rst b/source/lang/lowbyte.rst deleted file mode 100644 index 58e622f..0000000 --- a/source/lang/lowbyte.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _lang-lowbyte: - -lowByte() -========= - -Extracts the low-order (rightmost) byte of a variable (e.g. a -word). - -Syntax ------- - -lowByte(x) - -Parameters ----------- - -**x**: a value of any type. However, if a non-integral type is used, -the results will be strange. - -Returns -------- - -The low byte's value (this will be between 0 and 255). - -.. include:: cc-attribution.txt diff --git a/source/lang/map.rst b/source/lang/map.rst deleted file mode 100644 index 79122b3..0000000 --- a/source/lang/map.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. highlight:: cpp - -.. _lang-map: - -map() -===== - -Re-maps a number from one range to another. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: map - -Discussion ----------- - -``map()`` does not constrain values to within the range, because -out-of-range values are sometimes intended and useful. The -:ref:`constrain() ` macro may be used either before or -after this function, if limits to the ranges are desired. - -Note that the "lower bounds" of either range may be larger or smaller -than the "upper bounds" so that ``map()`` may be used to reverse a -range of numbers; for example:: - - y = map(x, 1, 50, 50, 1); - -The function also handles negative numbers well, so that this -example :: - - y = map(x, 1, 50, 50, -100); - -is also valid. - -The ``map()`` function uses integer math (its arguments and return -values all have type :ref:`long `), so it will not generate -fractions, when the math might indicate that it should do so. -Fractional remainders are truncated, and are not rounded or averaged. - -Example -------- - -:: - - /* Map an ADC reading (12 bits) to 16-bit PWM (0 to 65,535) */ - - void setup() { - pinMode(0, INPUT_ANALOG); - pinMode(9, PWM); - } - - void loop() { - int val = analogRead(0); - val = map(val, 0, 4095, 0, 65535); - analogWrite(9, val); - } - - -See Also --------- - -- :ref:`constrain() ` - -.. include:: cc-attribution.txt diff --git a/source/lang/max.rst b/source/lang/max.rst deleted file mode 100644 index d38eebe..0000000 --- a/source/lang/max.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. highlight:: cpp - -.. _lang-max: - -max() -===== - -(Macro) Calculates the maximum of two numbers. - -Syntax ------- - -:: - - max(x, y) - -Parameters ----------- - -**x**: the first number; may be any number or numeric expression. - -**y**: the second number; may be any number or numeric expression. - - -Returns -------- - -The larger of the two parameter values. - -Example -------- - -:: - - sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 - // (effectively ensuring that it is at least 20) - -.. note:: Perhaps counter-intuitively, max() is often used to - constrain the lower end of a variable's range, while :ref:`min() - ` is used to constrain the upper end of the range. - -Warning -------- - -Because of the way ``max()`` is implemented, avoid using other -functions inside the parentheses. It may lead to incorrect results:: - - max(a--, 0); // avoid this - yields incorrect results - - a--; // use this instead - - max(a, 0); // keep other operations outside max() - -Arduino Compatibility ---------------------- - -The Maple version of ``max()`` is compatible with Arduino. - -See Also --------- - -- :ref:`min() ` -- :ref:`constrain() ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/micros.rst b/source/lang/micros.rst deleted file mode 100644 index f12976b..0000000 --- a/source/lang/micros.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. highlight:: cpp - -.. _lang-micros: - -micros() -======== - -Returns the number of microseconds since the Maple board began running -the current program. This number will overflow (go back to zero), -after approximately 70 minutes. - -.. note:: There are 1,000 microseconds in a millisecond, and 1,000,000 - microseconds in a second. - -Library Documentation ---------------------- - -.. doxygenfunction:: micros - -Example -------- - -:: - - unsigned int time; - - void setup() { - } - - void loop() { - SerialUSB.print("Time: "); - time = micros(); - // prints time since program started - SerialUSB.println(time); - // wait a second so as not to send massive amounts of data - delay(1000); - } - -See Also --------- - -- :ref:`millis() ` -- :ref:`delay() ` -- :ref:`delayMicroseconds() ` - -.. include:: cc-attribution.txt diff --git a/source/lang/millis.rst b/source/lang/millis.rst deleted file mode 100644 index 54e4507..0000000 --- a/source/lang/millis.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _lang-millis: - -millis() -======== - -Returns the number of milliseconds since the Maple board began running -the current program. This number will overflow (go back to zero) after -approximately 50 days. - -Library Documentation ---------------------- - -.. doxygenfunction:: millis - -Example -------- - -The following time prints the value returned by ``millis()`` roughly -once per second:: - - unsigned int time; - - void setup() { - } - - void loop() { - SerialUSB.print("Time: "); - time = millis(); - // prints time since program started - Serial.println(time); - - // wait a second so as not to send massive amounts of data - delay(1000); - } - -Tip ---- - -Since the return value for ``millis()`` is an :ref:`unsigned long -`, overflow errors may occur if you try to do math -with other data types, such as :ref:`ints `. - -See Also --------- - -- :ref:`micros ` -- :ref:`delay ` -- :ref:`delayMicroseconds ` - -.. include:: cc-attribution.txt diff --git a/source/lang/min.rst b/source/lang/min.rst deleted file mode 100644 index 1245f6f..0000000 --- a/source/lang/min.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. highlight:: cpp - -.. _lang-min: - -min() -===== - -(Macro) Calculates the minimum of two numbers. - -Syntax ------- - -:: - - min(x,y) - -Parameters ----------- - -**x**: the first number; may be any number or numeric expression. - -**y**: the second number; may be any number or numeric expression. - -Returns -------- - -The smaller of the two numbers. - -Example -------- - -:: - - sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 - // ensuring that it never gets above 100. - - -.. note:: Perhaps counter-intuitively, max() is often used to - constrain the lower end of a variable's range, while min() is used - to constrain the upper end of the range. - - -Warning -------- - -Because of the way ``min()`` is implemented, avoid using other -functions inside the parentheses. It may lead to incorrect results:: - - min(a++, 100); // avoid this - yields incorrect results - - a++; // use this instead - - min(a, 100); // keep other operations outside min() - -Arduino Compatibility ---------------------- - -The Maple version of ``min()`` is compatible with Arduino. - -See Also --------- - -- :ref:`max() ` -- :ref:`constrain() ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/modulo.rst b/source/lang/modulo.rst deleted file mode 100644 index 289fba0..0000000 --- a/source/lang/modulo.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. highlight:: cpp - -.. _lang-modulo: - -Modulo Operator (``%``) -======================= - -Calculates the `remainder `_ -when one integer is divided by another. It is useful for keeping a -variable within a particular range (e.g. the size of an array). - -Syntax ------- - -:: - - dividend % divisor - -Parameters ----------- - -**dividend**: the number to be divided - -**divisor**: the number to divide by - -Returns -------- - -The remainder of **dividend**\ /\ **divisor**\ . - -Examples --------- - -:: - - int x; - x = 7 % 5; // x now contains 2 - x = 9 % 5; // x now contains 4 - x = 5 % 5; // x now contains 0 - x = 4 % 5; // x now contains 4 - -:: - - /* update one value in an array each time through a loop */ - - int values[10]; - int i = 0; - - void setup() { - // no setup necessary - } - - void loop() { - values[i] = analogRead(0); - i = (i + 1) % 10; // modulo operator makes sure i stays between 0 and 9 - } - -Tip ---- - -The modulo operator does not work on floats. For that, you can use -the C standard library function `fmod() -`_. - -See Also --------- - -- :ref:`Arithmetic ` - -.. include:: cc-attribution.txt diff --git a/source/lang/numeric-types.rst b/source/lang/numeric-types.rst deleted file mode 100644 index 9d2be48..0000000 --- a/source/lang/numeric-types.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _lang-numeric-types: - -Numeric types -============= - -This document serves as a reference for all of the built-in numeric -types which are available when programming in the IDE. Programmers -using the :ref:`command-line tools ` will have access -to these types as long as they have imported ``wirish.h``; several are -defined in in `libmaple_types.h -`_. - -.. _lang-numeric-types-integral: - -Integral types --------------- - -.. cpp:type:: char - - 8-bit integer value. - -.. cpp:type:: short - - 16-bit integer value. - -.. cpp:type:: int - - 32-bit integer value. - -.. cpp:type:: long - - 64-bit integer value. - -.. cpp:type:: long long - - 64-bit integer value. - -.. cpp:type:: int8 - - Synonym for ``char``. - -.. cpp:type:: uint8 - - Synonym for ``unsigned char``. - -.. cpp:type:: int16 - - Synonym for ``short``. - -.. cpp:type:: uint16 - - Synonym for ``unsigned short``. - -.. cpp:type:: int32 - - Synonym for ``int``. - -.. cpp:type:: uint32 - - Synonym for ``unsigned int`` - -.. cpp:type:: int64 - - Synonym for ``long long`` - -.. cpp:type:: uint64 - - Synonym for ``unsigned long long``. - -Floating-Point Types --------------------- - -.. cpp:type:: float - - 32-bit, IEEE 754 single-precision floating-point type. - -.. cpp:type:: double - - 64-bit, IEEE 754 double-precision floating-point type. diff --git a/source/lang/pinmode.rst b/source/lang/pinmode.rst deleted file mode 100644 index b9095da..0000000 --- a/source/lang/pinmode.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. highlight:: cpp - -.. _lang-pinmode: - -pinMode() -========= - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: pinMode - -.. doxygenenum:: WiringPinMode - -Discussion ----------- - -``pinMode()`` is usually called within :ref:`lang-setup` in order to -configure a pin for a certain usage (although it may be called -anywhere). - -Example -------- - -:: - - int ledPin = 13; // LED connected to digital pin 13 - - void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output - } - - void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second - } - -Arduino Compatibility ---------------------- - -.. TODO check out Arduino vs. Maple static discilpline cutoffs to -.. ensure accuracy of following: - -The libmaple implementation of ``pinMode()`` supports the ``INPUT`` -and ``OUTPUT`` modes with semantics identical to that of the Arduino -function (however, be advised that the Maple, as a 3.3V device, will -only drive 3.3V to an ``OUTPUT`` pin that has been set ``HIGH``). - -``INPUT_ANALOG`` and ``PWM`` modes were added because the Maple does -not distinguish between analog and digital pins the same way the -Arduino does. Unlike the Arduino, you **must call** ``pinMode()`` to -set up a pin for these purposes before a call to, e.g., -:ref:`lang-analogRead`. In practice, this should only add a few lines -to your :ref:`lang-setup` function. - -.. TODO verify following before putting it in: - -.. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and -.. ``PWM_OPEN_DRAIN`` modes represent functionality not currently -.. available on Arduino boards. - -See also --------- - -- :ref:`lang-constants` -- :ref:`lang-digitalwrite` -- :ref:`lang-digitalread` -- Maple :ref:`GPIO ` reference page - - - -.. include:: cc-attribution.txt diff --git a/source/lang/pointer.rst b/source/lang/pointer.rst deleted file mode 100644 index 0a42270..0000000 --- a/source/lang/pointer.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _lang-pointer: - -Pointer Operators (``&``, ``*``) -================================ - -The pointer operators ``&`` (reference) and ``*`` (dereference) are -different from the bitwise math operator :ref:`& -` and the arithmetic operator :ref:`* -`. - -Pointers are one of the more complicated subjects for beginners in -learning C, and it is possible to write many useful Arduino sketches -without ever encountering pointers. However, for manipulating certain -data structures, the use of pointers can simplify the code, improve -its efficiency, and generally provide many benefits that would be -difficult to achieve without the use of pointers. - -Introducing pointers is somewhat outside the scope of this -documentation. However, a good `pointer tutorial -`_ is available. -Also see the `Wikipedia article on pointers -`_, especially -the section on `pointers in C -`_. - -See Also --------- - -- http://xkcd.com/138/ - -.. include:: cc-attribution.txt diff --git a/source/lang/pow.rst b/source/lang/pow.rst deleted file mode 100644 index 4280400..0000000 --- a/source/lang/pow.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _lang-pow: - -pow() -===== - -Calculates the value of a number raised to a power. - -Library Documentation ---------------------- - -.. doxygenfunction:: pow - -.. TODO LATER some examples - -See Also --------- - -- :ref:`sqrt() ` -- :ref:`float ` -- :ref:`double ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/pwmwrite.rst b/source/lang/pwmwrite.rst deleted file mode 100644 index 7a1d51f..0000000 --- a/source/lang/pwmwrite.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. highlight:: cpp - -.. _lang-pwmwrite: - -pwmWrite() -========== - -Writes a :ref:`PWM wave ` to a pin. You can use this to make an -LED get brighter or dimmer, control a servomotor, etc. After a call to -pwmWrite(), the pin will output a steady square wave with the given -duty cycle. You can change the duty cycle later by calling pwmWrite() -again with the same pin and a different duty. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: pwmWrite - -Example -------- - -Sets the output to the LED proportional to the value read from the -potentiometer:: - - int ledPin = 13; // LED connected to pin 13 (Maple) - int analogPin = 3; // potentiometer connected to analog pin 3 - int val = 0; // variable to store the read value - - void setup() { - pinMode(ledPin, OUTPUT); // sets the LED pin as output - - pinMode(analogPin, PWM); // sets the potentiometer pin as PWM - // output - } - - void loop() { - val = analogRead(analogPin); // read the input pin - - analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, - // analogWrite values from 0 to 65535 - } - -See Also --------- - -- :ref:`Maple PWM tutorial ` diff --git a/source/lang/random.rst b/source/lang/random.rst deleted file mode 100644 index f2a9762..0000000 --- a/source/lang/random.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. highlight:: cpp - -.. _lang-random: - -random() -======== - -The ``random()`` function generates pseudo-random numbers. - -.. TODO keep tracking Sphinx/Breathe's ability to reference overloaded -.. functions so we can use doxygenfunction instead of manually -.. documenting this. - -Library Documentation ---------------------- - -.. cpp:function:: random(long max) - - Same as a call to ``random(0, max)``. - -.. cpp:function:: random(long min, long max) - - Generate a pseudo-random number with given lower and upper bounds. - - *Parameters* - - - ``min`` - Lower bound on the returned value, inclusive - - ``max`` - Upper bound on the returned value, exclusive - - *Returns*: A pseudo-random number in the range [min, max). - -Discussion ----------- - -If it is important for a sequence of values generated by -:ref:`random() ` to differ, on subsequent executions of a -sketch, use :ref:`randomSeed() ` to initialize the -random number generator with a fairly random input, such as -:ref:`analogRead() ` on an unconnected pin. - -Conversely, it can occasionally be useful to use pseudorandom -sequences that repeat exactly. This can be accomplished by calling -``randomSeed()`` with a fixed number, before starting the random -sequence. - -Example -------- - -The following sketch initializes the random seed based on an :ref:`ADC -` reading of pin 0. If this pin is unconnected, the Sketch -should print different values to the :ref:`serial monitor -` each time it is run:: - - long randNumber; - - void setup() { - pinMode(0, INPUT_ANALOG); - randomSeed(analogRead(0)); - } - - void loop() { - randNumber = random(300); - SerialUSB.println(randNumber); - - delay(50); - } - -See Also --------- - -- :ref:`randomSeed() ` - -.. include:: cc-attribution.txt diff --git a/source/lang/randomseed.rst b/source/lang/randomseed.rst deleted file mode 100644 index d0a15b7..0000000 --- a/source/lang/randomseed.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. highlight:: cpp - -.. _lang-randomseed: - -randomSeed() -============ - -``randomSeed()`` initializes the `pseudorandom number generator -`_, -causing it to start at an arbitrary point in its random sequence. -This sequence, while very long, and random, is always the same. - - -Library Documentation ---------------------- - -.. doxygenfunction:: randomSeed - -Discussion ----------- - -If it is important for a sequence of values generated by -:ref:`random() ` to differ, on subsequent executions of a -sketch, use ``randomSeed()`` to initialize the random number generator -with a fairly random input, such as :ref:`analogRead() -` on an unconnected pin. - -Conversely, it can occasionally be useful to use pseudorandom -sequences that repeat exactly. This can be accomplished by calling -``randomSeed()`` with a fixed number, before starting the random -sequence. - -Example -------- - -The following sketch initializes the random seed based on an :ref:`ADC -` reading of pin 0. If this pin is unconnected, the Sketch -should print different values to the :ref:`serial monitor -` each time it is run:: - - long randNumber; - - void setup() { - pinMode(0, INPUT_ANALOG); - randomSeed(analogRead(0)); - } - - void loop() { - randNumber = random(300); - SerialUSB.println(randNumber); - - delay(50); - } - -See Also --------- - -- :ref:`random() ` - -.. include:: cc-attribution.txt diff --git a/source/lang/return.rst b/source/lang/return.rst deleted file mode 100644 index 7b5039e..0000000 --- a/source/lang/return.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. highlight:: cpp - -.. _lang-return: - -``return`` -========== - -Terminates a function and return a value from a function to the -calling function, if the function has non-``void`` return type. - -Syntax: -------- - -:: - - // from within a "void" function: - return; - - // from within a non-"void" function: - return value; - -In the second case, ``value`` should have a type which is the same as -the return type of the function, or be convertible to it (like an -``int`` to a ``long``, etc.; see :ref:`this note -` for some references). - -Examples: ---------- - -A function to compare a sensor input to a threshold:: - - // converts analog readings between 0 and 400 to 0, and 400 up to 1. - int checkSensor() { - if (analogRead(0) > 400) { - return 1; - else { - return 0; - } - } - -An early ``return`` is also useful when testing a section of code -without having to "comment out" large sections of possibly buggy code, -like so:: - - void loop() { - - // brilliant code idea to test here - - return; - - // the rest of a dysfunctional sketch here - // this code will never be executed - } - -See Also --------- - -- :ref:`comments ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/scope.rst b/source/lang/scope.rst deleted file mode 100644 index 7b65bab..0000000 --- a/source/lang/scope.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. highlight:: cpp - -.. _lang-scope: - -Scope -===== - -Variables in the C++ programming language, which Maple uses (all of -your sketches are C++ programs in disguise), have a property called -*scope*. Simply put, a variable's scope is made up of all of the -lines where the variable can be used. - -Scope in C++ is a fairly complex topic, so we won't try to describe it -in full here. Instead, we present a simplified view, describing two -different kinds of scopes, *global* and *local*. For more detailed -information, consult a C++ reference. - -Global and Local Variables --------------------------- - -A global variable is one that can be "seen" by every function in a -program. In the :ref:`Maple IDE `, any variable declared outside -of a function (like :ref:`setup() ` and :ref:`loop() -`) is a global variable. - -A local variable can only be "seen" inside of a particular function. -You can declare a variable to be local to a function by declaring it -inside of the :ref:`curly braces ` which enclose -that function. - -When programs start to get larger and more complex, local variables -are a useful way to ensure that a function has exclusive access to its -own variables. This prevents programming errors when one function -mistakenly modifies variables used by another function. - -It is also sometimes useful to declare and initialize a variable -inside a :ref:`for ` loop. This creates a variable that -can only be accessed from inside the loop body. - -Example -------- - -Here is an example sketch (which you can copy into the Maple IDE and -run on your Maple) that illustrates the use of global and local -variables, as well as declaring variables inside of a ``for`` loop. -Be sure to open a :ref:`serial monitor ` after you -:ref:`verify ` and :ref:`upload ` the sketch:: - - int globalVar; // any function will see this variable - - void setup() { - // since "globalVar" is declared outside of any function, - // every function can "see" and use it: - globalVar = 50; - - // the variables "i" and "d" declared inside the "loop" function - // can't be seen here. see what happens when you uncomment the - // following lines, and try to Verify (compile) the sketch: - // - // i = 16; - // SerialUSB.print("i = "); - // SerialUSB.println(i); - // d = 26.5; - // SerialUSB.print("d = "); - // SerialUSB.println(d); - } - - void loop() { - // since "i" and "d" are declared inside of the "loop" function, - // they can only be seen and used from inside of it: - int i; - double d; - - for (int j = 0; j < 5; j++) { - // variable i can be used anywhere inside the "loop" function; - // variable j can only be accessed inside the for-loop brackets: - i = j * j; - SerialUSB.print("i = "); - SerialUSB.println(i); - } - - // globalVar can be accessed from anywhere. note how even - // though we set globalVar = 50 in the "setup" function, we can - // see that value here: - SerialUSB.print("globalVar = "); - SerialUSB.println(globalVar); - - // d can be accessed from anywhere inside the "loop" function: - d = 26.5; - SerialUSB.print("d = "); - SerialUSB.print(d); - SerialUSB.println(" (before separateFunction())"); - - separateFunction(); - - // notice how even though separateFunction() has a variable - // named "d", it didn't touch our (local) variable which has - // the same name: - SerialUSB.print("d = "); - SerialUSB.print(d); - SerialUSB.println(" (after separateFunction())"); - } - - void separateFunction() { - // variable "d" here has the same name as variable "d" inside of - // the "loop" function, but since they're both _local_ - // variables, they don't affect each other: - double d = 30.5; - SerialUSB.print("d = "); - SerialUSB.print(d); - SerialUSB.println(" (inside of separateFunction())"); - } - -See Also --------- - -- `C++ programming Wikibook `_. -- Wikipedia article on `scope `_ - -.. include:: cc-attribution.txt diff --git a/source/lang/semicolon.rst b/source/lang/semicolon.rst deleted file mode 100644 index 8164616..0000000 --- a/source/lang/semicolon.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. highlight:: cpp - -.. _lang-semicolon: - -Semicolon (``;``) -================= - -Used to end a line of code. Example:: - - int a = 13; - -Tip ---- - -Forgetting to end a line in a semicolon will result in a compiler -error. The error text may be obvious, and refer to a missing -semicolon, or it may not. If an impenetrable or seemingly illogical -compiler error comes up, one of the first things to check is a -missing semicolon, in the immediate vicinity, preceding the line at -which the compiler complained. - - - - -.. include:: cc-attribution.txt diff --git a/source/lang/serial.rst b/source/lang/serial.rst deleted file mode 100644 index ca89b31..0000000 --- a/source/lang/serial.rst +++ /dev/null @@ -1,226 +0,0 @@ -.. _lang-serial: - -Serial Ports (``Serial1``, ``Serial2``, ``Serial3``) -==================================================== - -Used for communication between the Maple board and a computer or other -devices. - -.. contents:: Contents - :local: - -Introduction ------------- - -The Maple has three serial ports (also known as a UARTs or USARTs): -``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the -pins summarized in the following table: - -.. list-table:: - :header-rows: 1 - - * - Serial port - - TX, RX, CK - - CTS, RTS (if present) - - * - ``Serial1`` - - 7, 8, 6 - - - - * - ``Serial2`` - - 1, 0, 10 - - 2, 3 - - * - ``Serial3`` - - 29, 30, 31 - - 32, 33 - -Thus, if you use a particular serial port, you cannot also use its -communication pins for other purposes at the same time. - -If you want to communicate with the Maple using the provided USB port, -use :ref:`SerialUSB ` instead. - -To use them to communicate with an external TTL serial device, connect -the TX pin to your device's RX pin, the RX to your device's TX pin, -and the ground of your Maple to your device's ground. - -.. warning:: Don't connect these pins directly to an RS232 serial - port; they operate at +/- 12V and can damage your board. - - -Library Documentation ---------------------- - -All of the ``Serial[1,2,3]`` objects are instances of the -``HardwareSerial`` class, which is documented in this section. (This -means that you can use any of these functions on any of ``Serial1``, -``Serial2``, and ``Serial3``). - -.. cpp:class:: HardwareSerial - - Serial port class. Predefined instances are ``Serial1``, - ``Serial2``, and ``Serial3``. - -.. cpp:function:: HardwareSerial::begin(unsigned int baud) - - Set up a ``HardwareSerial`` object for communications. This method - must be called before attempting to use the ``HardwareSerial`` - object (typically, you call this in your :ref:`setup() - ` function). - -.. cpp:function:: HardwareSerial::end() - - Disables the USART associated with this object, allowing any - associated communication pins to be used for other purposes. - -.. cpp:function:: unsigned int HardwareSerial::available() - - Returns the number of bytes available for reading. - -.. cpp:function:: unsigned char HardwareSerial::read() - - Returns the next available, unread character. If there are no - available characters (you can check this with :cpp:func:`available - `), the call will block until one - becomes available. - -.. cpp:function:: HardwareSerial::flush() - - Removes the contents of the Serial's associated USART RX FIFO. - That is, clears any buffered characters, so that the next character - read is guaranteed to be new. - -.. cpp:function:: HardwareSerial::print(unsigned char b) - - Print the given byte over the USART. - -.. cpp:function:: HardwareSerial::print(char c) - - Print the given character over the USART. 7-bit clean characters - are typically interpreted as ASCII text. - -.. cpp:function:: HardwareSerial::print(const char *str) - - Print the given null-terminated string over the USART. - -.. cpp:function:: HardwareSerial::print(int n) - - Print the argument's digits over the USART, in decimal format. - Negative values will be prefixed with a ``'-'`` character. - -.. cpp:function:: HardwareSerial::print(unsigned int n) - - Print the argument's digits over the USART, in decimal format. - -.. cpp:function:: HardwareSerial::print(long n) - - Print the argument's digits over the USART, in decimal format. - Negative values will be prefixed with a ``'-'`` character. - -.. cpp:function:: HardwareSerial::print(unsigned long n) - - Print the argument's digits over the USART, in decimal format. - -.. cpp:function:: HardwareSerial::print(long n, int base) - - Print the digits of ``n`` over the USART, in base ``base`` (which - may be between 2 and 16). The ``base`` value 2 corresponds to - binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative - values will be prefixed with a ``'-'`` character. - -.. cpp:function:: HardwareSerial::print(double n) - - Print ``n``, accurate to 2 digits after the decimal point. - -.. _lang-serial-println: - -.. cpp:function:: HardwareSerial::println(char c) - - Like ``print(c)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(const char *c) - - Like ``print(c)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(unsigned char b) - - Like ``print(b)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(int n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(unsigned int n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(long n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(unsigned long n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(long n, int base) - - Like ``print(n, b)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(double n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println() - - Prints ``"\r\n"`` over the USART. - -.. cpp:function:: HardwareSerial::write(unsigned char ch) - - Sends one character over the USART. This function is currently - blocking, although nonblocking writes are a planned future - extension. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -.. cpp:function:: HardwareSerial::write(const char* str) - - Send the given null-terminated character string over the USART. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -.. cpp:function:: HardwareSerial::write(void *buf, unsigned int size) - - Writes the first ``size`` bytes of ``buf`` over the USART. Each - byte is transmitted as an individual character. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -Arduino Compatibility Note --------------------------- - -Unlike the Arduino, none of the Maple's serial ports is connected to -the USB port on the Maple board (for that, use :ref:`SerialUSB -`). Thus, to use these pins to communicate with your -personal computer, you will need an additional USB-to-serial adaptor. - -.. TODO LATER port these examples over - -.. Examples -.. -------- - -.. - `ASCII Table `_ -.. - `Dimmer `_ -.. - `Graph `_ -.. - `Physical Pixel `_ -.. - `Virtual Color Mixer `_ -.. - `Serial Call Response `_ -.. - `Serial Call Response ASCII `_ - -.. include:: cc-attribution.txt diff --git a/source/lang/serialusb.rst b/source/lang/serialusb.rst deleted file mode 100644 index af3a7e0..0000000 --- a/source/lang/serialusb.rst +++ /dev/null @@ -1,242 +0,0 @@ -.. highlight:: cpp - -.. _lang-serialusb: - -``SerialUSB`` -============= - -Used for communication between the Maple board and a computer. - -.. contents:: Contents - :local: - -Introduction ------------- - -In addition to three :ref:`serial ports `, the Maple's -STM32 microprocessor includes a dedicated USB peripheral. This -peripheral is used to emulate a regular serial port for use as a -terminal (text read/write). The emulated terminal is relatively slow -and inefficient; it is best for transferring data at regular serial -speeds (kilobaud). - -Library access to the emulated serial port is provided through the -``SerialUSB`` object. You can mostly use ``SerialUSB`` as a drop-in -replacement for ``Serial1``, ``Serial2``, and ``Serial3``. - -.. warning:: The ``SerialUSB`` functionality includes a 50 millisecond - timeout for writes, and does not try to detect if the USB host is - "really" connected, or just enumerated and initialized. - - This means that if you have a number of calls to one of the - ``SerialUSB`` ``write()`` or ``print()`` functions in your code, - and you are not monitoring the emulated on a computer, your program - will run much, much slower than if it is being monitored or totally - disconnected (run off of a battery). - - You can avoid this behavior by :ref:`deciphering the port status - using the DTR and RTS line status `; the - behavior of these control lines is platform dependent and we no - longer interpret them by default. - -Library Documentation ---------------------- - -The ``SerialUSB`` object is an instance of the ``USBSerial`` class, -which is documented in this section. This means that you can use any -of these functions by writing -``SerialUSB.functionName(arguments...)``. For example, to print the -message "hello, world!", you can write ``USBSerial.println("hello, -world!")``. - -.. cpp:class:: USBSerial - - Emulated serial-over-USB class. ``SerialUSB`` is the predefined - instance. - -.. cpp:function:: USBSerial::begin() - - Set up the USB peripheral for emulated serial communication. The - peripheral is configured this way by default; calling this function - should only be necessary if you have disabled the peripheral using - ``SerialUSB.end()``. - -.. _lang-serialusb-end: - -.. cpp:function:: USBSerial::end() - - Disables the USB peripheral. - -.. cpp:function:: unsigned int USBSerial::available() - - Returns the number of bytes available for reading. - -.. _lang-serialusb-read: - -.. cpp:function:: unsigned char USBSerial::read() - - Returns the next available, unread character. If there are no - available characters (you can check this with :cpp:func:`available - `), the call will block until one - becomes available. - -.. cpp:function:: USBSerial::flush() - - Removes the contents of the Serial's associated input buffer. That - is, clears any buffered characters, so that the next character read - is guaranteed to be new. - -.. cpp:function:: USBSerial::print(unsigned char b) - - Print the given byte over the USB connection. - -.. cpp:function:: USBSerial::print(char c) - - Print the given character over the USB connection. 7-bit clean characters - are typically interpreted as ASCII text. - -.. cpp:function:: USBSerial::print(const char *str) - - Print the given null-terminated string over the USB connection. - -.. cpp:function:: USBSerial::print(int n) - - Print the argument's digits over the USB connection, in decimal format. - Negative values will be prefixed with a ``'-'`` character. - -.. cpp:function:: USBSerial::print(unsigned int n) - - Print the argument's digits over the USB connection, in decimal format. - -.. cpp:function:: USBSerial::print(long n) - - Print the argument's digits over the USB connection, in decimal - format. Negative values will be prefixed with a ``'-'`` character. - -.. cpp:function:: USBSerial::print(unsigned long n) - - Print the argument's digits over the USB connection, in decimal - format. - -.. cpp:function:: USBSerial::print(long n, int base) - - Print the digits of ``n`` over the USB connection, in base ``base`` - (which may be between 2 and 16). The ``base`` value 2 corresponds - to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. - Negative values will be prefixed with a ``'-'`` character. - -.. cpp:function:: USBSerial::print(double n) - - Print ``n``, accurate to 2 digits after the decimal point. - -.. _lang-serialusb-println: - -.. cpp:function:: USBSerial::println(char c) - - Like ``print(c)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(const char *c) - - Like ``print(c)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(unsigned char b) - - Like ``print(b)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(int n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(unsigned int n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(long n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(unsigned long n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(long n, int base) - - Like ``print(n, b)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(double n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println() - - Prints ``"\r\n"`` over the USB connection. - -.. cpp:function:: USBSerial::write(unsigned char ch) - - Sends one character over the USB connection. This function is - currently blocking, although nonblocking writes are a planned - future extension. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -.. cpp:function:: USBSerial::write(const char* str) - - Send the given null-terminated character string over the USB - connection. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -.. cpp:function:: USBSerial::write(void *buf, unsigned int size) - - Writes the first ``size`` bytes of ``buf`` over the USB connection. - Each byte is transmitted as an individual character. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -Examples --------- - -.. _lang-serialusb-safe-print: - -**Safe print**: This function should run smoothly and not block; the -LED should blink at roughly the same speed whether being monitored, -running from battery, or connected but not monitored. You may need to -experiment with the DTR/RTS logic for your platform and device -configuration. :: - - #define LED_PIN 13 - - void setup() { - /* Set up the LED to blink */ - pinMode(LED_PIN, OUTPUT); - } - - void loop() { - // LED will stay off if we are disconnected; - // will blink quickly if USB is unplugged (battery etc) - if(SerialUSB.isConnected()) { - digitalWrite(LED_PIN, 1); - } - delay(100); - - // If this logic fails to detect if bytes are going to - // be read by the USB host, then the println() will fully - // many times, causing a very slow LED blink. - // If the characters are printed and read, the blink will - // only slow a small amount when "really" connected, and fast - // when the virtual port is only configured. - if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) { - for(int i=0; i<10; i++) { - SerialUSB.println(123456,BIN); - } - } - digitalWrite(LED_PIN, 0); - delay(100); - } - diff --git a/source/lang/setup.rst b/source/lang/setup.rst deleted file mode 100644 index 837ddd6..0000000 --- a/source/lang/setup.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. highlight:: cpp - -.. _lang-setup: - -setup() -======= - -The ``setup()`` function is called when a sketch starts. Use it to -initialize :ref:`variables `, :ref:`pin modes -`, start using :ref:`libraries `, etc. The -``setup()`` function will only run once, after each power-up or reset -of the Maple board. - -Example -------- - -:: - - int buttonPin = 38; - - void setup() { - pinMode(buttonPin, INPUT); - } - - void loop() { - // ... - } - -.. include:: cc-attribution.txt diff --git a/source/lang/sin.rst b/source/lang/sin.rst deleted file mode 100644 index 398b8f3..0000000 --- a/source/lang/sin.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _lang-sin: - -sin() -===== - -Calculates the `sine `_ of an -angle. - -Library Documentation ---------------------- - -.. doxygenfunction:: sin - -Arduino Compatibility ---------------------- - -The Maple version of ``sin()`` is compatible with Arduino. - -Note that the Maple implementation comes from `newlib -`_\ , while Arduino's is that of -`avr-libc `_\ . - -See Also --------- - -- :ref:`cos ` -- :ref:`tan ` -- :ref:`float ` -- :ref:`double ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/sizeof.rst b/source/lang/sizeof.rst deleted file mode 100644 index eae509c..0000000 --- a/source/lang/sizeof.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. highlight:: cpp - -.. _lang-sizeof: - -``sizeof()`` -============ - -The ``sizeof`` operator on the Maple returns the number of bytes -needed to store a value of a given type\ [#fcharsize]_. This can be -an ordinary numeric type, like ``int``. It can be something more -complicated, like a ``struct`` or ``union``. If the argument to -``sizeof`` is an array, it returns the total number of bytes occupied -by the array. - -The general syntax looks like this:: - - sizeof(type) - sizeof(var) - -Example -------- - -The ``sizeof`` operator is useful for dealing with arrays (such as -strings) where it is convenient to be able to change the size of the -array without breaking other parts of the program. - -This program prints out a text string one character at a time. Try -changing the text phrase:: - - char myStr[] = "this is a test"; - int i; - - void setup() { - Serial.begin(9600); - } - - void loop() { - for (i = 0; i < sizeof(myStr) - 1; i++) { - Serial.print(i, DEC); - Serial.print(" = "); - Serial.println(myStr[i], BYTE); - } - } - - -Note that ``sizeof`` returns the total number of bytes. So for larger -variable types such as ``int``, the :ref:`for loop ` -would look something like this:: - - for (i = 0; i < (sizeof(myInts)/sizeof(int)) - 1; i++) { - // do something with myInts[i] - } - -.. rubric:: Footnotes - -.. [#fcharsize] Technically (and pedantically) speaking, ``sizeof`` - returns a multiple of the number of bits a ``char`` occupies in - memory. However, on the Maple (this goes for most C++ - implementations), a ``char`` occupies 8 bits = 1 byte. All the C++ - standard guarantees, however, is that a ``char`` occupies at - *least* 8 bits. - -.. include:: cc-attribution.txt - diff --git a/source/lang/sq.rst b/source/lang/sq.rst deleted file mode 100644 index bd32648..0000000 --- a/source/lang/sq.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. highlight:: cpp - -.. _lang-sq: - -sq() -==== - -(Macro) computes the square of a number. - -Syntax ------- - -:: - - sq(a) - -Parameters ----------- - -**a**: the number. - -Returns -------- - -**a** squared (**a** × **a**). - -Warning -------- - -Because of the way ``sq()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - b = sq(a++); // avoid this - yields incorrect results - - b = sq(a); // use this instead - - a++; // keep other operations outside sq() - - -Arduino Compatibility ---------------------- - -Maple's implementation of ``sq()`` is compatible with Arduino. - - -.. include:: cc-attribution.txt diff --git a/source/lang/sqrt.rst b/source/lang/sqrt.rst deleted file mode 100644 index 956a754..0000000 --- a/source/lang/sqrt.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _lang-sqrt: - -sqrt() -====== - -Calculates the square root of a number. - -Library Documentation ---------------------- - -.. doxygenfunction:: sqrt - -Arduino Compatibility ---------------------- - -The Maple versino of ``sqrt()`` is compatible with Arduino. - -See Also --------- - -- :ref:`pow ` -- :ref:`sq ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/static.rst b/source/lang/static.rst deleted file mode 100644 index 5d1802e..0000000 --- a/source/lang/static.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. highlight:: cpp - -.. _lang-static: - -``static`` -========== - -The ``static`` keyword can be used to create variables that are -visible to only one function. However, unlike local variables that get -created and destroyed every time a function is called, ``static`` -variables persist beyond the function call, preserving their data -between function calls. - -Variables declared as ``static`` will only be created and initialized -the first time a function is called. - -.. note:: This is only one use of the ``static`` keyword in C++. It - has some other important uses that are not documented here; consult - a reliable C++ reference for details. - -Example -------- - -One use case for ``static`` variables is implementing counters that -last longer than the functions which need them, but shouldn't be -shared to other functions. Here's an example:: - - void setup() { - SerialUSB.begin(); - } - - void loop() { - int reading; - if (timeToReadSensors()) { - reading = readSensors(); - } - // do something with reading - } - - int readSensors() { - static int numSensorReadings = 0; - numSensorReadings++; - if (numSensorReadings % 100 == 0) { - SerialUSB.print("just got to another 100 sensor readings"); - } - return analogRead(...); - } - -In this example, the static variable ``numSensorReadings`` is -initialized to zero the first time ``readSensors()`` is called, and -then incremented, so it starts out at one. Subsequent calls to -``readSensors()`` won't reset ``numSensorReadings`` to zero, because -it was declared ``static``. Thus, ``numSensorReadings`` is a count of -the number of times that ``readSensors()`` has been called. - - -.. include:: cc-attribution.txt diff --git a/source/lang/string.rst b/source/lang/string.rst deleted file mode 100644 index 0a270da..0000000 --- a/source/lang/string.rst +++ /dev/null @@ -1,128 +0,0 @@ -.. highlight:: cpp - -.. _lang-string: - -Strings -======= - -Text strings can be represented in two ways. You can - -1. Use the :ref:`String ` data type, which is -part of the core as of version 0.0.9, or - -2. You can make a string out of an array of type :ref:`char -` and null-terminate it. - -This page describes the second method. - -Examples --------- - -All of the following are valid declarations for strings:: - - char str1[15]; - char str2[6] = {'m', 'a', 'p', 'l', 'e'}; - char str3[6] = {'m', 'a', 'p', 'l', 'e', '\0'}; - char str4[ ] = "maple"; - char str5[6] = "maple"; - char str6[15] = "maple"; - -As you can see, there are several methods available for declaring and -initializing strings: - -- Declare an array of ``char`` without initializing it, as with ``str1``. - -- Declare an array of ``char`` (with one extra ``char``) and the - compiler will add the required null character, as with ``str2``. - -- Explicitly add the null character (``'\0'``), as with ``str3``. - -- Initialize with a string constant in quotation marks (``"..."``); - the compiler will size the array to fit the string constant and a - terminating null character (``str4``). - -- Initialize the array with an explicit size and string constant, - (``str5``). - -- Initialize the array, leaving extra space for a larger string - (``str6``). - -Null Termination ----------------- - -Generally, strings are terminated with a null character (`ASCII -`_ code 0). This allows functions -(like ``SerialUSB.print()``) to tell where the end of a string is. -Otherwise, they would continue reading subsequent bytes of memory that -aren't actually part of the string. - -This means that your string needs to have space for one more character -than the text you want it to contain. That is why ``str2`` and -``str5`` need to be six characters, even though "maple" is only five --- the last position is automatically filled with a NULL -character. ``str4`` will be automatically sized to six characters, one -for the extra null. In the case of ``str3``, we've explicitly included -the null character (written ``'\0'``) ourselves. - -Note that it's possible to have a string without a final null -character (e.g. if you had specified the length of ``str2`` as five -instead of six). This will break most functions that use strings, so -you shouldn't do it intentionally. If you notice something behaving -strangely (operating on characters not in the string), however, this -could be the problem. - -Single quotes or double quotes? -------------------------------- - -Strings are always defined inside double quotes (``"Abc"``) and -characters are always defined inside single quotes (``'A'``). - -Wrapping long strings ---------------------- - -You can wrap long strings like this:: - - char myString[] = "This is the first line" - " this is the second line" - " etcetera"; - -Arrays of Strings ------------------ - -It is often convenient, when working with large amounts of text, -such as a project with an LCD display, to setup an array of -strings. Because strings themselves are arrays, this is in actually -an example of a two-dimensional array. - -In the code below, the asterisk after the datatype char ``char *`` -indicates that this is an array of "pointers". All array names are -actually pointers, so this is required to make an array of arrays. -Pointers are one of the more esoteric parts of C for beginners to -understand, but it isn't necessary to understand pointers in detail to -use them effectively here:: - - char* myStrings[] = {"This is string 1", "This is string 2", - "This is string 3", "This is string 4", - "This is string 5", "This is string 6"}; - - void setup() { - SerialUSB.begin(); - } - - void loop() { - for (int i = 0; i < 6; i++) { - SerialUSB.println(myStrings[i]); - delay(500); - } - } - - -See Also --------- - -- :ref:`array ` -- :ref:`__attribute__ ` -- :ref:`Variables ` - - -.. include:: cc-attribution.txt diff --git a/source/lang/switchcase.rst b/source/lang/switchcase.rst deleted file mode 100644 index b484bc5..0000000 --- a/source/lang/switchcase.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. highlight:: cpp - -.. _lang-switchcase: - -``switch``\ /\ ``case`` -======================= - -Like :ref:`if ` statements, A ``switch`` statement controls -program flow by allowing you to specify different code that should be -executed under various cases. - -The general syntax looks like this:: - - switch (var) { - case val1: - // statements - break; - case val2: - // statements - break; - ... - default: - // statements - } - -Where ``var`` is a variable whose value to investigate, and the -``val1``, ``val2`` after each ``case`` are constant values that -``var`` might be. - -Description ------------ - -A ``switch`` statement compares the value of a variable to the values -specified in ``case`` statements. When a ``case`` statement is found -whose value matches that of the variable, the code in that case -statement is run. - -Here's a more concrete example:: - - switch (var) { - case 1: - doThing1(); - break; - case 2: - doThing2(); - break; - } - afterTheSwitch(); - -In the above example, if ``var == 1``, then the code beginning on the -line after ``case 1`` gets executed. That is, if ``var`` is one, -``doThing1()`` gets called first, and then the ``break`` statement is -executed. - -The ``break`` keyword exits the ``switch`` statement, and is typically -used at the end of each ``case``. Since there is a ``break`` at the -end of ``case 1``, the ``switch`` statement exits, and the next line -to be run is the one which calls ``afterTheSwitch()``. - -Without a ``break``, the ``switch`` statement will continue executing -the following ``case`` expressions ("falling-through") until a -``break`` (or the end of the switch statement) is reached. Let's -pretend the ``switch`` looked like this instead:: - - switch (var) { - case 1: - doThing1(); - // no break statement anymore - case 2: - doThing2(); - break; - } - afterTheSwitch(); - -Now, if ``var`` is one, ``doThing1()`` gets executed like before. -However, without a ``break``, the code would continue to be executed -line-by-line, so ``doThing2()`` would be called next. At this point, -a ``break`` has been reached, so the program continues by calling -``afterTheSwitch()``. This is usually not what you want, which is why -each ``case`` usually has a ``break`` at the end. - -.. _lang-switchcase-default: - -Writing "``default:``" instead of a ``case`` statement allows you to -specify what to do if none of the ``case`` statements matches. Having -a ``default`` is optional (you can leave it out), but if you have one, -it must appear after all of the ``case`` statements. Let's add a -``default`` to the ``switch`` we've been discussing:: - - switch (var) { - case 1: - doThing1(); - break; - case 2: - doThing2(); - break; - default: - doSomethingElse(); - } - afterTheSwitch(); - -If ``var`` is one, then ``doThing1()`` gets called. If ``var`` is -two, ``doThing2()`` gets called. If ``var`` is anything else, -``doSomethingElse()`` gets called. As stated above, a ``default`` is -optional. If you're missing one and none of the ``case`` statements -match, the ``switch`` does nothing at all, as if it weren't there. - -``switch`` statements are often used with an :ref:`enum ` -value as the variable to compare. In this case, you can write down -all of the values the ``enum`` takes as ``case`` statements, and be -sure you've covered all the possibilities. - -See also: ---------- - -- :ref:`if/else ` - -.. include:: cc-attribution.txt diff --git a/source/lang/tan.rst b/source/lang/tan.rst deleted file mode 100644 index 4bbe0db..0000000 --- a/source/lang/tan.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _lang-tan: - -tan() -===== - -Calculates the tangent of an angle. - -Library Documentation ---------------------- - -.. doxygenfunction:: tan - -Arduino Compatibility ---------------------- - -The Maple version of ``tan()`` is compatible with Arduino. - -Note that the Maple implementation comes from `newlib -`_\ , while Arduino's is that of -`avr-libc `_\ . - -See Also --------- - - -- :ref:`sin ` -- :ref:`cos ` -- :ref:`float ` -- :ref:`double ` - -.. include:: cc-attribution.txt diff --git a/source/lang/unsignedchar.rst b/source/lang/unsignedchar.rst deleted file mode 100644 index 5b946ed..0000000 --- a/source/lang/unsignedchar.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. highlight:: cpp - -.. _lang-unsignedchar: - -``unsigned char`` -================= - -An unsigned version of the :ref:`char ` data type. An -``unsigned char`` occupies 1 byte of memory; it stores an integer from -0 to 255. - -Like an :ref:`unsigned int `, an ``unsigned char`` -won't store negative numbers; it is also subject to the same -:ref:`overflow issues ` as any integral data type. - -Example -------- - -:: - - unsigned char c = 240; - -See Also --------- - - -- :ref:`byte ` -- :ref:`int ` -- :ref:`array ` -- :ref:`SerialUSB.println() ` -- :ref:`Serial.println() ` - -.. include:: cc-attribution.txt diff --git a/source/lang/unsignedint.rst b/source/lang/unsignedint.rst deleted file mode 100644 index f6311da..0000000 --- a/source/lang/unsignedint.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. highlight:: cpp - -.. _lang-unsignedint: - -``unsigned int`` -================ - -An ``unsigned int`` (unsigned integer) is the same as an :ref:`int -` in that it stores a 4 byte integer value. However, -Instead of storing both negative and positive numbers, an ``unsigned -int`` can only store nonnegative values, yielding a range of 0 to -4,294,967,295 (the positive value is 2^32 - 1). - -The difference between an ``unsigned int`` and a (signed) ``int`` lies -in the way the highest bit, sometimes referred to as the "sign" bit, -is interpreted. In the case of the Maple ``int`` type (which is -signed), if the high bit is a "1", the number is interpreted as a -negative number, using a technique known as `two's complement math -`_. The -bits in an an ``unsigned int`` are interpreted according to the usual -rules for converting `binary to decimal -`_. - -An ``unsigned int`` is subject to the same :ref:`overflow issues -` as a regular ``int``; the only difference is -that an ``unsigned int`` will "underflow" at 0, and "overflow" at -4,294,967,295. Here is some example code which illustrates this:: - - unsigned int x; - x = 0; - x--; // x now contains 4,294,967,295; rolled over "left to right" - x++; // x now contains 0; rolled over "right to left" - -Here is an example of declaring an ``unsigned int`` variable named -``ledPin``, then giving it value 13:: - - unsigned int ledPin = 13; - -The general syntax for declaring an ``unsigned int`` variable named -``var``, then giving it value ``val``, looks like:: - - unsigned int var = val; - -See Also --------- - -- :ref:`int ` -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`long ` -- :ref:`unsigned long ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - -.. include:: cc-attribution.txt diff --git a/source/lang/unsignedlong.rst b/source/lang/unsignedlong.rst deleted file mode 100644 index 14a4fc3..0000000 --- a/source/lang/unsignedlong.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. highlight:: cpp - -.. _lang-unsignedlong: - -``unsigned long`` -================= - -An unsigned version of the :ref:`long ` data type. An -``unsigned long`` occupies 8 bytes of memory; it stores an integer -from 0 to 2^64-1, which is approximately 1.8×10^19 (18 quintillion, or -18 billion billion). - -Like an :ref:`unsigned int `, an ``unsigned long`` -won't store negative numbers; it is also subject to the same -:ref:`overflow issues ` as any integral data type. - -Here is an example of declaring an ``unsigned long`` variable named -``c``, then giving it value 299,792,458,000,000,000 (see :ref:`integer -constants ` for an explanation of the "L" -at the end of the number):: - - // Speed of light in nanometers per second (approximate). - unsigned long c = 299792458000000000L; - -The general syntax for declaring an ``unsigned long`` variable named -``var``, then giving it value ``val``, looks like:: - - unsigned long var = val; - -See Also --------- - -- :ref:`long ` -- :ref:`int ` -- :ref:`unsigned ` -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - -.. include:: cc-attribution.txt diff --git a/source/lang/variables.rst b/source/lang/variables.rst deleted file mode 100644 index 9094cd5..0000000 --- a/source/lang/variables.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. highlight:: cpp - -.. _lang-variables: - -Variables -========= - -A variable is a way of naming and storing a value for later use by -the program, such as data from a sensor or an intermediate value -used in a calculation. - -.. contents:: Contents - :local: - -.. _lang-variables-declaring: - -Declaring Variables -------------------- - -Before they are used, all variables have to be *declared*. Declaring a -variable means defining its type, giving it a name, and (optionally) -giving it an initial value (this is often referred to as -*initializing* the variable). Variables do not have to be initialized -(given a value) when they are declared, but it is good style to give -them an initial value whenever possible. - -Here is an example of declaring a variable named ``inputVariable1`` -with type :ref:`int ` (the ``int`` type is used to store -integers, like -2, -1, 0, 1, etc.):: - - int inputVariable1; - -In the above declaration, we did not give the variable an initial -value. Here is another example, where we declare an ``int`` variable -named ``inputVariable2``, with an initial value of ``0``:: - - int inputVariable2 = 0; - -The Maple environment comes ready to use with many useful types of -variables. See the :ref:`built-in types ` page -for more information. - -Here are a few examples of declaring variables of different types:: - - int lightSensVal; - char currentLetter; - unsigned long speedOfLight = 186000UL; - char errorMessage = {"choose another option"}; // see string - -Naming Variables ----------------- - -The rules for naming a variable are simple. Names for variables can -contain letters, numbers, and underscores (the underscore is the -:kbd:`_` character), and cannot begin with a number. So -``temperature_reading``, ``tempReading``, ``tempReading1``, and -``tempReading2`` are all valid variable names, but ``4_temp_readings`` -is not, because it begins with a number. - -You cannot choose a name for a variable that is one of the C++ -:ref:`keywords `. - -Variable names are case-sensitive, so "tempreading" and "tempReading" -are different variables. However, it is very bad style to write code -that chooses variables which are the same up to case. - -You should give your variables descriptive names, so as to make your -code more readable. Variable names like ``tiltSensor`` or -``pushButton`` help you (and anyone else reading your code) understand -what the variable represents. Variable names like ``var`` or -``value``, on the other hand, do little to make your code readable. - -.. _lang-variables-scope: - -Variable Scope --------------- - -An important choice that programmers face is where (in the program -text) to declare variables. The specific place that variables are -declared influences how various functions in a program will "see" the -variable. This is called variable *scope*. See the :ref:`scope -reference ` for more information. - -.. _lang-variables-initializing: - -Initializing Variables ----------------------- - -Variables may be *initialized* (assigned a starting value) when they -are declared or not. It is always good programming practice however to -double check that a variable has valid data in it before it is used. -Using a variable before you give it a value is a common source of -bugs. - -.. _lang-variables-rollover: - -Variable Rollover ------------------ - -Every (numeric) type has a valid *range*. The range of a type is the -smallest and largest value that a variable of that type can store. -For example, the :ref:`int ` type has a range of --2,147,483,648 to 2,147,483,647 [#frange]_. - -When variables are made to exceed their range's maximum value, they -"roll over" back to their minimum value. Note that this happens in -both directions. It's like in the game *Pac-Man* -- when Pac-Man goes -past the right edge of the screen, he reappears on the left, and when -he goes past the left side of the screen, he reappears on the right:: - - int x; - x = -2,147,483,648; - x = x - 1; // x now contains -2,147,483,647; rolled over "left to right" - - x = 2,147,483,647; - x = x + 1; // x now contains -2,147,483,648; rolled over "right to left" - -Each numeric type's reference page includes its range. See the -:ref:`built-in types ` reference for links to each -type's reference page. - -Using Variables ---------------- - -Once variables have been declared, they are given values using the -:ref:`assignment operator `, which is a single equals -sign, ``=``. The assignment operator tells the program to store the -value on the right side of the equals sign into the variable on the -left side:: - - inputVariable1 = 7; // sets variable named inputVariable1 to 7 - inputVariable2 = analogRead(2); // sets variable named inputVariable2 to - // the (digitized) input voltage read from - // analog pin #2 - -Once a variable has been set (assigned a value), you can test its -value to see if it meets certain conditions, or you can use its value -directly. For instance, the following code tests whether the -inputVariable2 is less than 100, then sets a delay based on -inputVariable2 (which, at that point, is at least 100):: - - if (inputVariable2 < 100) { - inputVariable2 = 100; - } - - delay(inputVariable2); - -See Also --------- - -- :ref:`lang-scope` -- :ref:`lang-numeric-types` - -.. rubric:: Footnotes - -.. [#frange] This range might seem a little weird at first. The - reasons for this range of values have to do with the fact that an - ``int`` occupies 32 bits of memory, and the facts :: - - 2^31 = -2,147,483,648 - 2^31 - 1 = 2,147,483,647 - - - Why 2^31 instead of 2^32? Well, that has to do with `how ints are - (usually) stored - `_ on computers. - - -.. include:: cc-attribution.txt - diff --git a/source/lang/void.rst b/source/lang/void.rst deleted file mode 100644 index 88bd448..0000000 --- a/source/lang/void.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. highlight:: cpp - -.. _lang-void: - -``void`` -======== - -The ``void`` keyword is used only in function declarations. It -indicates that the function is expected to return no information to -the function from which it was called, or that it expects no arguments -from its caller. - -Example -------- - -:: - - // actions are performed in the functions "setup" and "loop" - // but no information is reported to the larger program - - void setup() { - // ... - } - - void loop() { - // ... - } - -.. TODO doc page on function declaration? - -.. include:: cc-attribution.txt diff --git a/source/lang/volatile.rst b/source/lang/volatile.rst deleted file mode 100644 index 276bb6a..0000000 --- a/source/lang/volatile.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. highlight:: cpp - -.. _lang-volatile: - -``volatile`` -============ - -The ``volatile`` keyword known is a variable *qualifier*. It is -usually used before the datatype of a variable, to modify the way in -which the compiler treats the variable. - -Declaring a variable ``volatile`` is a directive to the compiler. The -compiler is software which translates your C++ code into the machine -code, which are the real instructions for the STM32 chip in the -Maple. (The particular compiler we provide for use with the Maple is a -version of :ref:`GCC `). - -Specifically, it directs the compiler to read the variable's value -fresh every time it is used, rather than "backing up" the value and -reading from its backup copy. (Compilers often "back up" a variable's -value in RAM into a storage location called a *register*; this is done -for efficiency). - -A variable should be declared ``volatile`` whenever its value can be -changed by something beyond the control of the code section in which -it appears, such as an :ref:`external interrupt -`. On the Maple, the only place that this is -likely to occur is in sections of code associated with interrupts. - -Example -------- - -:: - - // toggles LED when interrupt pin changes state - - int pin = 13; - volatile int state = LOW; - - void setup() { - pinMode(pin, OUTPUT); - attachInterrupt(0, blink, CHANGE); - } - - void loop() { - digitalWrite(pin, state); - } - - void blink() { - if (state == HIGH) { - state = LOW; - } else { - // state must be HIGH - state = HIGH; - } - } - -See also --------- - -- :ref:`External Interrupts ` -- :ref:`lang-attachinterrupt` -- :ref:`lang-detachinterrupt` - -.. include:: cc-attribution.txt diff --git a/source/lang/while.rst b/source/lang/while.rst deleted file mode 100644 index 9047d05..0000000 --- a/source/lang/while.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. highlight:: cpp - -.. _lang-while: - -``while`` -========= - -Syntax ------- - -:: - - while (expression) { - // block of code - } - -Description ------------ - -``while`` loops will repeat the statements inside their associated -block of code until the expression inside the parentheses becomes -:ref:`false `. Something must change the tested -expressions' value, or the ``while`` loop will never exit. This could -be in your code, such as an incremented variable, or an external -condition, such as testing a sensor. - -Example -------- - -:: - - var = 0; - while(var < 200) { - // do something repetitive 200 times - var++; - } - -.. include:: cc-attribution.txt -- cgit v1.2.3 From 7f31099eead99718d279d9a4bb543131329891ce Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Dec 2010 01:50:56 -0500 Subject: Finalized 0.0.9 documentation. --- Doxyfile | 11 +- source/_static/img/jtag-wiring.png | Bin 40550 -> 33637 bytes source/bootloader.rst | 710 ++++++++++++++--------------- source/compatibility.rst | 22 +- source/cpp.rst | 13 - source/external-interrupts.rst | 1 - source/gpio.rst | 16 +- source/home.rst | 32 -- source/i2c.rst | 1 - source/index.rst | 20 +- source/jtag.rst | 27 +- source/lang/api/analogread.rst | 35 -- source/lang/api/analogwrite.rst | 50 +- source/lang/api/constants.rst | 23 + source/lang/api/hardwarespi.rst | 152 ++++++ source/lang/api/hardwaretimer.rst | 368 +++++++++++++++ source/lang/api/interrupts.rst | 47 ++ source/lang/api/isbuttonpressed.rst | 17 + source/lang/api/nointerrupts.rst | 47 ++ source/lang/api/pinmode.rst | 2 + source/lang/api/pwmwrite.rst | 15 +- source/lang/api/serialusb.rst | 11 +- source/lang/api/toggleled.rst | 17 + source/lang/api/togglepin.rst | 17 + source/lang/api/waitforbuttonpress.rst | 17 + source/lang/cpp/built-in-types.rst | 95 ++++ source/lang/cpp/keywords.rst | 2 +- source/lang/cpp/numeric-types.rst | 79 ---- source/lang/cpp/variables.rst | 6 +- source/lang/cpp/void.rst | 10 +- source/lang/unimplemented/interrupts.rst | 59 --- source/lang/unimplemented/nointerrupts.rst | 59 --- source/language-index.rst | 40 +- source/language.rst | 233 +++++----- source/libraries.rst | 67 ++- source/libs/servo.rst | 108 +++++ source/pwm.rst | 103 +---- source/spi.rst | 55 +-- source/timers.rst | 231 +++------- source/troubleshooting.rst | 27 +- source/usart.rst | 1 - source/usb.rst | 1 - 42 files changed, 1678 insertions(+), 1169 deletions(-) delete mode 100644 source/cpp.rst delete mode 100644 source/home.rst create mode 100644 source/lang/api/hardwarespi.rst create mode 100644 source/lang/api/hardwaretimer.rst create mode 100644 source/lang/api/interrupts.rst create mode 100644 source/lang/api/isbuttonpressed.rst create mode 100644 source/lang/api/nointerrupts.rst create mode 100644 source/lang/api/toggleled.rst create mode 100644 source/lang/api/togglepin.rst create mode 100644 source/lang/api/waitforbuttonpress.rst create mode 100644 source/lang/cpp/built-in-types.rst delete mode 100644 source/lang/cpp/numeric-types.rst delete mode 100644 source/lang/unimplemented/interrupts.rst delete mode 100644 source/lang/unimplemented/nointerrupts.rst create mode 100644 source/libs/servo.rst diff --git a/Doxyfile b/Doxyfile index 88b8764..3290843 100644 --- a/Doxyfile +++ b/Doxyfile @@ -318,7 +318,7 @@ EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -1335,13 +1335,13 @@ ENABLE_PREPROCESSING = YES # compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. @@ -1369,7 +1369,8 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = __cplusplus +PREDEFINED = ALWAYS_INLINE= \ + __cplusplus # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. @@ -1462,7 +1463,7 @@ HIDE_UNDOC_RELATIONS = YES # toolkit from AT&T and Lucent Bell Labs. The other options in this section # have no effect if this option is set to NO (the default) -HAVE_DOT = YES +HAVE_DOT = NO # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is # allowed to run in parallel. When set to 0 (the default) doxygen will diff --git a/source/_static/img/jtag-wiring.png b/source/_static/img/jtag-wiring.png index 9c63e82..8f31f99 100644 Binary files a/source/_static/img/jtag-wiring.png and b/source/_static/img/jtag-wiring.png differ diff --git a/source/bootloader.rst b/source/bootloader.rst index d42c050..57833ed 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -138,447 +138,447 @@ This time, however, no DFU transaction is initiated, and the bootloader gives way to user code, closing down the DFU pipe and bringing up the USB serial. -.. _bootloader-rev6: - -Maple Rev6 - The Serial Bootloader (Tentative) ----------------------------------------------- - -.. note:: This section documents an in-progress version of the Maple - bootloader. **No Maples yet sold use this bootloader protocol**. - It has not been yet been publicly released, and its interface is - not stable. - -The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac, -but was unsatisfactory on Windows. Unlike the other operating systems, -Windows needed to be manually pointed to both the driver to use for -programming (DFU, via `libusb `_) and the -driver to use for serial communication (usbser.sys, built in to -Windows). Since Maple operates in only one of these modes at a time, -driver installation was unnecessarily complicated. It was necessary to -bring Maple into the correct mode before installing each of the -drivers. Furthermore, because libusb is not bundled with Windows, and -its driver is not signed, Windows 7 users have been forced to -laboriously disable driver signing checks. Finally, Windows hates the -constant switching of the device between Serial and DFU modes (during -programming), and often prompts users to install drivers that are -already installed. We have therefore decided to abandon DFU. - -In our new bootloader scheme, Maple is simply a serial device. -Windows comes bundled with usbser.sys, so no driver signing is -required. The IDE installation process is greatly simplified, there -is no more switching back and forth between "modes", and we can build -in new functionality outside the DFU spec. - -The first incarnation of this serial-only bootloader leaves libmaple -and user code untouched. However, during programming, instead of -calling :command:`dfu-util` to upload code we will now call a newly -written utility script similar to `avr-dude -`_. The high level -operation of the bootloader will remain the same - come on at startup, -wait for an upload operation or timeout, and jump to user code. - -The second version of this bootloader will eliminate this dependence -on resetting and timing out by having the bootloader run in the -background. It will additionally own the serial port. In this scheme, -sending data over the COM port while DTR is pulled low results in that -packet being captured by the bootloader and interpreted as a -bootloader command. When the user uploads a new program, the -bootloader will overwrite the old one, reset the various peripheral -registers, and jump to user code. All of this will occur without -resetting the chip and thus causing Maple to connect and disconnect -from your computer (which seems to cause many problems). - -The final version of this bootloader scheme will involve a separate -microcontroller, whose responsibilities are to drive the USB port, -program the main processor, and offer some amount of debugging -capability. This will allow user sketches to run on the bare metal of -the main processor, without any bootloader hiding underneath. This -approach is similar to the approaches taken by mbed and the Arduino -Uno. - -Regardless of which generation of the new serial bootloader you are -working with, the command interface is the same. The low level -communication protocol is inspired by STK-500, the protocol used to -program many AVR-based development boards. The protocol is a -packetized query-response scheme. The host PC initiates every -transaction, and for every query sent to the bootloader, a single -response will be returned (or the system times out). Data is -transmitted over 115.2kbps, 8 data bits, 1 stop bit, no parity -bit. Every query or response follows the same packet format that looks -like this: - -.. _bootloader-packet-structure: - -Packet Structure -^^^^^^^^^^^^^^^^ - -A bootloader packet is composed of a sequence of fields, as follows. - -.. list-table:: - :header-rows: 1 - - * - Field - - Length (bytes) - - Value - - Description - - * - START - - 1 - - 0x1B - - Magic constant, indicates bootloader packet - - * - SEQUENCE_NUM - - 1 - - 0--0xFF - - Queries and responses must have the same sequence number; rolls - over to 0 after 0xFF - - * - MESSAGE_SIZE - - 2 - - 0--0xFFFF - - Size of message body, currently limited to a 1024B=1KB maximum - - * - TOKEN - - 1 - - 0x7F - - Differs from STK500 value of 0x0E - - * - MESSAGE_BODY - - Variable, determined by MESSAGE_SIZE field - - Command query or response - - See :ref:`next section ` - - * - CHECKSUM - - 4 - - XOR of all other 32-bit words in packet - - See :ref:`below ` - -.. _bootloader-checksum: - -.. highlight:: cpp - -.. note:: When computing the checksum, the words in a packet are - interpreted big-endian (as if the packet were a sequence of 32-bit, - big-endian unsigned integers). If the end of the MESSAGE_BODY is - not aligned with a four-byte boundary, then the checksum will treat - it as if it was padded with zero bytes to a four-byte boundary. - - As a concrete example, an entire GET_INFO query (see :ref:`below - `), including the packet structure, is - comprised of the byte sequence :: - - {0x1B, 0x7F, 0x00, 0x01, 0x7F, 0x00, 0x64, 0x7F, 0x00, 0x01} - - The SEQUENCE_NUM of this query is 0x7F. +.. .. _bootloader-rev6: + +.. Maple Rev6 - The Serial Bootloader (Tentative) +.. ---------------------------------------------- + +.. .. note:: This section documents an in-progress version of the Maple +.. bootloader. **No Maples yet sold use this bootloader protocol**. +.. It has not been yet been publicly released, and its interface is +.. not stable. + +.. The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac, +.. but was unsatisfactory on Windows. Unlike the other operating systems, +.. Windows needed to be manually pointed to both the driver to use for +.. programming (DFU, via `libusb `_) and the +.. driver to use for serial communication (usbser.sys, built in to +.. Windows). Since Maple operates in only one of these modes at a time, +.. driver installation was unnecessarily complicated. It was necessary to +.. bring Maple into the correct mode before installing each of the +.. drivers. Furthermore, because libusb is not bundled with Windows, and +.. its driver is not signed, Windows 7 users have been forced to +.. laboriously disable driver signing checks. Finally, Windows hates the +.. constant switching of the device between Serial and DFU modes (during +.. programming), and often prompts users to install drivers that are +.. already installed. We have therefore decided to abandon DFU. + +.. In our new bootloader scheme, Maple is simply a serial device. +.. Windows comes bundled with usbser.sys, so no driver signing is +.. required. The IDE installation process is greatly simplified, there +.. is no more switching back and forth between "modes", and we can build +.. in new functionality outside the DFU spec. + +.. The first incarnation of this serial-only bootloader leaves libmaple +.. and user code untouched. However, during programming, instead of +.. calling :command:`dfu-util` to upload code we will now call a newly +.. written utility script similar to `avr-dude +.. `_. The high level +.. operation of the bootloader will remain the same - come on at startup, +.. wait for an upload operation or timeout, and jump to user code. + +.. The second version of this bootloader will eliminate this dependence +.. on resetting and timing out by having the bootloader run in the +.. background. It will additionally own the serial port. In this scheme, +.. sending data over the COM port while DTR is pulled low results in that +.. packet being captured by the bootloader and interpreted as a +.. bootloader command. When the user uploads a new program, the +.. bootloader will overwrite the old one, reset the various peripheral +.. registers, and jump to user code. All of this will occur without +.. resetting the chip and thus causing Maple to connect and disconnect +.. from your computer (which seems to cause many problems). + +.. The final version of this bootloader scheme will involve a separate +.. microcontroller, whose responsibilities are to drive the USB port, +.. program the main processor, and offer some amount of debugging +.. capability. This will allow user sketches to run on the bare metal of +.. the main processor, without any bootloader hiding underneath. This +.. approach is similar to the approaches taken by mbed and the Arduino +.. Uno. + +.. Regardless of which generation of the new serial bootloader you are +.. working with, the command interface is the same. The low level +.. communication protocol is inspired by STK-500, the protocol used to +.. program many AVR-based development boards. The protocol is a +.. packetized query-response scheme. The host PC initiates every +.. transaction, and for every query sent to the bootloader, a single +.. response will be returned (or the system times out). Data is +.. transmitted over 115.2kbps, 8 data bits, 1 stop bit, no parity +.. bit. Every query or response follows the same packet format that looks +.. like this: + +.. .. _bootloader-packet-structure: + +.. Packet Structure +.. ^^^^^^^^^^^^^^^^ + +.. A bootloader packet is composed of a sequence of fields, as follows. + +.. .. list-table:: +.. :header-rows: 1 + +.. * - Field +.. - Length (bytes) +.. - Value +.. - Description + +.. * - START +.. - 1 +.. - 0x1B +.. - Magic constant, indicates bootloader packet + +.. * - SEQUENCE_NUM +.. - 1 +.. - 0--0xFF +.. - Queries and responses must have the same sequence number; rolls +.. over to 0 after 0xFF + +.. * - MESSAGE_SIZE +.. - 2 +.. - 0--0xFFFF +.. - Size of message body, currently limited to a 1024B=1KB maximum + +.. * - TOKEN +.. - 1 +.. - 0x7F +.. - Differs from STK500 value of 0x0E + +.. * - MESSAGE_BODY +.. - Variable, determined by MESSAGE_SIZE field +.. - Command query or response +.. - See :ref:`next section ` + +.. * - CHECKSUM +.. - 4 +.. - XOR of all other 32-bit words in packet +.. - See :ref:`below ` + +.. .. _bootloader-checksum: + +.. .. highlight:: cpp + +.. .. note:: When computing the checksum, the words in a packet are +.. interpreted big-endian (as if the packet were a sequence of 32-bit, +.. big-endian unsigned integers). If the end of the MESSAGE_BODY is +.. not aligned with a four-byte boundary, then the checksum will treat +.. it as if it was padded with zero bytes to a four-byte boundary. -.. highlight:: sh +.. As a concrete example, an entire GET_INFO query (see :ref:`below +.. `), including the packet structure, is +.. comprised of the byte sequence :: + +.. {0x1B, 0x7F, 0x00, 0x01, 0x7F, 0x00, 0x64, 0x7F, 0x00, 0x01} + +.. The SEQUENCE_NUM of this query is 0x7F. + +.. .. highlight:: sh -.. _bootloader-commands: +.. .. _bootloader-commands: -Commands -^^^^^^^^ +.. Commands +.. ^^^^^^^^ -The packet structure overhead is for reliability. The actual queries -and responses are transacted inside of the message body. Following -the STK-500 protocol, each query or response begins with the single -byte command field. For each query, the resultant response must begin -with the same CMD byte. For each type of command, the structure of -queries and responses is of fixed size. +.. The packet structure overhead is for reliability. The actual queries +.. and responses are transacted inside of the message body. Following +.. the STK-500 protocol, each query or response begins with the single +.. byte command field. For each query, the resultant response must begin +.. with the same CMD byte. For each type of command, the structure of +.. queries and responses is of fixed size. -Also following STK-500, fields longer than 1 byte are transmitted MSB -first (big-endian). However, READ and WRITE commands operate byte-wise -(not word-wise); it is up to the host PC to ensure that alignment and -ordering issues are handled appropriately. +.. Also following STK-500, fields longer than 1 byte are transmitted MSB +.. first (big-endian). However, READ and WRITE commands operate byte-wise +.. (not word-wise); it is up to the host PC to ensure that alignment and +.. ordering issues are handled appropriately. -.. _bootloader-get-info: +.. .. _bootloader-get-info: -GET_INFO -"""""""" +.. GET_INFO +.. """""""" -Used to query device characteristics. +.. Used to query device characteristics. -GET_INFO Query: +.. GET_INFO Query: -.. list-table:: - :header-rows: 1 +.. .. list-table:: +.. :header-rows: 1 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - GET_INFO - - 1 - - Value 0 +.. * - GET_INFO +.. - 1 +.. - Value 0 -GET_INFO Response: +.. GET_INFO Response: -.. list-table:: - :header-rows: 1 - :widths: 4 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - GET_INFO - - 1 - - Value 0 +.. * - GET_INFO +.. - 1 +.. - Value 0 - * - Endianness - - 1 - - 0 indicates little-endian, 1 indicates big-endian. - (Currently returns 0; this field allows for future - expansion). +.. * - Endianness +.. - 1 +.. - 0 indicates little-endian, 1 indicates big-endian. +.. (Currently returns 0; this field allows for future +.. expansion). - * - Available Ram - - 4 - - In bytes +.. * - Available Ram +.. - 4 +.. - In bytes - * - Available Flash - - 4 - - In bytes +.. * - Available Flash +.. - 4 +.. - In bytes - * - Flash Page Size - - 2 - - In bytes +.. * - Flash Page Size +.. - 2 +.. - In bytes - * - Starting Address (FLASH) - - 4 - - Usually 0x08005000 +.. * - Starting Address (FLASH) +.. - 4 +.. - Usually 0x08005000 - * - Starting Address (RAM) - - 4 - - Usually 0x200000C0 +.. * - Starting Address (RAM) +.. - 4 +.. - Usually 0x200000C0 - * - Bootloader Version - - 4 - - Current version 0x00060000 (MAJ,MIN) +.. * - Bootloader Version +.. - 4 +.. - Current version 0x00060000 (MAJ,MIN) -.. _bootloader-erase-page: +.. .. _bootloader-erase-page: -ERASE_PAGE -"""""""""" +.. ERASE_PAGE +.. """""""""" -Used to erase flash pages. +.. Used to erase flash pages. -ERASE_PAGE query: +.. ERASE_PAGE query: -.. list-table:: - :header-rows: 1 - :widths: 4 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - ERASE_PAGE - - 1 - - Value 1 +.. * - ERASE_PAGE +.. - 1 +.. - Value 1 - * - ADDRESS - - 4 - - Will erase whichever page contains ADDRESS +.. * - ADDRESS +.. - 4 +.. - Will erase whichever page contains ADDRESS -ERASE_PAGE response: +.. ERASE_PAGE response: -.. list-table:: - :header-rows: 1 - :widths: 3 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 3 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - ERASE_PAGE - - 1 - - Value 1 +.. * - ERASE_PAGE +.. - 1 +.. - Value 1 - * - SUCCESS - - 1 - - Either 0 (failure) or 1 (success) +.. * - SUCCESS +.. - 1 +.. - Either 0 (failure) or 1 (success) -WRITE_BYTES -""""""""""" +.. WRITE_BYTES +.. """"""""""" -Used to write to RAM or flash. +.. Used to write to RAM or flash. -WRITE_BYTES query: +.. WRITE_BYTES query: -.. list-table:: - :header-rows: 1 - :widths: 4 4 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 4 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - WRITE_BYTES - - 1 - - Value 2 +.. * - WRITE_BYTES +.. - 1 +.. - Value 2 - * - Starting Address - - 4 - - Can address arbitrary RAM, or :ref:`cleared - ` flash pages. +.. * - Starting Address +.. - 4 +.. - Can address arbitrary RAM, or :ref:`cleared +.. ` flash pages. - * - DATA - - MESSAGE_SIZE - 5 - - See :ref:`Packet Structure ` +.. * - DATA +.. - MESSAGE_SIZE - 5 +.. - See :ref:`Packet Structure ` -WRITE_BYTES response: +.. WRITE_BYTES response: -.. list-table:: - :header-rows: 1 - :widths: 2 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - WRITE_BYTES - - 1 - - Value 2 +.. * - WRITE_BYTES +.. - 1 +.. - Value 2 - * - SUCCESS - - 1 - - Either 0 (failure) or 1 (success). Will fail if writes were - made to uncleared pages. Does not clean up failed writes - (memory will be left in an undefined state). +.. * - SUCCESS +.. - 1 +.. - Either 0 (failure) or 1 (success). Will fail if writes were +.. made to uncleared pages. Does not clean up failed writes +.. (memory will be left in an undefined state). -READ_BYTES -"""""""""" +.. READ_BYTES +.. """""""""" -Used to read from RAM or flash. +.. Used to read from RAM or flash. -READ_BYTES query: +.. READ_BYTES query: -.. list-table:: - :header-rows: 1 - :widths: 2 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - READ_BYTES - - 1 - - Value 3 +.. * - READ_BYTES +.. - 1 +.. - Value 3 - * - ADDRESS - - 4 - - Start of block to read. Must be a multiple of 4. +.. * - ADDRESS +.. - 4 +.. - Start of block to read. Must be a multiple of 4. - * - LENGTH - - 2 - - Maximum number of bytes to read (currently, this may be at most - 1024 = 1KB). Must be a multiple of 4. +.. * - LENGTH +.. - 2 +.. - Maximum number of bytes to read (currently, this may be at most +.. 1024 = 1KB). Must be a multiple of 4. -READ_BYTES response: +.. READ_BYTES response: -.. list-table:: - :header-rows: 1 - :widths: 2 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - READ_BYTES - - 1 - - Value 3 +.. * - READ_BYTES +.. - 1 +.. - Value 3 - * - DATA - - MESSAGE_SIZE - 1 - - Contains read bytes. The actual number of bytes read may be - less than the LENGTH field of the corresponding READ_BYTES - query. If this section is of length 0, this should be - interpreted as a read failure. See - :ref:`bootloader-packet-structure`. +.. * - DATA +.. - MESSAGE_SIZE - 1 +.. - Contains read bytes. The actual number of bytes read may be +.. less than the LENGTH field of the corresponding READ_BYTES +.. query. If this section is of length 0, this should be +.. interpreted as a read failure. See +.. :ref:`bootloader-packet-structure`. -JUMP_TO_USER -"""""""""""" +.. JUMP_TO_USER +.. """""""""""" -Causes the bootloader to jump to user code's starting address. +.. Causes the bootloader to jump to user code's starting address. -JUMP_TO_USER query: +.. JUMP_TO_USER query: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - JUMP_TO_USER - - 1 - - Value 4 +.. * - JUMP_TO_USER +.. - 1 +.. - Value 4 - * - Location - - 1 - - 0 means jump to flash starting address, 1 means jump to RAM - starting address. See the :ref:`bootloader-get-info` command - for more information. +.. * - Location +.. - 1 +.. - 0 means jump to flash starting address, 1 means jump to RAM +.. starting address. See the :ref:`bootloader-get-info` command +.. for more information. -JUMP_TO_USER response: +.. JUMP_TO_USER response: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - JUMP_TO_USER - - 1 - - Value 4 +.. * - JUMP_TO_USER +.. - 1 +.. - Value 4 - * - SUCCESS - - 1 - - Either 0 (failure) or 1 (success). If successful, after the - response is sent, the bootloader ends this session and jumps to - the user code in flash or RAM as specified in the query's - Location field. +.. * - SUCCESS +.. - 1 +.. - Either 0 (failure) or 1 (success). If successful, after the +.. response is sent, the bootloader ends this session and jumps to +.. the user code in flash or RAM as specified in the query's +.. Location field. -SOFT_RESET -"""""""""" +.. SOFT_RESET +.. """""""""" -Engages a full software reset. +.. Engages a full software reset. -SOFT_RESET query: +.. SOFT_RESET query: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - SOFT_RESET - - 1 - - Value 5 +.. * - SOFT_RESET +.. - 1 +.. - Value 5 -SOFT_RESET response: +.. SOFT_RESET response: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - SOFT_RESET - - 1 - - Value 5 +.. * - SOFT_RESET +.. - 1 +.. - Value 5 - * - SUCCESS - - 1 - - Either 0 or 1 (FAILED and OK, respectively). Will end this - bootloader session and reset the processor. +.. * - SUCCESS +.. - 1 +.. - Either 0 or 1 (FAILED and OK, respectively). Will end this +.. bootloader session and reset the processor. .. _bootloader-reflashing: diff --git a/source/compatibility.rst b/source/compatibility.rst index a070b42..848a3d3 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -119,8 +119,6 @@ differences, most of which are improvements: Shield and Device Compatibility ------------------------------- -.. TODO update for 0.0.9 - .. list-table:: :header-rows: 1 @@ -134,7 +132,7 @@ Shield and Device Compatibility * - WiFi Shield - Yes! - - Tested; no library yet (expected for 0.0.9) + - Tested; preliminary library support * - MIDI shield - Yes! @@ -146,7 +144,8 @@ Shield and Device Compatibility * - Bluetooth shield - Unknown - - + - Some Bluetooth <-> UART boards have been tested and are known + to work. * - Cellular shield - Unknown @@ -158,11 +157,12 @@ Library Porting Status The state of currently ported Arduino libraries is the :ref:`libraries`. -.. TODO update for 0.0.9; update as libraries are ported. +.. TODO Update as libraries are ported. .. list-table:: :header-rows: 1 + * - Library - Ported? - Notes @@ -180,9 +180,11 @@ The state of currently ported Arduino libraries is the - Planned * - EEPROM - - No - - The Maple doesn't have EEPROM; use flash instead. Perhaps this - library could be emulated? + - (Unsupported) third-party emulation + - The Maple doesn't have EEPROM; it uses flash instead. There is + an `EEPROM emulation library + `_ by + `x893 `_, but we haven't tested it. * - Firmata - Not yet @@ -192,6 +194,10 @@ The state of currently ported Arduino libraries is the - Not yet - Planned + * - Servo + - **Yes** + - :ref:`Included since IDE 0.0.9 ` + * - SoftwareSerial - Not yet - Planned diff --git a/source/cpp.rst b/source/cpp.rst deleted file mode 100644 index a20578e..0000000 --- a/source/cpp.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _cpp: - -============== -C++ for Maple -============== - -.. _index-language-index-cpp-index: - -.. toctree:: - :maxdepth: 1 - :glob: - - lang/cpp/* \ No newline at end of file diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index 79492ef..5187ca4 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -121,6 +121,5 @@ Recommended Reading * STMicro documentation for STM32F103RB microcontroller: - * `All `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) diff --git a/source/gpio.rst b/source/gpio.rst index ee2b6eb..4017862 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -14,9 +14,9 @@ peripheral functions. This page documents those capabilities, by pin. The current and voltage limitations have not been copied over from the STM32 datasheet (see the :ref:`Recommended Reading ` for a link). In particular, a number of -GPIO pins are 5v tolerant (which means that applying 5v to a pin and -reading it as input or allowing it to drain to ground will not damage -that pin), while some are not. +GPIO pins are 5V tolerant (which means that applying 5 volts to a pin +and reading it as input or allowing it to drain to ground will not +damage that pin), while some are not. .. contents:: Contents :local: @@ -26,11 +26,10 @@ that pin), while some are not. Pin Mapping Mega Table ---------------------- -This huge reference table shows the available functionality on every -GPIO pin, by peripheral type. The "STM32" column refers to the port -and number that the header is connected to on the microcontroller. -The "5v?" column documents whether or not the pin is 5v tolerant (see -above). +This table shows the available functionality on every GPIO pin, by +peripheral type. The "STM32" column refers to the port and number that +the header is connected to on the microcontroller. The "5V?" column +documents whether or not the pin is 5 volt tolerant (see above). .. csv-table:: :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" @@ -99,6 +98,5 @@ Recommended Reading STMicro documentation for STM32F103RB microcontroller: - * `All `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) diff --git a/source/home.rst b/source/home.rst deleted file mode 100644 index db5b56e..0000000 --- a/source/home.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _home: - -======================== -Maple Documentation Home -======================== - - -Welcome! - -Maple is a user-friendly prototyping platform developed by LeafLabs in Cambridge, MA. Using Maple, creators with any level of experience can implement beautiful ideas that require the power of a 32-bit processor. For more details about Maple's hardware, please see its :ref:`technical specifications `. To start using your Maple, keep reading - -.. _home-Getting-Started: - -Getting Started -^^^^^^^^^^^^^^^ - -:ref:`Quickstart ` - -:ref:`IDE Anatomy ` - -:ref:`Basic Language Reference ` - -:ref:`Tech Specs` - -.. _home-Problem-Solving: - -Problem Solving -^^^^^^^^^^^^^^^ - -Check out our :ref:`troubleshooting ` and :ref:`known problems` pages. - -If you don't find what you're looking for, hit the `forums `_ to ask the LeafLabs team and other Maple users questions. Good luck, and have fun! diff --git a/source/i2c.rst b/source/i2c.rst index 6e5b946..b4a996b 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -80,7 +80,6 @@ Recommended Reading * `Arduino i2c/TWI reference `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) * `Application Note on Advanced I2C Usage diff --git a/source/index.rst b/source/index.rst index c552dd4..825ec81 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,7 +1,15 @@ .. _index: Maple Documentation Contents -============================= +============================ + +Welcome! This is the Maple documentation index. If you just bought a +Maple, you probably want to head to the :ref:`quickstart +`. If you're having problems, check out the +:ref:`troubleshooting ` and :ref:`known problems +` pages. + +Have fun! .. _index-usage: @@ -15,7 +23,7 @@ Maple Documentation Contents IDE Anatomy .. _index-maple-programming: - + **Maple Programming:** .. toctree:: @@ -29,7 +37,7 @@ Maple Documentation Contents Bootloader - Troubleshooting + Troubleshooting Known Problems .. _index-hardware: @@ -38,7 +46,7 @@ Maple Documentation Contents .. toctree:: :maxdepth: 1 - + i2c pwm gpio @@ -55,8 +63,8 @@ Maple Documentation Contents .. toctree:: :maxdepth: 1 - + Technical Specifications Complete Language Index - + diff --git a/source/jtag.rst b/source/jtag.rst index 7cfba5f..e3c8111 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -15,24 +15,24 @@ and hardware peripherals (we use it when working on :ref:`libmaple Note that the STM32 on the Maple has a built-in low level serial debugger which could also be used to flash bootloaders, and that the :ref:`ASSERT ` framework allows basic debugging over -a USART serial channel. We expect only advanced users to use this -feature. +a USART serial channel. We expect only fairly advanced users to use +this feature. .. contents:: Contents :local: - Wiring Diagram -------------- .. figure:: /_static/img/jtag-wiring.png :align: center :alt: JTAG wiring diagram + :width: 7.4in - JTAG wiring diagram to connect a standard 20-pin ARM JTAG device to - the 8-pin JTAG port on the Maple. - -.. FIXME jtag wiring diagram (above) looks terrible; replace it + JTAG wiring diagram (`large version + `_) + to connect a standard 20-pin ARM JTAG device to the 8-pin JTAG port + on the Maple. The Maple has holes for a 8-pin JTAG header but that header is not soldered on by default. If you know ahead of time that you'll be @@ -42,14 +42,7 @@ probably solder one on for no charge. Otherwise, you can simply attach standard 0.1" pitch male header pins (either the exact 4x2 block or two 4-pin pieces of breakaway straight header). For a one-off usage hack, the header can be jammed in the holes and twisted to -ensure electrical contact; this is what we do to flash our bootloader. - -The above schematic assumes that the header has been soldered on to -the *bottom* of the board, not the top; most ribbon cable connectors -will interfere with the power header. If you don't want a header -coming off the bottom, you can use a slim connector and invert this -diagram appropriately. - +ensure electrical contact. Compatible Devices ------------------ @@ -65,6 +58,8 @@ Recommended Reading * `STM32/gdb/OpenOCD HOWTO `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) +* There's a `thread on JTAG + `_ in our `forum`_ + which you may find useful. diff --git a/source/lang/api/analogread.rst b/source/lang/api/analogread.rst index c614aca..35c6fbc 100644 --- a/source/lang/api/analogread.rst +++ b/source/lang/api/analogread.rst @@ -32,11 +32,6 @@ Before calling analogRead() on a pin, that pin must first be configured for analog input, using :ref:`lang-pinMode` (you only have to do this once, so it's usually done in :ref:`lang-setup`\ ). -It takes about 0.8 microseconds (.0000008 seconds) to read an analog -input, so the maximum sample rate using this function is approximately -1.3 million samples per second\ [#fsamp]_. - - Parameter Discussion -------------------- @@ -115,40 +110,10 @@ Some basic tools to accomplish this are `resistor dividers . However, opamps and other powered components can also be used if greater precision is required. -Finally, On the Arduino, it takes significantly longer to read analog -input: about 100 microseconds (0.0001 s), so the maximum reading rate -is 10,000 times a second. - - See also -------- - :ref:`ADC note ` - `(Arduino) Tutorial: Analog Input Pins `_ - -.. rubric:: Footnotes - -.. [#fsamp] This is based on the current configuration of a 55.5 cycle - sample time, at 72 MHz. However, the minimum sample time *possible* - is 1.5 cycles, leading to a theoretical maximum of approximately 48 - million samples per second (of course, doing anything with the - readings also consumes cycles, so this maximum can't be reached in - practice). - - See the `STM32 Reference Manual `_, §§11.12.4--5 - (pp. 225--226), for more information on the low-level bit twiddling - currently necessary to change the sample time. For examples of how - the ADCs are configured in libmaple, see `adc.h - `_ - and `adc.c - `_\ - . Be aware that changing the sample time has important - consequences related to the impedance of the device connected to - the input pin. If you want to make changes, as a minimum, you - should first read ST's application notes on `ADC modes - `_ and `ADC oversampling - `_. - - .. include:: cc-attribution.txt diff --git a/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst index 01820ef..9147b96 100644 --- a/source/lang/api/analogwrite.rst +++ b/source/lang/api/analogwrite.rst @@ -11,19 +11,18 @@ analogWrite() .. note:: On the Maple, calling analogWrite() is the same as calling - :ref:`lang-pwmwrite`\ ; see that function's documentation for more - information. + :ref:`lang-pwmwrite`\ ; we recommend using that function directly + instead. This is because PWM is not true analog output (i.e., is not the output of a `DAC `_\ ), so - the function is badly named. For instance, **analogWrite() has + the function is badly named. For instance, analogWrite() **has absolutely nothing to do with** :ref:`lang-analogread`\ , which is potentially confusing. - The alias of analogWrite() to pwmWrite() is provided (sigh) for the - sake of compatibility with Arduino, but we recommend using - :ref:`lang-pwmwrite` when writing new software, for clarity. + The alias of analogWrite() to pwmWrite() is provided for the sake + of compatibility with Arduino only. .. contents:: Contents :local: @@ -97,23 +96,21 @@ Difference 3: No PWM on pin 10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, -9, 11, 12, and 14, or twelve pins in total. That is at least as -*many* PWM pins as any Arduino board, but there are differences in -*which* pins support it. +9, 11, 12, 14, 24, 27, and 28 or fifteen pins in total. That's *more* +PWM-capable pins as any Arduino board, but there are differences in +*which* pins support PWM. * On **most Arduino boards** (those with the ATmega168 or ATmega328; this includes the **Arduino Uno**), this function works on pins 3, 5, 6, 9, 10, and 11, or six pins total. Note that these boards support PWM on pin 10, while Maple does not. -* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins - total. Note that this board supports PWM on pins 4, 10, and 13, - while the Maple does not. Maple supports PWM on pins 0, 1, and 14, - which the Mega does not, making the total number of pins supporting - PWM equal on these boards. +* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve + pins total. Note that this board supports PWM on pins 4, 10, and + 13, while the Maple does not. -* **Older Arduino boards** with an ATmega8 only support analogWrite() on - pins 9, 10, and 11. Maple does not support PWM on pin 10. +* **Older Arduino boards** with an ATmega8 only support analogWrite() + on pins 9, 10, and 11. Maple does not support PWM on pin 10. In all cases, Arduino boards support PWM on pin 10, unlike Maple. We did our best to make PWM as pin-compatible as possible; however, @@ -125,7 +122,8 @@ work on any Arduino board and on Maple. The "safe" pins, which work on most recent Arduino boards, the Arduino Mega and the Maple, are pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as portable as possible between Maple and Arduino, we recommend using the -"safest" pins first, then the "safe" pins, as necessary. +"safest" pins first, then the "safe" pins, then any other pins, as +necessary. Difference 4: PWM frequency ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -138,17 +136,23 @@ Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of the timer which controls PWM output on the particular pin (\ :ref:`the PWM tutorial has the details `\ ). -If your application absolutely requires Arduino's PWM frequency (it -probably doesn't), then the steps are: +If your application definitely requires Arduino's PWM frequency, then +the steps are: -1. Figure out which timer controls PWM output on your pin (\ :ref:`this table ` is your friend here). Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4. +1. Figure out which :ref:`timer ` controls PWM + output on your pin (\ :ref:`this table ` is your + friend here). Let's say it's ``Timern``\ , where ``n`` is some + number 1, 2, 3, or 4. -2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of approximately 490 Hz. +2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's + period to approximately 2041 microseconds, which is a frequency of + approximately 490 Hz. Be aware that this will change the period for the **entire timer**\ , and will affect anything else in your program that depends on that -timer. One example is :ref:`interrupts `\ . -You've been :ref:`warned `\ . +timer. The important examples are :ref:`timer interrupts +` and :ref:`PWM +`\ . See also -------- diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst index bc5c894..4426293 100644 --- a/source/lang/api/constants.rst +++ b/source/lang/api/constants.rst @@ -288,6 +288,29 @@ exponent indicators. Some examples are given in the following table: - 67.0×10\ :sup:`-12` - ``0.000000000067`` +.. _lang-constants-board: + +Board-Specific Constants +------------------------ + +This section documents constants whose value might change across +different LeafLabs boards. You can use these constants to help ensure +that your code will be portable across different boards. + +.. TODO replace "upcoming" when Mini, Native come out + +.. _lang-constants-led: + +- ``BOARD_LED_PIN``: the number of the pin which connects to the + built-in LED. On the Maple, this is pin 13, but it's not guaranteed + to be the same in upcoming boards like the Maple Mini. + +.. _lang-constants-but: + +- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the + built-in button (labeled "BUT"). On the Maple, this is pin 38, but + it's not guaranteed to be the same in other boards. + See Also -------- diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst new file mode 100644 index 0000000..c71b2c3 --- /dev/null +++ b/source/lang/api/hardwarespi.rst @@ -0,0 +1,152 @@ +.. highlight:: cpp + +.. _lang-hardwarespi: + +HardwareSPI +=========== + +This class is used for creating objects to manage the Maple's built-in +SPI ports. The Maple has two SPI ports. The relevant pins +corresponding to each port's logic signals are documented in the +following table (and on the Maple silkscreen): + +.. _lang-hardwarespi-pinout: + +.. list-table:: + :header-rows: 1 + + * - Port number + - NSS + - MOSI + - MISO + - SCK + + * - 1 + - 10 + - 11 + - 12 + - 13 + + * - 2 + - 31 + - 32 + - 33 + - 34 + +If you use a SPI port, you cannot simultaneously use its associated +pins for other purposes. + +Library Documentation +--------------------- + +HardwareSPI Class Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use the SPI interface by including a declaration ``HardwareSPI +Spi(number);`` at the start of the sketch or program. The ``number`` +must be either 1 or 2 and specifies which port to use. Once this is +done, you can call any of the methods documented here using +``Spi.method(arguments)``; for example, ``Spi.send(0x13)`` would send +the value ``0x13`` into the port buffer to be transmitted as soon as +possible. + +.. cpp:class:: HardwareSPI + + Class for interacting with SPI. + +.. cpp:function:: HardwareSPI::HardwareSPI(uint32 spi_num) + + Construct an object for managing a SPI peripheral. ``spi_num`` + must be 1 or 2; see the :ref:`table above + ` for pinout information. + +.. cpp:function:: void HardwareSPI::begin(SPIFrequency freq, uint32 endianness, uint32 mode) + + Configure the baudrate of the given SPI port and set up the header + pins appropriately. + + Parameters: + + - ``freq``: one of the ``SPIFrequency`` values, given :ref:`below + `. + + - ``endianness``: either ``LSBFIRST`` (little-endian) or + ``MSBFIRST`` (big-endian). + + - ``mode``: one of 0, 1, 2, or 3, and specifies which SPI mode is + used. The mode number determines a combination of polarity and + phase according to the following table: + + .. list-table:: + :header-rows: 1 + + * - Mode + - Polarity + - Phase + + * - 0 + - 0 + - 0 + + * - 1 + - 0 + - 1 + + * - 2 + - 1 + - 0 + + * - 3 + - 1 + - 1 + + For more information on polarity and phase, see the + :ref:`external references, below `. + +.. cpp:function:: void HardwareSPI::begin() + + A convenience ``begin()``, equivalent to ``begin(SPI_1_125MHZ, + MSBFIRST, 0)``. + +.. cpp:function:: uint8 HardwareSpi::send(uint8 *data, uint32 length) + + Writes ``data`` into the port buffer to be transmitted as soon as + possible, where ``length`` is the number of bytes to send from + ``data``. Returns the last byte shifted back from slave. + +.. cpp:function:: uint8 HardwareSpi::send(uint8 data) + + Writes the single byte ``data`` into the port buffer to be + transmitted as soon as possible. Returns the data byte shifted + back from the slave. + +.. cpp:function:: uint8 HardwareSpi::recv() + + Reads a byte from the peripheral. Returns the next byte in the + buffer. + +SPI Speeds +^^^^^^^^^^ + +.. _lang-hardwarespi-spifrequency: + +The possible SPI speeds are configured using the ``SPIFrequency`` enum: + +.. doxygenenum:: SPIFrequency + +.. _lang-hardwarespi-seealso: + +See Also +-------- + +* `Wikipedia Article on Serial Peripheral Interface Bus (SPI) + `_ +* `Arduino reference on SPI + `_ +* `Hardcore SPI on Arduino `_ by kik64 +* STMicro documentation for STM32F103RB microcontroller: + + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + + diff --git a/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst new file mode 100644 index 0000000..258471b --- /dev/null +++ b/source/lang/api/hardwaretimer.rst @@ -0,0 +1,368 @@ +.. highlight:: cpp + +.. _lang-hardwaretimer: + +HardwareTimer +============= + +This class defines the public API for interfacing with the STM32's +built-in timer peripherals. More information on these peripherals +(including code examples) is available in the :ref:`timers reference +`. + +Library Documentation +--------------------- + +HardwareTimer Class Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To interact with a particular timer, call one of the methods +documented below on one of the predefined ``HardwareTimer`` instances. +For example, to set the prescale factor on timer 1 to 5, call +``Timer1.setPrescaleFactor(5)``. + +.. cpp:class:: HardwareTimer + + Class for interacting with a timer. There are four predefined + instances available on the Maple: ``Timer1``, ``Timer2``, + ``Timer3``, and ``Timer4``. + +.. _lang-hardwaretimer-attachinterrupt: + +.. cpp:function:: void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler) + + Attach an interrupt handler to the given ``channel``. This + interrupt handler will be called when the timer's counter reaches + the given channel :ref:`compare ` + value. + + ``handler`` should be a function which takes no arguments and has + :ref:`void ` value; i.e. it should have signature :: + + void handler(void); + + You can later detach the interrupt using :ref:`detachInterrupt() + `. + + .. note:: The function (often called an *interrupt service + routine*, or ISR) should attempt to return as quickly as + possible. :ref:`Blinking the LED `, some + logic, :ref:`PWM ` updates, and :ref:`Serial + ` writes are fine; writing to + :ref:`SerialUSB ` or :ref:`waiting + ` for user input can take a long + time and prevent other interrupts from firing on time. + + Tip: if you have a :ref:`delay() ` in your + ISR, you're probably doing it wrong. + +.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + `\ ``(1, handler)``. + +.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + `\ ``(2, handler)``. + +.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + `\ ``(3, handler)``. + +.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + `\ ``(4, handler)``. + +.. _lang-hardwaretimer-setchannelmode: + +.. cpp:function:: void HardwareTimer::setChannelMode(int channel, TimerMode mode) + + Set the given channel of this timer to the given :ref:`mode + `. The parameter ``channel`` is one of + 1, 2, 3, and 4, and corresponds to the compare channel you would + like to set. Refer to the full :ref:`pin mapping table + ` to match up timer channels and pin + numbers. + +.. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode `\ + ``(1, mode)``. + +.. cpp:function:: void HardwareTimer::setChannel2Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode `\ + ``(2, mode)``. + +.. cpp:function:: void HardwareTimer::setChannel3Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode `\ + ``(3, mode)``. + +.. cpp:function:: void HardwareTimer::setChannel4Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode `\ + ``(4, mode)``. + +.. _lang-hardwaretimer-getcompare: + +.. cpp:function:: uint16 HardwareTimer::getCompare(int channel) + + Gets the compare value for the given ``channel``, from 1 to 4. See + :ref:`setCompare() `. + +.. cpp:function:: uint16 HardwareTimer::getCompare1() + + Equivalent to :ref:`getCompare `\ + ``(1, mode)``. + +.. cpp:function:: uint16 HardwareTimer::getCompare2() + + Equivalent to :ref:`getCompare `\ + ``(2, mode)``. + +.. cpp:function:: uint16 HardwareTimer::getCompare3() + + Equivalent to :ref:`getCompare `\ + ``(3, mode)``. + +.. cpp:function:: uint16 HardwareTimer::getCompare4() + + Equivalent to :ref:`getCompare `\ + ``(4, mode)``. + +.. _lang-hardwaretimer-setcompare: + +.. cpp:function:: void HardwareTimer::setCompare(int channel, uint16 compare) + + Sets the compare value for the given ``channel`` to ``compare``. + If ``compare`` is greater than this timer's overflow value, it will + be truncated to the overflow value. The default compare value is + 65,535 (the largest unsigned 16-bit integer value). + + When the counter reaches this value the interrupt for this channel + will fire if the given ``channel`` :ref:`mode + ` is ``TIMER_OUTPUTCOMPARE`` and + an interrupt is :ref:`attached + `. + + By default, this only changes the relative offsets between events + on a single timer ("phase"); they don't control the frequency with + which they occur. However, a common trick is to increment the + compare value manually in the interrupt handler so that the event + will fire again after the increment period. There can be a + different increment value for each channel, so this trick allows + events to be programmed at 4 different rates on a single + timer. Note that function call overheads mean that the smallest + increment rate is at least a few microseconds. + +.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) + + Equivalent to :ref:`setCompare `\ + ``(1, compare)``. + +.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) + + Equivalent to :ref:`setCompare `\ + ``(2, compare)``. + +.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) + + Equivalent to :ref:`setCompare `\ + ``(3, compare)``. + +.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) + + Equivalent to :ref:`setCompare `\ + ``(4, compare)``. + +.. cpp:function:: uint16 HardwareTimer::getCount() + + Gets the current timer count. Due to function call overhead, the + return value will be increasingly accurate with smaller prescale + values. Also see :ref:`setCount() `. + +.. _lang-hardwaretimer-setcount: + +.. cpp:function:: void HardwareTimer::setCount(uint16 val) + + Set the timer's current count to ``val``. + + Note that there is some function call overhead associated with + calling this method, so using it is not a robust way to get + multiple timers to share a count value. + + If ``val`` exceeds the timer's :ref:`overflow value + `, it is truncated to the overflow + value. + + +.. _lang-hardwaretimer-detachinterrupt: + +.. cpp:function:: void HardwareTimer::detachInterrupt(int channel) + + Remove the interrupt handler attached to the given ``channel``, if + any. The handler will no longer be called by this timer. + +.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() + + Equivalent to :ref:`detachInterrupt + `\ ``(1)``. + +.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() + + Equivalent to :ref:`detachInterrupt + `\ ``(2)``. + +.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() + + Equivalent to :ref:`detachInterrupt + `\ ``(3)``. + +.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() + + Equivalent to :ref:`detachInterrupt + `\ ``(4)``. + +.. _lang-hardwaretimer-generateupdate: + +.. cpp:function:: void HardwareTimer::generateUpdate() + + Re-initializes the counter (to 0 in upcounting mode, which is the + default), and generates an update of the prescale and overflow + registers. + +.. _lang-hardwaretimer-getoverflow: + +.. cpp:function:: uint16 HardwareTimer::getOverflow() + + Gets the timer's overflow value. See :ref:`setOverflow() + `. + +.. _lang-hardwaretimer-setoverflow: + +.. cpp:function:: void HardwareTimer::setOverflow(uint16 val) + + Sets the timer overflow (or "reload") value to ``val``. + + When the timer's counter reaches this, value it resets to + zero. Its default value is 65535 (the largest unsigned 16-bit + integer); setting the overflow to anything lower will cause + interrupts to be called more frequently (see :ref:`setPeriod() + ` function for a shortcut). + + After the next :ref:`timer update + `, this number will be the + maximum value for the timer's channel compare values. + +.. _lang-hardwaretimer-pause: + +.. cpp:function:: void HardwareTimer::pause() + + Stop the timer's counter, without affecting its configuration. + + The timer will no longer count or fire interrupts after this + function is called, until it is resumed. This function is useful + during timer setup periods, in order to prevent interrupts from + firing before the timer is fully configured. + + Note that there is some function call overhead associated with this + method, so using it in concert with :ref:`resume() + ` is not a robust way to align multiple + timers to the same count value. + +.. _lang-hardwaretimer-setperiod: + +.. cpp:function:: uint16 HardwareTimer::setPeriod(uint32 microseconds) + + Configure the :ref:`prescaler + ` and :ref:`overflow + ` values to generate a timer reload + with a period as close to the given number of ``microseconds`` as + possible. + + The return value is the new overflow value, which may be used to + set channel compare values. However, if a clock that fires an + interrupt every given number of microseconds is all that is + desired, and the relative "phases" are unimportant, channel compare + values may all be set to 1. + +.. _lang-hardwaretimer-getprescalefactor: + +.. cpp:function:: uint16 HardwareTimer::getPrescaleFactor() + + Returns the timer's prescale factor. See + :ref:`setPrescaleFactor() `. + +.. _lang-hardwaretimer-setprescalefactor: + +.. cpp:function:: void HardwareTimer::setPrescaleFactor(uint16 factor) + + Set the timer's prescale factor to ``factor``. + + The prescaler acts as a clock divider to slow down the rate at + which the counter increments. + + For example, the system clock rate is 72MHz, so the counter will + reach 65535 in (13.89 nanoseconds) × (65535 counts) = (910.22 + microseconds), or about a thousand times a second. If the + prescaler equals 1098, then the clock rate is effectively 72MHz / + 1098 = 65.56KHz, and the counter will reach 65536 in (15.25 + microseconds) × (65536 counts) = (0.999 seconds), or about once + per second. + + The :ref:`setPeriod() ` method may + also be used as a convenient alternative. + +.. cpp:function:: void HardwareTimer::resume() + + Resume a paused timer, without affecting its configuration. + + The timer will resume counting and firing interrupts as + appropriate. + + Note that there is some function call overhead associated with + using this method, so using it in concert with :ref:`pause() + ` is not a robust way to align multiple + timers to the same count value. + +.. cpp:function:: timer_dev_num HardwareTimer::getTimerNum() + + Returns the :ref:`timer device number + ` associated with the timer. For + example, ``Timer1.getTimerNum()`` would return ``TIMER1``. + + In most cases, you should not need to use this function. If you do + use it, be careful; the constant ``TIMER1`` is *not equal* to the + number 1; similarly, ``TIMER2`` is *not* the number 2, etc. Be + sure to refer to the timer device number by name. + +.. _lang-hardwaretimer-modes: + +Timer Modes +^^^^^^^^^^^ +.. doxygenenum:: TimerMode + +.. _lang-hardwaretimer-timer-dev-num: + +Timer Device Numbers +^^^^^^^^^^^^^^^^^^^^ + +These provide a lower-level interface for interacting with timers. +They are mostly useful in context with the :ref:`getTimer() +` function. **Be careful** when using +these not to confuse e.g. ``TIMER1`` with the number 1; they are +different. + +.. doxygenenum:: timer_dev_num + +.. _lang-hardwaretimer-convenience: + +.. _lang-hardwaretimer-gettimer: + +Other Functions +^^^^^^^^^^^^^^^ +.. doxygenfunction:: getTimer diff --git a/source/lang/api/interrupts.rst b/source/lang/api/interrupts.rst new file mode 100644 index 0000000..58fd2cc --- /dev/null +++ b/source/lang/api/interrupts.rst @@ -0,0 +1,47 @@ +.. highlight:: cpp + +.. _lang-interrupts: + +interrupts() +============ + +Re-enables interrupts (after they've been disabled by +:ref:`noInterrupts() `). Interrupts allow certain +important tasks to happen in the background, and certain interrupts +are enabled by default. + +Some functions will not work while interrupts are disabled, and both +incoming and outgoing communication may be ignored. Interrupts can +slightly disrupt the timing of code, however, and may be disabled for +particularly critical sections of code. + +Library Documentation +--------------------- + +.. doxygenfunction:: interrupts + +Example +------- + +:: + + void setup() {} + + void loop() { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + +See Also +-------- + +- :ref:`noInterrupts() ` +- :ref:`attachInterrupt() ` +- :ref:`detachInterrupt() ` +- :ref:`Timers reference ` +- :ref:`Timer API ` +- :ref:`External interrupts ` + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/api/isbuttonpressed.rst b/source/lang/api/isbuttonpressed.rst new file mode 100644 index 0000000..dbff0c9 --- /dev/null +++ b/source/lang/api/isbuttonpressed.rst @@ -0,0 +1,17 @@ +.. _lang-isbuttonpressed: + +isButtonPressed() +================= + +Check whether the board's built-in button (labeled BUT on the +silkscreen) is pressed. + +Library Documentation +--------------------- + +.. doxygenfunction:: isButtonPressed + +See Also +-------- + +- :ref:`lang-waitforbuttonpress` diff --git a/source/lang/api/nointerrupts.rst b/source/lang/api/nointerrupts.rst new file mode 100644 index 0000000..68f0498 --- /dev/null +++ b/source/lang/api/nointerrupts.rst @@ -0,0 +1,47 @@ +.. highlight:: cpp + +.. _lang-nointerrupts: + +noInterrupts() +============== + +Description +----------- + +Disables interrupts. Interrupts allow certain important tasks to +happen in the background and are enabled by default. Some functions +will not work while interrupts are disabled, and incoming +communication may be ignored. Interrupts can slightly disrupt the +timing of code, however, and may be disabled for particularly critical +sections of code. + +Library Documentation +--------------------- + +.. doxygenfunction:: noInterrupts + +Example +------- + +:: + + void setup() {} + + void loop() { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + +See Also +-------- + +- :ref:`interrupts() ` +- :ref:`attachInterrupt() ` +- :ref:`detachInterrupt() ` +- :ref:`Timers reference ` +- :ref:`Timer API ` +- :ref:`External interrupts ` + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/api/pinmode.rst b/source/lang/api/pinmode.rst index b9095da..03cbcfa 100644 --- a/source/lang/api/pinmode.rst +++ b/source/lang/api/pinmode.rst @@ -13,6 +13,8 @@ Library Documentation .. doxygenfunction:: pinMode +.. _lang-pinmode-wiringpinmode: + .. doxygenenum:: WiringPinMode Discussion diff --git a/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst index 7a1d51f..2c858ab 100644 --- a/source/lang/api/pwmwrite.rst +++ b/source/lang/api/pwmwrite.rst @@ -11,6 +11,13 @@ pwmWrite(), the pin will output a steady square wave with the given duty cycle. You can change the duty cycle later by calling pwmWrite() again with the same pin and a different duty. +On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, +9, 11, 12, 14, 24, 27, and 28. + +The Arduino function :ref:`analogWrite() ` is an +alias for ``pwmWrite()``, but it is badly named, and its use is +discouraged. + .. contents:: Contents :local: @@ -25,12 +32,11 @@ Example Sets the output to the LED proportional to the value read from the potentiometer:: - int ledPin = 13; // LED connected to pin 13 (Maple) int analogPin = 3; // potentiometer connected to analog pin 3 int val = 0; // variable to store the read value void setup() { - pinMode(ledPin, OUTPUT); // sets the LED pin as output + pinMode(BOARD_LED_PIN, OUTPUT); // sets the LED pin as output pinMode(analogPin, PWM); // sets the potentiometer pin as PWM // output @@ -39,8 +45,9 @@ potentiometer:: void loop() { val = analogRead(analogPin); // read the input pin - analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, - // analogWrite values from 0 to 65535 + analogWrite(BOARD_LED_PIN, val / 16); // analogRead values go from 0 + // to 4095, analogWrite values + // from 0 to 65535 } See Also diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst index af3a7e0..e1d12bf 100644 --- a/source/lang/api/serialusb.rst +++ b/source/lang/api/serialusb.rst @@ -52,7 +52,9 @@ world!")``. .. cpp:class:: USBSerial Emulated serial-over-USB class. ``SerialUSB`` is the predefined - instance. + (singleton) instance. + +.. _lang-serialusb-begin: .. cpp:function:: USBSerial::begin() @@ -65,7 +67,12 @@ world!")``. .. cpp:function:: USBSerial::end() - Disables the USB peripheral. + Disables the USB peripheral. Note that using this function will + terminate all USB communications between the Maple and the USB + host; in particular, it implies that you won't be able to upload + any new programs without resetting the board or using + :ref:`perpetual bootloader mode + `. .. cpp:function:: unsigned int USBSerial::available() diff --git a/source/lang/api/toggleled.rst b/source/lang/api/toggleled.rst new file mode 100644 index 0000000..0cc20c2 --- /dev/null +++ b/source/lang/api/toggleled.rst @@ -0,0 +1,17 @@ +.. _lang-toggleled: + +toggleLED() +=========== + +Switches the LED from off to on, or on to off. + +Library Documentation +--------------------- + +.. doxygenfunction:: toggleLED + +See Also +-------- + +- :ref:`BOARD_LED_PIN ` +- :ref:`togglePin() ` diff --git a/source/lang/api/togglepin.rst b/source/lang/api/togglepin.rst new file mode 100644 index 0000000..290718d --- /dev/null +++ b/source/lang/api/togglepin.rst @@ -0,0 +1,17 @@ +.. _lang-togglepin: + +togglePin() +=========== + +Switches a digital output pin from :ref:`HIGH ` +to :ref:`LOW `, or from LOW to HIGH. + +Library Documentation +--------------------- + +.. doxygenfunction:: togglePin + +See Also +-------- + +- :ref:`toggleLED() ` diff --git a/source/lang/api/waitforbuttonpress.rst b/source/lang/api/waitforbuttonpress.rst new file mode 100644 index 0000000..34c5066 --- /dev/null +++ b/source/lang/api/waitforbuttonpress.rst @@ -0,0 +1,17 @@ +.. _lang-waitforbuttonpress: + +waitForButtonPress() +==================== + +Wait for the board's built-in button (labeled BUT on the silkscreen) +to be pressed, possibly with timeout. + +Library Documentation +--------------------- + +.. doxygenfunction:: waitForButtonPress + +See Also +-------- + +- :ref:`lang-isbuttonpressed` diff --git a/source/lang/cpp/built-in-types.rst b/source/lang/cpp/built-in-types.rst new file mode 100644 index 0000000..1323db8 --- /dev/null +++ b/source/lang/cpp/built-in-types.rst @@ -0,0 +1,95 @@ +.. highlight:: cpp + +.. _lang-built-in-types: + +================ + Built-in Types +================ + +This document serves as a reference for many of the built-in types +which are available when programming in the IDE. Programmers using +the :ref:`command-line tools ` will have access to +these types as long as they have imported `wirish.h +`_; +several are defined in in `libmaple_types.h +`_. + +.. _lang-built-in-types-integral: + +Integral types +-------------- + +.. cpp:type:: char + + 8-bit integer value. + +.. cpp:type:: short + + 16-bit integer value. + +.. cpp:type:: int + + 32-bit integer value. + +.. cpp:type:: long + + 64-bit integer value. + +.. cpp:type:: long long + + 64-bit integer value. + +.. cpp:type:: int8 + + Synonym for ``char``. + +.. cpp:type:: uint8 + + Synonym for ``unsigned char``. + +.. cpp:type:: int16 + + Synonym for ``short``. + +.. cpp:type:: uint16 + + Synonym for ``unsigned short``. + +.. cpp:type:: int32 + + Synonym for ``int``. + +.. cpp:type:: uint32 + + Synonym for ``unsigned int`` + +.. cpp:type:: int64 + + Synonym for ``long long`` + +.. cpp:type:: uint64 + + Synonym for ``unsigned long long``. + +Floating-Point Types +-------------------- + +.. cpp:type:: float + + 32-bit, IEEE 754 single-precision floating-point type. + +.. cpp:type:: double + + 64-bit, IEEE 754 double-precision floating-point type. + +Other Types +----------- + +.. cpp:type:: voidFuncPtr + + Pointer to a function that takes no arguments and returns nothing, i.e. + + :: + + typedef void (*voidFuncPtr)(void); + diff --git a/source/lang/cpp/keywords.rst b/source/lang/cpp/keywords.rst index e4ebe99..e3bc20d 100644 --- a/source/lang/cpp/keywords.rst +++ b/source/lang/cpp/keywords.rst @@ -94,7 +94,7 @@ The following keywords are used for built-in types. - :ref:`lang-float` - :ref:`lang-int` - :ref:`lang-long` -- :ref:`short ` +- :ref:`short ` - :ref:`void ` (not really a type, but used in the absence of one) diff --git a/source/lang/cpp/numeric-types.rst b/source/lang/cpp/numeric-types.rst deleted file mode 100644 index 9d2be48..0000000 --- a/source/lang/cpp/numeric-types.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _lang-numeric-types: - -Numeric types -============= - -This document serves as a reference for all of the built-in numeric -types which are available when programming in the IDE. Programmers -using the :ref:`command-line tools ` will have access -to these types as long as they have imported ``wirish.h``; several are -defined in in `libmaple_types.h -`_. - -.. _lang-numeric-types-integral: - -Integral types --------------- - -.. cpp:type:: char - - 8-bit integer value. - -.. cpp:type:: short - - 16-bit integer value. - -.. cpp:type:: int - - 32-bit integer value. - -.. cpp:type:: long - - 64-bit integer value. - -.. cpp:type:: long long - - 64-bit integer value. - -.. cpp:type:: int8 - - Synonym for ``char``. - -.. cpp:type:: uint8 - - Synonym for ``unsigned char``. - -.. cpp:type:: int16 - - Synonym for ``short``. - -.. cpp:type:: uint16 - - Synonym for ``unsigned short``. - -.. cpp:type:: int32 - - Synonym for ``int``. - -.. cpp:type:: uint32 - - Synonym for ``unsigned int`` - -.. cpp:type:: int64 - - Synonym for ``long long`` - -.. cpp:type:: uint64 - - Synonym for ``unsigned long long``. - -Floating-Point Types --------------------- - -.. cpp:type:: float - - 32-bit, IEEE 754 single-precision floating-point type. - -.. cpp:type:: double - - 64-bit, IEEE 754 double-precision floating-point type. diff --git a/source/lang/cpp/variables.rst b/source/lang/cpp/variables.rst index 9094cd5..e6da0c9 100644 --- a/source/lang/cpp/variables.rst +++ b/source/lang/cpp/variables.rst @@ -37,7 +37,7 @@ named ``inputVariable2``, with an initial value of ``0``:: int inputVariable2 = 0; The Maple environment comes ready to use with many useful types of -variables. See the :ref:`built-in types ` page +variables. See the :ref:`built-in types ` page for more information. Here are a few examples of declaring variables of different types:: @@ -116,7 +116,7 @@ he goes past the left side of the screen, he reappears on the right:: x = x + 1; // x now contains -2,147,483,648; rolled over "right to left" Each numeric type's reference page includes its range. See the -:ref:`built-in types ` reference for links to each +:ref:`built-in types ` reference for links to each type's reference page. Using Variables @@ -149,7 +149,7 @@ See Also -------- - :ref:`lang-scope` -- :ref:`lang-numeric-types` +- :ref:`lang-built-in-types` .. rubric:: Footnotes diff --git a/source/lang/cpp/void.rst b/source/lang/cpp/void.rst index 88bd448..88c9c64 100644 --- a/source/lang/cpp/void.rst +++ b/source/lang/cpp/void.rst @@ -5,10 +5,12 @@ ``void`` ======== -The ``void`` keyword is used only in function declarations. It -indicates that the function is expected to return no information to -the function from which it was called, or that it expects no arguments -from its caller. +.. cpp:type:: void + + The ``void`` keyword is used in function declarations. It indicates + that the function is expected to return no information to the + function from which it was called, or that it expects no arguments + from its caller. Example ------- diff --git a/source/lang/unimplemented/interrupts.rst b/source/lang/unimplemented/interrupts.rst deleted file mode 100644 index 55b8e93..0000000 --- a/source/lang/unimplemented/interrupts.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _lang-interrupts: - -interrupts() -============ - -Re-enables interrupts (after they've been disabled by -`noInterrupts `_\ ()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None - - - -Returns -------- - -None - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `noInterrupts `_\ () -- `attachInterrupt `_\ () -- `detachInterrupt `_\ () - - - - -.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/nointerrupts.rst b/source/lang/unimplemented/nointerrupts.rst deleted file mode 100644 index fb2e5f9..0000000 --- a/source/lang/unimplemented/nointerrupts.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _lang-nointerrupts: - -noInterrupts() -============== - -Description ------------ - -Disables interrupts (you can re-enable them with interrupts()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None. - - - -Returns -------- - -None. - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `interrupts `_\ () - - - - -.. include:: /lang/cc-attribution.txt diff --git a/source/language-index.rst b/source/language-index.rst index 7843cb0..e160e2b 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -4,37 +4,37 @@ Complete Language Index ======================= -This is the index of Maple's :ref:`language reference ` documentation. The 'Maple API' column includes language specific to Maple as a microcontroller development platform, while the language in 'C++ for Maple' is more generally applied. - -# Fix above explanation +This is the index of Maple's :ref:`language reference +` documentation. The "Maple API" column provides +API references for documented libmaple functionality. The "C++ for +Maple".. pages are adaptations of the Arduino C++ documentation to the +.. Maple, and are intended as a minimal reference/refresher for +.. programmers familiar with the Arduino language. .. _index-language-index-cpp: .. _index-language-index-api: -+--------------------------------------------+----------------------------------------------+ -| Maple API | :ref:`C++ for Maple ` | -| | | -+============================================+==============================================+ -| | | -| .. toctree:: | .. toctree:: | -| :maxdepth: 1 | :maxdepth: 1 | -| :glob: | :glob: | -| | | -| lang/api/* | lang/cpp/* | -| | | -+--------------------------------------------+----------------------------------------------+ - -.. Unfinished, unimplemented in libmaple: ++----------------------------------+------------------------------------+ +| Maple API | C++ for Maple | +| | | ++==================================+====================================+ +| | | +| .. toctree:: | .. toctree:: | +| :maxdepth: 1 | :maxdepth: 1 | +| :glob: | :glob: | +| | | +| lang/api/* | lang/cpp/* | +| | | ++----------------------------------+------------------------------------+ + +.. Unimplemented in libmaple or not part of current release: .. toctree:: :hidden: - lang/unimplemented/interrupts.rst - lang/unimplemented/nointerrupts.rst lang/unimplemented/notone.rst lang/unimplemented/pulsein.rst lang/unimplemented/shiftout.rst lang/unimplemented/stringclass.rst lang/unimplemented/stringobject.rst lang/unimplemented/tone.rst - diff --git a/source/language.rst b/source/language.rst index 8e5d454..018eb8c 100644 --- a/source/language.rst +++ b/source/language.rst @@ -52,8 +52,8 @@ Unique Maple Additions Maple Language Reference ------------------------ -The following table summarizes the available language features. A -more exhaustive index is available at the :ref:`language-index`. +The following table summarizes the available core language features. +A more exhaustive index is available at the :ref:`language-index`. +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | @@ -67,129 +67,129 @@ more exhaustive index is available at the :ref:`language-index`. |**Control Structures** |* :ref:`INPUT ` | | | | | :ref:`OUTPUT ` |* :ref:`digitalRead() ` | |* :ref:`if/else ` | | | -| |* :ref:`true ` | | | -|* :ref:`for ` | :ref:`false ` |**Analog I/O** | +| |* :ref:`true ` | |* :ref:`togglePin() ` | +|* :ref:`for ` | :ref:`false ` | | +| | |* :ref:`toggleLED() ` | +|* :ref:`switch/case ` |* :ref:`BOARD_LED_PIN ` | | | +| | :ref:`BOARD_BUTTON_PIN `|* :ref:`isButtonPressed() ` | +|* :ref:`while ` | | | +| |* :ref:`Constants |* :ref:`waitForButtonPress() | +|* :ref:`do...while ` | ` (:ref:`integers | ` | +| | `, :ref:`floating | | +|* :ref:`break ` | point `) |**Analog I/O** | | | | | -|* :ref:`switch/case ` |* :ref:`Constants |* :ref:`analogRead() ` | -| | ` (:ref:`integers | | -|* :ref:`while ` | `, :ref:`floating |* :ref:`pwmWrite() ` | -| | point `) | (:ref:`analogWrite() ` is | -|* :ref:`do...while ` | | also available, though its use is discouraged) | -| |**Data Types** | | -|* :ref:`break ` | | | -| | The size of each datatype, in bytes, is |**Advanced I/O** | -|* :ref:`continue ` | given in parentheses where appropriate. | | -| | |* tone(): TODO | -|* :ref:`return ` | *Note*: The ``word`` type is (deliberately) | | -| | :ref:`not supported `. |* noTone(): TODO | -|* :ref:`goto ` | | | -| |* :ref:`void ` |* shiftOut(): TODO | +|* :ref:`continue ` |**Data Types** |* :ref:`analogRead() ` | | | | | -|**Further syntax** |* :ref:`boolean ` (1 byte) |* pulseIn(): TODO | +|* :ref:`return ` | The size of each datatype, in bytes, is |* :ref:`pwmWrite() ` | +| | given in parentheses where appropriate. | (:ref:`analogWrite() ` is | +|* :ref:`goto ` | | also available, though its use is discouraged) | +| | *Note*: The ``word`` type is (deliberately) | | +| | :ref:`not supported `. | | +|**Further syntax** | |**Advanced I/O** | +| |* :ref:`void ` | | +|* :ref:`; (semicolon) ` | |* tone(): TODO | +| |* :ref:`boolean ` (1 byte) | | +|* :ref:`{} (curly braces) | |* noTone(): TODO | +| ` |* :ref:`char ` (1 byte) | | +| | |* shiftOut(): TODO | +|* :ref:`// (single-line comment) |* :ref:`unsigned char | | +| ` | ` (1 byte) |* pulseIn(): TODO | | | | | -|* :ref:`; (semicolon) ` |* :ref:`char ` (1 byte) | | -| | |**Time** | -|* :ref:`{} (curly braces) |* :ref:`unsigned char | | -| ` | ` (1 byte) |* :ref:`millis() ` | +|* :ref:`/\* \*/ (multi-line comment) |* :ref:`byte ` (1 byte) | | +| ` | |**Time** | +| |* :ref:`int ` (4 bytes) | | +|* :ref:`#define ` | |* :ref:`millis() ` | +| |* :ref:`unsigned int ` | | +|* :ref:`#include ` | (4 bytes) |* :ref:`micros() ` | | | | | -|* :ref:`// (single-line comment) |* :ref:`byte ` (1 byte) |* :ref:`micros() ` | -| ` | | | -| |* :ref:`int ` (4 bytes) |* :ref:`delay() ` | -|* :ref:`/\* \*/ (multi-line comment) | | | -| ` |* :ref:`unsigned int ` |* :ref:`delayMicroseconds() | -| | (4 bytes) | ` | -|* :ref:`#define ` | | | -| |* :ref:`long ` (8 bytes) | | -|* :ref:`#include ` | |**Math** | -| |* :ref:`unsigned long ` | | -| | (8 bytes) |* :ref:`min() ` | +| |* :ref:`long ` (8 bytes) |* :ref:`delay() ` | |**Arithmetic Operators** | | | -| |* :ref:`float ` (4 bytes) |* :ref:`max() ` | -|* :ref:`= ` | | | -| (assignment operator) |* :ref:`double ` (8 bytes) |* :ref:`abs() ` | +| |* :ref:`unsigned long ` |* :ref:`delayMicroseconds() | +|* :ref:`= ` | (8 bytes) | ` | +| (assignment operator) | | | +| |* :ref:`float ` (4 bytes) | | +|* :ref:`+ ` (addition) | |**Math** | +| |* :ref:`double ` (8 bytes) | | +|* :ref:`- ` | |* :ref:`min() ` | +| (subtraction) |* :ref:`Strings ` | | +| | |* :ref:`max() ` | +|* :ref:`* ` |* :ref:`Arrays ` | | +| (multiplication) | |* :ref:`abs() ` | +| |* :ref:`enum ` | | +|* :ref:`/ ` (division) | |* :ref:`constrain() ` | +| |* :ref:`Numeric types ` | | +|* :ref:`% ` (modulo) | |* :ref:`map() ` | +| |**Conversion** | | +| | |* :ref:`pow() ` | +|**Comparison Operators** |* :ref:`char() ` | | +| | |* :ref:`sqrt() ` | +|* :ref:`== ` (equal to) |* :ref:`byte() ` | | | | | | -|* :ref:`+ ` (addition) |* :ref:`Strings ` |* :ref:`constrain() ` | +|* :ref:`\!= ` |* :ref:`int() ` |**Trigonometry** | +| (not equal to) | | | +| |* :ref:`long() ` |* :ref:`sin() ` | +|* :ref:`< ` (less than) | | | +| |* :ref:`float() ` |* :ref:`cos() ` | +|* :ref:`> ` | | | +| (greater than) |* :ref:`double() ` |* :ref:`tan() ` | | | | | -|* :ref:`- ` |* :ref:`Arrays ` |* :ref:`map() ` | -| (subtraction) | | | -| |* :ref:`enum ` |* :ref:`pow() ` | -|* :ref:`* ` | | | -| (multiplication) |* :ref:`Numeric types ` |* :ref:`sqrt() ` | +|* :ref:`<= ` | | | +| (less than or equal to) |**Variable Scope & Qualifiers** |**Random Numbers** | | | | | -|* :ref:`/ ` (division) |**Conversion** | | -| | |**Trigonometry** | -|* :ref:`% ` (modulo) |* :ref:`char() ` | | -| | |* :ref:`sin() ` | -| |* :ref:`byte() ` | | -|**Comparison Operators** | |* :ref:`cos() ` | -| |* :ref:`int() ` | | -|* :ref:`== ` (equal to) | |* :ref:`tan() ` | -| |* :ref:`long() ` | | -|* :ref:`\!= ` | | | -| (not equal to) |* :ref:`float() ` |**Random Numbers** | +|* :ref:`>= ` |* :ref:`variables `, |* :ref:`randomSeed() ` | +| (greater than or equal to) | :ref:`scope ` | | +| | |* :ref:`random() ` | +| |* :ref:`static ` | | +|**Boolean Operators** | | | +| |* :ref:`volatile ` |**Bits and Bytes** | +|* :ref:`&& ` (and) | | | +| |* :ref:`const ` |* :ref:`lowByte() ` | +|* :ref:`|| ` (or) | | | +| | |* :ref:`highByte() ` is | +|* :ref:`\! ` (not) |**Utilities** | provided, though its use is discouraged. | | | | | -|* :ref:`< ` (less than) |* :ref:`double() ` |* :ref:`randomSeed() ` | -| | | | -|* :ref:`> ` | |* :ref:`random() ` | -| (greater than) |**Variable Scope & Qualifiers** | | -| | | | -|* :ref:`<= ` |* :ref:`variables `, |**Bits and Bytes** | -| (less than or equal to) | :ref:`scope ` | | -| | |* :ref:`lowByte() ` | -|* :ref:`>= ` |* :ref:`static ` | | -| (greater than or equal to) | |* :ref:`highByte() ` is | -| |* :ref:`volatile ` | provided, though its use is discouraged. | -| | | | -|**Boolean Operators** |* :ref:`const ` |* :ref:`bitRead() ` | -| | | | -|* :ref:`&& ` (and) | |* :ref:`bitWrite() ` | -| |**Utilities** | | -|* :ref:`|| ` (or) | |* :ref:`bitSet() ` | -| |* :ref:`sizeof() ` | | -|* :ref:`\! ` (not) | |* :ref:`bitClear() ` | -| | | | -| | |* :ref:`bit() ` | +| |* :ref:`sizeof() ` |* :ref:`bitRead() ` | |**Pointer Operators** | | | +| | |* :ref:`bitWrite() ` | +|* :ref:`* dereference operator | | | +| ` | |* :ref:`bitSet() ` | | | | | -|* :ref:`* dereference operator | |**External Interrupts** | +|* :ref:`& reference operator | |* :ref:`bitClear() ` | | ` | | | -| | |* :ref:`Reference Page ` | -|* :ref:`& reference operator | | | -| ` | |* :ref:`attachInterrupt() | -| | | ` | +| | |* :ref:`bit() ` | | | | | -|**Bitwise Operators** | |* :ref:`detachInterrupt() | -| | | ` | +|**Bitwise Operators** | | | +| | |**External Interrupts** | |* :ref:`& ` | | | -| (bitwise and) | | | -| | |**Interrupts** | -|* :ref:`| ` | | | -| (bitwise or) | |* interrupts(): TODO | +| (bitwise and) | |* :ref:`Reference Page ` | | | | | -|* :ref:`^ ` | |* noInterrupts(): TODO | -| (bitwise xor) | | | +|* :ref:`| ` | |* :ref:`attachInterrupt() | +| (bitwise or) | | ` | | | | | -|* :ref:`~ ` | |**Communication** | -| (bitwise not) | | | -| | |* :ref:`SerialUSB ` | -|* :ref:`\<\< ` | | | -| (shift left) | |* :ref:`Serial ` | +|* :ref:`^ ` | |* :ref:`detachInterrupt() | +| (bitwise xor) | | ` | | | | | -|* :ref:`>> ` | |**Looking for something else?** | -| (shift right) | | | -| | | See the :ref:`libraries` page for interfacing with| -| | | particular types of hardware. Maple links | -|**Compound Operators** | | against `newlib `_ | -| | | and allows the use of any of its functions; see | -|* :ref:`++ ` | | its documentation for more details. | -| (increment) | | | +|* :ref:`~ ` | | | +| (bitwise not) | |**Interrupts** | | | | | -|* :ref:`- - ` | | | -| (decrement) | | | +|* :ref:`\<\< ` | |* :ref:`interrupts() ` | +| (shift left) | | | +| | |* :ref:`noInterrupts() ` | +|* :ref:`>> ` | | | +| (shift right) | | | +| | |**Communication** | | | | | -|* :ref:`+= ` | | | -| (compound add) | | | +|**Compound Operators** | |* :ref:`SerialUSB ` | | | | | +|* :ref:`++ ` | |* :ref:`Serial ` | +| (increment) | | | +| | |**Looking for something else?** | +|* :ref:`- - ` | | | +| (decrement) | | See the :ref:`libraries` page for interfacing with| +| | | particular types of hardware. Maple links | +|* :ref:`+= ` | | against `newlib `_ | +| (compound add) | | and allows the use of any of its functions; see | +| | | its documentation for more details. | |* :ref:`-= | | | | ` (compound | | | | subtract) | | | @@ -222,6 +222,8 @@ more exhaustive index is available at the :ref:`language-index`. Missing Arduino Features ------------------------ +.. _langage-missing-analogreference: + **analogReference()** It is not possible to implement this function on the Maple @@ -256,8 +258,6 @@ Unimplemented Arduino Features The following Wiring/Arduino features are currently unimplemented on the Maple. However, they will be present in future versions: -- `interrupts() `_ -- `noInterrupts() `_ - `noTone() `_ - `pulseIn() `_ - `shiftOut() `_ @@ -272,7 +272,11 @@ the Maple. However, they will be present in future versions: C++ for Maple -------------- -If you haven't programmed in C++, or if you just need to jog your memory, you may want to check out our :ref:`C++ for Maple Index`. It covers programming ideas and C++ that will definitely come in handy. + +If you haven't programmed in C++, or if you just need to jog your +memory, you may want to check out our :ref:`Language Index +`. It provides some introductory coverage of +programming ideas and C++. .. _arduino_c_for_c_hackers: @@ -366,9 +370,7 @@ contains ``setup()`` and ``loop()``:: } void loop() { - static int toggle = 0; - toggle ^= 1; - digitalWrite(the_pin, toggle); + togglePin(the_pin); } The second file contains the (not very useful) implementation for @@ -388,9 +390,7 @@ Then the results of the concatenation process might be :: } void loop() { - static int toggle = 0; - toggle ^= 1; - digitalWrite(the_pin, toggle); + togglePin(the_pin); } int choose_a_pin(void); @@ -415,9 +415,7 @@ Which could plausibly be turned into the final source file :: } void loop() { - static int toggle = 0; - toggle ^= 1; - digitalWrite(the_pin, toggle); + togglePin(the_pin); } int choose_a_pin(void); @@ -441,7 +439,6 @@ Recommended Reading * `newlib Documentation `_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) * `Programming Manual `_ (assembly language and register reference) diff --git a/source/libraries.rst b/source/libraries.rst index 567aec8..7623963 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -21,13 +21,69 @@ in the description of the library. .. contents:: Contents :local: +.. toctree:: + :hidden: + + libs/servo.rst + +.. _libraries-servo: + +Servo +----- + +The Servo library is provided for convenient control of RC +servomotors. For more information, see the :ref:`Servo ` +reference. + +**Compatibility Note** + +The Servo class provides a public interface identical to the Arduino +version's documented functionality (as of Arduino 0021), so in most +cases, this library will be a drop-in replacement. + +However, there are some differences, essentially at the level of +implementation details. + +The major difference is that while the Arduino implementation drives +the servos with "bit-banged" :ref:`PWM `, the Maple +implementation uses :ref:`timers ` to drive the PWM directly. + +Consequently, **the Maple implementation only allows Servo instances +to** :ref:`attach ` **to pins that support PWM**. + +To determine if a pin supports PWM (15 Maple pins do), you can either +check if "PWM" appears next to its number on the Maple silkscreen, or +consult the :ref:`pwmWrite() ` documentation. + +RC Servos expect a pulse approximately every 20ms. In the Maple +implementation, :ref:`periods ` are set +for entire timers, rather than individual channels. Thus, +``attach()``\ ing a Servo to a pin can interfere with other pins +associated with the same timer\ [#fard-servo]_. + +Because of this, we recommend connecting multiple servomotors to pins +which share a timer, in order to keep as many timers free for other +purposes as possible. Consult the :ref:`table provided in the timers +reference ` to match up pins and timer +channels. + +Another difference: although it is not publicly documented to do so, +the Arduino implementation of `attach() +`_ returns the timer +channel associated with the newly-attached pin, or 0 on failure (as of +Arduino 0021). The Maple implementation returns true on success, and +false on failure (and this is its documented behavior). + .. _libraries-liquid-crystal: LiquidCrystal ------------- +.. TODO 0.0.10 make our own LiquidCrystal docs + The LiquidCrystal library allows Maple to control LCD screens. For -more information, see the Arduino LiquidCrystal documentation. +more information, see the `Arduino LiquidCrystal documentation +`_. **Compatibility Note** @@ -57,6 +113,8 @@ the hardware i2c peripheral on the stm32 as well as the DMA for performance. Support for slave, smBUS, and multimaster modes are also slated for inclusion in the enhanced Wire port. +.. TODO 0.0.10 Wire docs in the cpp domain in own page under /libs/ + Wire Function Reference ^^^^^^^^^^^^^^^^^^^^^^^ @@ -127,3 +185,10 @@ Wire Function Reference Returns the number of bytes which are still available for reading (with ``Wire.receive()``) from the last call to ``Wire.requestFrom(uint8, int)``. + +.. rubric:: Footnotes + +.. [#fard-servo] The Arduino implementation also captures timer + channels in groups as more Servo objects are attached, but the + details of which channels have their periods reset when are + slightly different. diff --git a/source/libs/servo.rst b/source/libs/servo.rst new file mode 100644 index 0000000..f92fd91 --- /dev/null +++ b/source/libs/servo.rst @@ -0,0 +1,108 @@ +.. highlight:: cpp + +.. _libs-servo: + +======= + Servo +======= + +This documents the Servo library for controlling RC servomotors. It +is implemented as a thin layer over the built-in :ref:`timer +peripherals `. + +You can use this library in the :ref:`IDE ` by choosing the Servo +item under the Sketch > Import Library... menu. + +If you are using the :ref:`Unix toolchain `, the +library is located in ``$LIB_MAPLE_HOME/libraries/Servo/``. + +Servo Class Reference +--------------------- + +You can construct a Servo object by including the declaration :: + + Servo servo; + +in your sketch. This will create a Servo object called ``servo``. +You can then use any of its methods; for instance, to control a +servomotor attached to pin 9, you could write :: + + servo.attach(9); + +.. cpp:class:: Servo + + Class for controlling RC servomotors via :ref:`timers `. + +.. _libs-servo-attach: + +.. cpp:function:: bool Servo::attach(uint8 pin, uint16 min, uint16 max) + + Attach this Servo object to the given ``pin``. The pin must be + capable of PWM. You can check this by seeing if "PWM" is written + next to its number on the Maple silkscreen, or by consulting the + :ref:`pwmWrite() ` documentation. + + Sets this pin's :ref:`mode ` to :ref:`PWM + `, and returns true if successful. + Does nothing and returns false if the pin doesn't support PWM. + + Parameter ``min`` is the pulse width corresponding to 0 degrees; + ``max`` is the pulse width corresponding to 180 degrees (both are + in microseconds). + +.. cpp:function:: bool Servo::attach(uint8 pin) + + Equivalent to :ref:`attach(pin, 544, 2400) `. + +.. _libs-servo-attached: + +.. cpp:function:: int Servo::attached() const + + If currently attached (via :ref:`attach() `) to + a pin, returns that pin's number. Returns ``NOT_ATTACHED`` + otherwise. + +.. cpp:function:: bool Servo::detach() + + If this Servo object is currently attached to pin, stops driving + the servo by setting a zero pulse width (this is accomplished by + setting the associated :ref:`channel mode + ` to ``TIMER_DISABLED``). + + Subsequently, calling :ref:`attached() ` will + return ``NOT_ATTACHED``. + +.. cpp:function:: void Servo::write(unsigned int value) + + If ``value`` is less than ``SERVO_MAX_WRITE_ANGLE`` (which, for + Arduino compatibility, is 200), it's interpreted as an angle in + degrees. Otherwise, it's treated as a pulse width in microseconds. + + Drives the servo to target the given angle, based on a linear + interpolation of the ``min`` and ``max`` pulse widths determined + when :ref:`attach() ` was called. + + Be aware that some (especially lower-cost) servos have fairly + non-linear maps between pulse width and target angle. Make sure to + test your motor before relying on this method. + +.. cpp:function:: void Servo::writeMicroseconds(uint16 pulseWidth) + + Drives the servo using a ``pulseWidth``-microsecond pulse. + + If ``pulseWidth`` is outside of the [``min``, ``max``\ ] pulse + width range set during :ref:`attach() `, it will + be clamped to lie in this range. + +.. cpp:function:: int Servo::read() const + + Returns the servo's target angle, in degrees. This will be clamped + to lie between 0 (when the pulse width is at most ``min``) and 180 + (when the pulse width is at least ``max``). + +.. cpp:function:: uint16 Servo::readMicroseconds() const + + Returns the pulse width of the wave currently driving the servo, in + microseconds. This will be clamped to lie in the [``min``, + ``max``\ ] pulse width range set during :ref:`attach() + `. diff --git a/source/pwm.rst b/source/pwm.rst index fd72842..1a8f4df 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -28,9 +28,9 @@ Note that unlike the Arduino, the Maple does not have PWM functionality on pin D10; all other pins are :ref:`compatible `. -The following table shows which :ref:`timer ` generates which -PWM outputs. See the :ref:`pin mapping table ` -to track down exactly which timer *channel* corresponds to each pin. +The following table shows which timer can generate which PWM +outputs. See the :ref:`pin mapping table ` to +track down exactly which timer *channel* corresponds to each pin. .. _pwm-timer-table: @@ -65,12 +65,13 @@ The Maple has 16-bit PWM resolution, which means that the counter and variables can be as large as 65535, as opposed to 255 with 8-bit resolution. With a 72MHz clock rate, a PWM output could have maximum period of about one millisecond; using a :ref:`prescaler -` (clock divider) in front of the counter can increase -this maximum period. Setting the :ref:`period ` to -something other than the maximum value gives further control over the -total length of the waveform. However, this effectively limits the -resolution with which the duty can be modified: the duty must be less -than or equal to the period. +` (clock divider) in front of +the counter can increase this maximum period. Setting the +:ref:`period ` to something other than +the maximum value gives further control over the total length of the +waveform. However, this effectively limits the resolution with which +the duty can be modified: the duty must be less than or equal to the +period. Here are some commonly used PWM configurations (note that servos are notoriously variable, especially the lower cost models): @@ -93,82 +94,13 @@ notoriously variable, especially the lower cost models): Function Reference ------------------ -``pinMode(pin_num, PWM)`` - - This command is usually called from :ref:`setup() ` to - tell the microcontroller that pin_num should be configured to PWM - output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` - is also available (see the list of :ref:`GPIO modes ` - for more information). - -.. _pwm-pwmwrite: - -``pwmWrite(pin_num, value)`` - - This command sets the PWM duty. User code is expected to determine - and honor the maximum value (based on the configured period). As a - convenience, ``analogWrite`` is an alias for ``pwmWrite`` to ease - porting Arduino code, though period and duty will have to be - recalibrated (see :ref:`compatibility `). - -.. _pwm-overflow: - -``Timer[1,2,3,4].setOverflow(overflow)`` - - This function sets the period ("reload" or "overflow") value for - an entire PWM timer bank. The value is 16bit (0 to 65535) and - determines the maximum value that can be written with - :ref:`pwmWrite() ` corresponding to 100% duty - cycle. This also affects the PWM frequency: the higher reload is, - the lower the PWM frequency will be. - - The PWM output pin starts HIGH, then the timer begins counting up - from zero (with frequency equal to 72MHz/:ref:`prescaler - `) until it hits the duty value, at which point it - drops to LOW. The timer then continues counting up until it hits - the total period (set with this function), at which point the - cycle starts again. - -.. _pwm-prescaler: - -``Timer[1,2,3,4].setPrescaleFactor(prescale)`` - - Find the appropriate timer for a given PWM header using the table - :ref:`above `, then set the prescaler. A - prescaler is a clock divider. The timer will normally count with - frequency equal to the STM32's normal clock (72MHz); this - corresponds to setting ``prescale`` to 1 (which is the default). - - If a longer frequency is desired, use a larger ``prescale`` value. - For instance, an 8MHz frequency can be achieved by setting - ``prescale`` to 9, since 72MHz / 9 = 8MHz. - - This function is normally called once from, :ref:`lang-setup`, but - the timer can be reconfigured with a new prescaler at any time. - - * Configure the prescaler and overflow values to generate a timer - * reload with a period as close to the given number of - * microseconds as possible. - * - * The return value is the overflow, which may be used to set - * channel compare values. However, if a clock that fires an - * interrupt every given number of microseconds is all that is - * desired, and the relative "phases" are unimportant, channel - * compare values may all be set to 1. - -``Timer[1,2,3,4].setPeriod(period_in_microseconds)`` - - Configure the prescaler and overflow values to generate a timer - reload with a period as close to the given number of microseconds - as possible. - - The return value is the overflow, which may be used to set channel - compare values. However, if a clock that fires an interrupt every - given number of microseconds is all that is desired, and the - relative "phases" are unimportant, channel compare values may all - be set to 1. - - +- :ref:`lang-pinmode` +- :ref:`lang-pwmwrite` +- :ref:`Timer API` (especially :ref:`setOverflow() + `, :ref:`setPrescaleFactor() + `, and :ref:`setPeriod() + `). +- :ref:`Timers reference `. Recommended Reading ------------------- @@ -182,6 +114,5 @@ Recommended Reading * `So You Want To Use PWM, Eh? `_ at Non-Lexical Vocables * STMicro documentation for STM32F103RB microcontroller: - * `All `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) diff --git a/source/spi.rst b/source/spi.rst index ca9415c..ba43eef 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -4,54 +4,16 @@ SPI ===== -The Maple has two SPI ports. The first has NSS on D10, MOSI on D11, -MISO on D12, and SCK on D13. The second has NSS on D31, SCK on D32, -MISO on D33, and MOSI on D34. +The Serial Peripheral Interface Bus (SPI) is a serial data transfer +protocol useful for interacting with a wide variety of hardware +peripherals. -.. _spi-speeds: +The Maple has two SPI ports. The first has NSS on D10, MOSI on +D11, MISO on D12, and SCK on D13. The second has NSS on D31, SCK on +D32, MISO on D33, and MOSI on D34. -Each port can be configured at one of the following speeds: - -* ``SPI_18MHZ``: 18 MHz -* ``SPI_9MHZ``: 9 MHz -* ``SPI_4_5MHZ``: 4.5 MHz -* ``SPI_2_25MHZ``: 2.25 MHz -* ``SPI_1_125MHZ``: 1.124 MHz -* ``SPI_562_500KHZ``: 562.500 KHz -* ``SPI_281_250KHZ``: 281.250 KHz -* ``SPI_140_625KHZ``: 140.625 KHz - -.. contents:: Contents - :local: - -Function Reference ------------------- - -``HardwareSPI Spi(number);`` - - This declaration must be included at the start of any sketch or - program that uses the SPI interface. The argument number is either - 1 or 2 and specifies which port to use. - -``Spi.begin(freq, endianness, mode)`` - - ``begin`` is usually called in :ref:`lang-setup` to configure the - baudrate of the given SPI port and to set up the header pins - appropriately. ``freq`` is one of the set listed :ref:`above - `; ``endianness`` is either ``LSBFIRST`` or - ``MSBFIRST``; mode is one of 0, 1, 2, 3, and specifies which "SPI - Mode" is used (see specification docs linked below). - -``Spi.begin()`` - - A default ``begin`` with no arguments is provided for the lazy; it - is equivalent to ``Spi.begin(SPI_1_125MHZ, MSBFIRST, 0)``. - -``Spi.send(data, size)`` - - Writes data into the port buffer to be transmitted as soon as - possible. ``data`` should be an array of type ``byte*``; ``size`` - should be the number of elements in ``data``. +The public libmaple API for managing the SPI ports is the +:ref:`HardwareSpi ` class. Recommended Reading ------------------- @@ -63,7 +25,6 @@ Recommended Reading * `Hardcore SPI on Arduino `_ by kik64 * STMicro documentation for STM32F103RB microcontroller: - * `All `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) diff --git a/source/timers.rst b/source/timers.rst index 948805b..56dd686 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -8,25 +8,46 @@ Timers There are four general purpose timers in the Maple microcontroller that can be configured to generate periodic or delayed events with minimal work done by the microcontroller. For example, the :ref:`PWM -` channels, once enabled, generate regular square-wave signals on -specific output pins that will continue even if the microcontroller is -busy crunching numbers or handling communications interrupts. By -attaching interrupt handlers to these channels (instead of just -changing the voltage on an external pin), more complex events like -printing to a serial port, updating a variable, or emitting a whale -mating call can be scheduled. You can even modify the configuration of -the timer itself at a regular interval; the possibilities are endless! - -The four timers each have four separate compare channels. Each timer -is a single 16-bit counter that can be configured with both a -prescaler and an overflow value. The prescaler acts as a divider of -the 72MHz system clock; without prescaling the counter would get up to -65536 (2 to the 16th power) and roll over more than a thousand times a -second; even with the full prescaler it rolls over about once a -minute. The overflow value is the maximum value the counter will go up -to. It defaults to the full 65535; smaller values will cause the -counter to reset to zero more frequently. +` channels can generate regular square-wave signals on specific +output pins without consuming extra clock cycles. By attaching +interrupt handlers to these channels (instead of just changing the +voltage on an external pin), more complex events can be scheduled. + +.. contents:: Contents + :local: + +Introduction +------------ + +.. _timers-prescale: + +The four timers each have four separate compare channels. Each channel +has an associated 16-bit counter that can be configured with a 16-bit +prescaler and a 16-bit overflow value. The prescaler determines how +fast the counter changes, while the overflow value determines when it +gets reset. + +The prescaler acts as a divider of the 72MHz system clock. That is, +with a prescaler of 1, the channel's counter increments with a +frequency of 72MHz, rolling over (passing the maximum 16-bit unsigned +integer value of 65,535) more than a thousand times a second. With a +prescaler of 7200, it has a frequency of (72/7200) MHz = 10 KHz, +rolling over approximately every 6.55 seconds. + +The overflow value is the maximum value the counter will go up to. It +defaults to the full 65,535; smaller values will cause the counter to +reset to zero more frequently. + +Whenever a channel's counter reaches its overflow value, an "update +event" interrupt is generated. You can configure the Maple to notify +you when this takes place, by registering an interrupt handler, which +is a function that will be called when the update event occurs. + +libmaple Reference +------------------ +The libmaple API for interacting with timers is documented at the +:ref:`HardwareTimer reference `. Caveats ------- @@ -36,9 +57,18 @@ Caveats **PWM Conflicts:** Because PWM functionality on a given pin depends on the configuration of the timer and channel, you must chose your channels carefully if you want to use both timer interrupts and PWM in -the same program. Refer to the full :ref:`pin mapping table -` to match up timer channels and Maple header -pin numbers. +the same program. Refer to the following table to match up timer +channels and Maple header pin numbers: + +.. _timers-pin-channel-map: + +.. csv-table:: + :header: Timer, Ch. 1 pin, Ch. 2 pin, Ch. 3 pin, Ch. 4 pin + + ``Timer1``, 6, 7, 8, -- + ``Timer2``, 2, 3, 1, 0 + ``Timer3``, 12, 11, 27, 28 + ``Timer4``, 5, 9, 14, 24 **Overhead:** there is some overhead associated with function and interrupt calls (loading and unloading the stack, preparing state, @@ -59,7 +89,8 @@ configuration being the same. auto-reset and communications functionality. This will require that you put your Maple into :ref:`perpetual bootloader mode ` before uploading a new - program to it. + program to it (or somehow causing your program to re-enable serial + over USB using :ref:`SerialUSB.begin() `). Disabling SysTick with ``systick_disable()`` helps as well. However, calling this function will break the ``micros()`` and @@ -73,33 +104,6 @@ a handler isn't going to block other interrupts from firing (e.g. USB, Serial, SysTick) if those other interrupts are important for your program. -.. _timers-modes: - -General Timer Modes -------------------- - -``TIMER_DISABLED`` - - Exactly what it sounds like: the timer stops counting, interrupts - are not called, and no state changes are output. - -``TIMER_PWM`` - - This is the default mode for pins after initialization. See the - :ref:`PWM docs ` for more information on this mode. - - .. note:: - - ``Timer1.setChannel1Mode(TIMER_PWM)`` may not work as expected; - if you want PWM functionality on a channel, make sure you don't - set it to something else. - -``TIMER_OUTPUTCOMPARE`` - - In this mode, the timer counts from 0 to the overflow value - repeatedly; every time the counter value reaches one of the - channel compare values, the corresponding interrupt is fired. - SysTick Peripheral ------------------ @@ -111,136 +115,22 @@ VGA code, where the timing jitters are transformed into visual jags in the image. The SysTick peripheral can be disabled by calling ``systick_disable()``, and re-enabled using ``systick_resume()``. -Function Reference ------------------- - -For all of these functions, ``Timer1`` can be replaced with -``Timer2``, ``Timer3``, or ``Timer4``; the channel numbers also range -from 1 to 4. - -``Timer1.pause()``/\ ``Timer1.resume()`` - - These functions start and stop the counter without affecting the - rest of the configuration. These functions can be used during the - setup period to prevent interrupts from firing before they are - completely configured. Note that there is some function call - overhead with these functions, so they are not a perfect way to - align multiple timers to the same count value. - -``Timer1.setOverflow(val)`` - - Sets the overflow (or "reload") value for the whole timer; when - the counter reaches this value it resets to zero. Defaults to - 65535 (the largest unsigned 16bit integer); setting it to anything - lower will cause interrupts to be called more frequently (see the - setPeriod function below for a shortcut). This number sets the - maximum value for the channel compare values. - -``Timer1.setPrescaleFactor(val)`` - - The prescaler acts as a clock divider to slow down the rate at - which the counter increments. For example, the system clock rate - is 72MHz, so the counter will reach 65535 in (13.89 nanoseconds) * - (65535 counts) = (910.22 microseconds), or about a thousand times - a second. If you set the prescaler to 1098, then the clock rate is - effectively 65.56KHz, and the counter will reach 65536 in (15.25 - microseconds) * (65536 counts) = (0.999 seconds), or just about - once a second. Use the :ref:`setPeriod ` - function below if you are allergic to math! - -.. _timers-set-period: - -``Timer1.setPeriod(val)`` - - This tricky trick will configure the prescaler and overflow values - to generate a timer reload with a period as close to val - microseconds as possible. It returns the chosen overflow value, - which you can then use to set the channel compare values - appropriately: if you just want the interrupts to fire when the - clock rolls over and you don't care about the relative "phase", - you can always set the channel compare values to 1. - - Remember: a microsecond is 1/1,000,000th of a second, or 1/1,000 - of a millisecond. The prescaler itself is 16bit, so the longest - period that can be configured is 1/(72MHz) * (2^32) = (59.65 - seconds) or about a minute. You can get around this by creating an - interrupt that increments a 32-bit variable, by using the - ``millis()`` function, or by interfacing with an external - real-time-clock chip. - -``Timer1.setCount(val)``/\ ``Timer1.getCount()`` - - These functions let you mess with the counter's brains - directly. You can probably make it not work if you try! The timer - is 16bit, so ``val`` and the return value of ``getCount`` are - ``uint16``. - -``Timer1.setChannel1Mode(MODE)`` - - This sets the given channel (here 1) of the given timer (here 1) - to the given mode. See the :ref:`list above ` for - possible values; for interrupts you want ``TIMER_OUTPUTCOMPARE``. - -``Timer1.setCompare1(val)`` - - Sets the compare value for the given channel; when the counter - reaches this value the interrupt for this channel will fire if the - channel is in output compare mode and an interrupt is attached. - - By default this only changes the relative offsets between events - on a single timer ("phase"); they don't control the frequency with - which they occur. However, a common trick is to increment the - compare value manually in the interrupt handler so that the event - will fire again after the increment period. There can be a - different increment value for each channel, so this trick allows - events to be programmed at 4 different rates on a single timer! - Note that function call overhead means that the smallest increment - rate is a couple microseconds. - -.. _timers-attachinterrupt: -.. _timers-detachinterrupt: - -``Timer1.attachCompare1Interrupt(function)``/\ ``Timer1.detachCompare1Interrupt()`` - - This is how to attach or disable an interrupt handlers to timer - channels; this what will get called when the counter reaches the - compare value set with ``setCompareN(val)``. ``function`` - (sometimes referred to as an ISR: "interrupt service routine") - should be of a type that does not accept or return any values - (C/C++ programmers: ``void (function*)(void)``). They are just - like any other function in your sketch/program and must be - initialized at the top of the file and defined below. - - ``function`` should try to do what it has to do as fast as - possible. Blinking the LED, some logic, PWM updates, and Serial - writes are fine; writing to SerialUSB or waiting for user input - can take a long time and other compare interrupts won't fire. Tip: - if you have a ``delay()`` in your ISR, you're probably doing it - wrong. - - Stay vigilant here... function pointers are serious business, and - once you go down that path you'll find yourself in a `forest of - parentheses `_ before you know it. - Code Examples ------------- LED blink ^^^^^^^^^ -\ :: +:: - #define LED_PIN 13 #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles void handler_led(void); - int toggle = 0; - void setup() { // Set up the LED to blink - pinMode(LED_PIN, OUTPUT); + pinMode(BOARD_LED_PIN, OUTPUT); // Setup Timer Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); @@ -254,16 +144,13 @@ LED blink } void handler_led(void) { - toggle ^= 1; - digitalWrite(LED_PIN, toggle); + toggleLED(); } Racing Counters ^^^^^^^^^^^^^^^ -\ :: - - #define BUTTON_PIN 38 +:: void handler_count1(void); void handler_count2(void); @@ -274,7 +161,7 @@ Racing Counters void setup() { // Set up BUT for input - pinMode(BUTTON_PIN, INPUT_PULLUP); + pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); // Setup Counting Timers Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); @@ -302,7 +189,7 @@ Racing Counters // Run... while BUT is held, pause Count2 for(int i = 0; i<1000; i++) { - if(digitalRead(BUTTON_PIN)) { + if(digitalRead(BOARD_BUTTON_PIN)) { Timer4.pause(); } else { Timer4.resume(); diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 0c10d01..f3052d9 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -150,7 +150,11 @@ is several times more FLASH memory available for user programs. ``No DFU capable USB device found`` ----------------------------------- -This probably means you don't have a Maple plugged in or powered on! +This probably means you don't have a Maple plugged in or powered on. +Try unplugging and plugging your Maple or pressing the RESET button. + +This can also happen if you disable the USB peripheral, e.g. using +:ref:`SerialUSB.end() `. I have multiple Maples installed; how do I know which one will get flashed? --------------------------------------------------------------------------- @@ -161,19 +165,26 @@ board. There's no solution to this problem for now: you'll have to just plug in the Maples one at a time. If this is a real problem let us know and we'll see if we can come up with a better solution. +My flash programs don't seem to stick; they behave like they are RAM! +--------------------------------------------------------------------- + +If you have uploaded a program to RAM, this will take priority over +any program subsequently uploaded to flash. We'll be removing this +bug in a later version of the bootloader. For now, you can fix this +by unplugging your Maple to clear the contents of RAM, then plugging +it back in. + +If you are using the :ref:`Unix toolchain `, Make sure +you :command:`make clean` when switching between FLASH and RAM +targets; :command:`make` isn't smart enough to rebuild everything that +needs to be for the new target. + .. _troubleshooting-shell: ===================== Command-line issues ===================== -My flash programs don't seem to stick; they behave like they are RAM! ---------------------------------------------------------------------- - -Make sure you :command:`make clean` when switching between FLASH and -RAM targets; :command:`make` isn't smart enough to rebuild everything -that needs to be for the new target. - [Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` ----------------------------------------------------- diff --git a/source/usart.rst b/source/usart.rst index c0334a9..3beb3fc 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -30,6 +30,5 @@ Recommended Reading * `Arduino reference on Serial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) diff --git a/source/usb.rst b/source/usb.rst index 5494b06..f502f31 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -39,7 +39,6 @@ Recommended Reading * Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents `_ * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) * `Programming Manual `_ (pdf; assembly -- cgit v1.2.3 From 44fe17fa8aec8a4d0684ee7309f8eb503f0ad79e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Dec 2010 19:17:55 -0500 Subject: 0.0.9 release. Made some changes to Servo to get it to compile from within the IDE. Also fixed a lurking broken link in the docs. --- source/_templates/layout.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_templates/layout.html b/source/_templates/layout.html index 98b3d82..bf05832 100644 --- a/source/_templates/layout.html +++ b/source/_templates/layout.html @@ -1,6 +1,6 @@ {% extends "!layout.html" %} {% block rootrellink %}
  • LeafLabs |
    • -
  • Docs Home |
    • +
  • Docs Home |
    • {{ super() }} -{% endblock %} \ No newline at end of file +{% endblock %} -- cgit v1.2.3 From 451f72f34e12b860937b5f40f4118855ef45308f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 21 Dec 2010 03:58:22 -0500 Subject: removed flush() from SerialUSB docs. --- source/lang/api/serialusb.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst index e1d12bf..3bb8c00 100644 --- a/source/lang/api/serialusb.rst +++ b/source/lang/api/serialusb.rst @@ -87,12 +87,6 @@ world!")``. `), the call will block until one becomes available. -.. cpp:function:: USBSerial::flush() - - Removes the contents of the Serial's associated input buffer. That - is, clears any buffered characters, so that the next character read - is guaranteed to be new. - .. cpp:function:: USBSerial::print(unsigned char b) Print the given byte over the USB connection. -- cgit v1.2.3 From 63c03fe6d1aeada3d6c581bacd6c1229b00374b4 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 11 Jan 2011 18:16:05 -0500 Subject: updating copy-to-ide script for more convenient IDE compilation --- flibbit.py | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 flibbit.py diff --git a/flibbit.py b/flibbit.py deleted file mode 100644 index 5f149d4..0000000 --- a/flibbit.py +++ /dev/null @@ -1,26 +0,0 @@ -import os -import shutil -import re -from os.path import * - -src = '/Users/mbolivar/foo/arduino.cc/en/Reference' -dst = '/Users/mbolivar/hack/leaf/libmaple/docs/source/arduino' - -fs = [x for x in os.listdir(src) if x.endswith('.rst')] - -def process(line): - if re.match('-+$', line.rstrip()): - return '=' * (len(line) - 1) + '\n' - elif re.match('\^+$', line.rstrip()): - return '-' * (len(line) - 1) + '\n' - return line - -for f in fs: - print 'processing:', f - with open(join(src,f), 'r') as f_in: - with open(join(dst, basename(f)), 'w') as f_out: - label = '.. _arduino-%s:\n\n' % (f.split('.')[0]) - f_out.write(label) - for line in list(f_in.readlines())[20:-22]: - f_out.write(process(line)) - -- cgit v1.2.3 From 9ea60c7e7dffd06791ec2dc62ffab3f2bf802f08 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 8 Feb 2011 22:19:40 -0500 Subject: Documentation bugfixes --- source/lang/api/attachinterrupt.rst | 31 ++++++++++++++++++++++--------- source/lang/api/detachinterrupt.rst | 16 +++++++++++----- source/lang/api/pwmwrite.rst | 13 ++++++------- source/unix-toolchain.rst | 2 +- 4 files changed, 40 insertions(+), 22 deletions(-) diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst index 0b8907f..7c5a6c7 100644 --- a/source/lang/api/attachinterrupt.rst +++ b/source/lang/api/attachinterrupt.rst @@ -15,7 +15,28 @@ occurs. Library Documentation --------------------- -.. doxygenfunction:: attachInterrupt +.. FIXME once breathe knows how to get the correct attachInterupt +.. (right now it's copying from HardwareTimer), replace with a +.. doxygenfunction directive + +.. cpp:function:: void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode) + + Registers an interrupt handler on a pin. + + The interrupt will be triggered on a given transition on the pin, + as specified by the mode parameter. The handler runs in interrupt + context. The new handler will replace whatever handler is + currently registered for the pin, if any. + + *Parameters* + + - ``pin`` - Maple pin number + + - ``handler`` - Function to run upon external interrupt trigger. + The handler should take no arguments, and have void return type. + + - ``mode`` - Type of transition to trigger on, e.g. falling, + rising, etc. .. doxygenenum:: ExtIntTriggerMode @@ -34,7 +55,6 @@ There are a few constraints you should be aware of if you're using more than one interrupt at a time; the :ref:`external-interrupts` page has the details. - Using Interrupts ---------------- @@ -43,7 +63,6 @@ microcontroller programs, and can help solve timing problems. A good task for using an interrupt might be reading a rotary encoder, or monitoring user input. - If you wanted to insure that a program always caught the pulses from a rotary encoder, never missing a pulse, it would make it very tricky to write a program to do anything else, because the program @@ -55,7 +74,6 @@ sensor that is trying to catch a click, or an infrared slot sensor situations, using an interrupt can free the microcontroller to get some other work done while not missing the doorbell. - Example ------- @@ -78,7 +96,6 @@ Example state = !state; } - Arduino Compatibility --------------------- @@ -89,14 +106,10 @@ additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 number goes with which pin -- just tell ``attachInterrupt()`` the pin you want. - See also -------- - - :ref:`detachInterrupt ` - :ref:`external-interrupts` - - .. include:: cc-attribution.txt diff --git a/source/lang/api/detachinterrupt.rst b/source/lang/api/detachinterrupt.rst index adb2439..41642a7 100644 --- a/source/lang/api/detachinterrupt.rst +++ b/source/lang/api/detachinterrupt.rst @@ -6,11 +6,20 @@ detachInterrupt() Used to disable an interrupt specified with :ref:`lang-attachinterrupt`\ . - Library Documentation --------------------- -.. doxygenfunction:: detachInterrupt +.. FIXME once breathe knows how to get the correct detachInterupt +.. (right now it's copying from HardwareTimer), replace with a +.. doxygenfunction directive + +.. cpp:function:: void detachInterrupt(uint8 pin) + + Disable any registered external interrupt on the given pin. + + *Parameters* + + - ``pin`` Maple pin number Arduino Compatibility --------------------- @@ -31,7 +40,4 @@ See Also - :ref:`attachInterrupt() ` - - - .. include:: cc-attribution.txt diff --git a/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst index 2c858ab..9d50077 100644 --- a/source/lang/api/pwmwrite.rst +++ b/source/lang/api/pwmwrite.rst @@ -33,21 +33,20 @@ Sets the output to the LED proportional to the value read from the potentiometer:: int analogPin = 3; // potentiometer connected to analog pin 3 - int val = 0; // variable to store the read value void setup() { pinMode(BOARD_LED_PIN, OUTPUT); // sets the LED pin as output - pinMode(analogPin, PWM); // sets the potentiometer pin as PWM - // output + pinMode(analogPin, INPUT_ANALOG); // sets the potentiometer pin as + // analog input } void loop() { - val = analogRead(analogPin); // read the input pin + int val = analogRead(analogPin); // read the input pin - analogWrite(BOARD_LED_PIN, val / 16); // analogRead values go from 0 - // to 4095, analogWrite values - // from 0 to 65535 + pwmWrite(BOARD_LED_PIN, val * 16); // analogRead values go from 0 + // to 4095, pwmWrite values + // from 0 to 65535, so scale roughly } See Also diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index e6039a2..b2cabbb 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -90,7 +90,7 @@ package; this could also be installed with `easy_install $ git clone git://github.com/leaflabs/libmaple.git libmaple $ cd libmaple $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz - $ tar xvf arm-*-linux32.tar.gz + $ tar xvf gcc-arm-none-eabi-latest-linux32.tar.gz $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up This step is fairly straightforward: do a git clone of the `libmaple -- cgit v1.2.3 From 9768ee6b2f60442676613c154ad784b30191711c Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 9 Feb 2011 21:10:34 -0500 Subject: Fixed docs bug where we say "long" when we mean "long long" --- source/external-interrupts.rst | 10 +---- source/lang/api/constants.rst | 14 ++++++- source/lang/api/hardwaretimer.rst | 2 + source/lang/api/millis.rst | 2 +- source/lang/api/random.rst | 8 ++-- source/lang/cpp/arithmetic.rst | 2 +- source/lang/cpp/assignment.rst | 28 +++++--------- source/lang/cpp/built-in-types.rst | 2 +- source/lang/cpp/compoundbitwise.rst | 17 ++++----- source/lang/cpp/doublecast.rst | 2 +- source/lang/cpp/enum.rst | 3 +- source/lang/cpp/int.rst | 8 +++- source/lang/cpp/keywords.rst | 13 +++---- source/lang/cpp/long.rst | 52 ------------------------- source/lang/cpp/longcast.rst | 4 +- source/lang/cpp/longlong.rst | 56 +++++++++++++++++++++++++++ source/lang/cpp/return.rst | 2 +- source/lang/cpp/unsignedint.rst | 8 +++- source/lang/cpp/unsignedlong.rst | 41 -------------------- source/lang/cpp/unsignedlonglong.rst | 43 +++++++++++++++++++++ source/lang/cpp/variables.rst | 2 +- source/language.rst | 74 ++++++++++++++++++------------------ 22 files changed, 200 insertions(+), 193 deletions(-) delete mode 100644 source/lang/cpp/long.rst create mode 100644 source/lang/cpp/longlong.rst delete mode 100644 source/lang/cpp/unsignedlong.rst create mode 100644 source/lang/cpp/unsignedlonglong.rst diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index 5187ca4..b2cbbb1 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -84,14 +84,8 @@ The following table shows which pins can be used on which lines. Function Reference ------------------ -.. doxygenfunction:: attachInterrupt - -.. doxygenfunction:: detachInterrupt - -.. doxygenenum:: ExtIntTriggerMode - -.. doxygentypedef:: voidFuncPtr - +- :ref:`attachInterrupt() ` +- :ref:`detachInterrupt() ` Code example ------------ diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst index 4426293..72738b8 100644 --- a/source/lang/api/constants.rst +++ b/source/lang/api/constants.rst @@ -242,10 +242,18 @@ type, follow it with: For example, ``33U`` is an :ref:`unsigned int `. - an ``l`` or ``L`` to interpret the constant as a long value. For - example, ``100000L`` is a :ref:`long `. + example, ``100000L`` is a :ref:`long `. On the Maple, + ``long`` is just a synonym for ``int``. - a ``ul`` or ``UL`` to do both. For example, ``32767UL`` is an - :ref:`unsigned long `. + :ref:`unsigned long `. On the Maple, ``unsigned + long`` is just a synonym for ``unsigned int``. + +- an ``ll`` or ``LL`` to interpret the constant as a :ref:`long long + ` value. + +- a ``ull`` or ``ULL`` to interpret the constant as an :ref:`unsigned + long long `. .. _lang-constants-fp: @@ -321,6 +329,8 @@ See Also - :ref:`unsigned int ` - :ref:`long ` - :ref:`unsigned long ` +- :ref:`long long ` +- :ref:`unsigned long long ` - :ref:`float ` - :ref:`double ` diff --git a/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst index 258471b..3e5424c 100644 --- a/source/lang/api/hardwaretimer.rst +++ b/source/lang/api/hardwaretimer.rst @@ -317,6 +317,8 @@ For example, to set the prescale factor on timer 1 to 5, call The :ref:`setPeriod() ` method may also be used as a convenient alternative. +.. _lang-hardwaretimer-resume: + .. cpp:function:: void HardwareTimer::resume() Resume a paused timer, without affecting its configuration. diff --git a/source/lang/api/millis.rst b/source/lang/api/millis.rst index 54e4507..0288c56 100644 --- a/source/lang/api/millis.rst +++ b/source/lang/api/millis.rst @@ -40,7 +40,7 @@ Tip Since the return value for ``millis()`` is an :ref:`unsigned long `, overflow errors may occur if you try to do math -with other data types, such as :ref:`ints `. +with other data types, such as :ref:`chars `. See Also -------- diff --git a/source/lang/api/random.rst b/source/lang/api/random.rst index f2a9762..dd8871d 100644 --- a/source/lang/api/random.rst +++ b/source/lang/api/random.rst @@ -7,13 +7,13 @@ random() The ``random()`` function generates pseudo-random numbers. -.. TODO keep tracking Sphinx/Breathe's ability to reference overloaded -.. functions so we can use doxygenfunction instead of manually -.. documenting this. - Library Documentation --------------------- +.. FIXME keep tracking Sphinx/Breathe's ability to reference +.. overloaded functions so we can use doxygenfunction instead of +.. manually documenting. + .. cpp:function:: random(long max) Same as a call to ``random(0, max)``. diff --git a/source/lang/cpp/arithmetic.rst b/source/lang/cpp/arithmetic.rst index 91fe22e..7e8c3fc 100644 --- a/source/lang/cpp/arithmetic.rst +++ b/source/lang/cpp/arithmetic.rst @@ -97,7 +97,7 @@ particular, on Maple, ints do not overflow (become negative) until they reach 2,147,483,648; on the Arduino, they overflow at 32,767. Because of this, programs running on Maple are much less likely to run into overflow issues. The following table summarizes the sizes and -ranges of integer datatypes on the Maple (the ranges of long long +ranges of integer datatypes on the Maple (the ranges of ``long long`` types are approximate): .. _lang-arithmetic-int-sizes: diff --git a/source/lang/cpp/assignment.rst b/source/lang/cpp/assignment.rst index b6ad4d5..f9430b4 100644 --- a/source/lang/cpp/assignment.rst +++ b/source/lang/cpp/assignment.rst @@ -15,47 +15,38 @@ operator tells the microcontroller to evaluate whatever value or expression is on the right side of the equal sign, and store it in the variable to the left of the equal sign [#fgross]_. - - Example ------- :: int sensVal; // declare an integer variable named sensVal - senVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal - - + sensVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in sensVal Programming Tips ---------------- -The variable on the left side of the assignment operator ( = sign ) +The variable on the left side of the assignment operator (``=`` sign) needs to be able to hold the value stored in it. If it is not large enough to hold a value, the value stored in the variable will be incorrect. -Don't confuse the assignment operator [ = ] (single equal sign) -with the comparison operator [ == ] (double equal signs), which -evaluates whether two expressions are equal. - +Don't confuse the assignment operator ``=`` (single equal sign) with +the comparison operator ``==`` (double equal signs), which evaluates +whether two expressions are equal. Arduino Compatibility --------------------- Assignments on the Maple are identical to those on Arduino. - - See Also -------- - -- `if (comparison operators) `_ -- `char `_ -- `int `_ -- `long `_ - +- :ref:`if ` +- :ref:`char ` +- :ref:`int ` +- :ref:`long long ` .. rubric:: Footnotes @@ -66,5 +57,4 @@ See Also `_ for more information. - .. include:: cc-attribution.txt diff --git a/source/lang/cpp/built-in-types.rst b/source/lang/cpp/built-in-types.rst index 1323db8..a7349e6 100644 --- a/source/lang/cpp/built-in-types.rst +++ b/source/lang/cpp/built-in-types.rst @@ -33,7 +33,7 @@ Integral types .. cpp:type:: long - 64-bit integer value. + 32-bit integer value. .. cpp:type:: long long diff --git a/source/lang/cpp/compoundbitwise.rst b/source/lang/cpp/compoundbitwise.rst index a4bbb24..8231130 100644 --- a/source/lang/cpp/compoundbitwise.rst +++ b/source/lang/cpp/compoundbitwise.rst @@ -31,8 +31,8 @@ value of ``y``:: x &= y; // equivalent to x = x & y; You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any :ref:`integer value +``int``, ``char``, ``byte``, ``long long``, etc.). You can use either +an integer variable or any :ref:`integer value ` (like ``3`` or ``0x20``) for ``y``. Before doing an example of ``&=``, let's first review the Bitwise AND @@ -115,9 +115,9 @@ its old value bitwise ORed with the value of ``y``:: x |= y; // equivalent to x = x | y; You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an -integer variable or any integer value (like ``3`` or ``0x20``) for -``y``. (This works the same way as :ref:`compound bitwise AND +``int``, ``char``, ``long long`` etc.). You can use either an integer +variable or any integer value (like ``3`` or ``0x20``) for ``y``. +(This works the same way as :ref:`compound bitwise AND `\ , ``&=``). Before doing an example of ``|=``, let's first review the Bitwise OR @@ -178,12 +178,11 @@ will be equal to its old value bitwise XORed with the value of ``y``:: x ^= y; // equivalent to x = x ^ y; You can use any integer variable for ``x`` (i.e., any variable of type -``int``, ``long``, ``char``, ``byte``, etc.). You can use either an +``int``, ``char``, ``long long``, etc.). You can use either an integer variable or any integer value (like ``3`` or ``0x20``) for ``y``. (This works the same way as :ref:`&= -` and :ref:`\|= -`; in fact, these three operators all -work the same in this way). +` and :ref:`\|= `; +in fact, these three operators all work the same in this way). Before doing an example of ``^=``, let's first review the Bitwise XOR operator, ``^``:: diff --git a/source/lang/cpp/doublecast.rst b/source/lang/cpp/doublecast.rst index 511fe24..16a9907 100644 --- a/source/lang/cpp/doublecast.rst +++ b/source/lang/cpp/doublecast.rst @@ -12,7 +12,7 @@ data type. Here is an example:: double d = double(x); // d now holds 2.0, a double value The value ``x`` can be of any type. However, if ``x`` is not a number -(like an ``int`` or ``long``), you will get strange results. +(like an ``int`` or ``long long``), you will get strange results. See the :ref:`double ` reference for details about the precision and limitations of ``double`` values on the Maple. diff --git a/source/lang/cpp/enum.rst b/source/lang/cpp/enum.rst index ba82383..b6409eb 100644 --- a/source/lang/cpp/enum.rst +++ b/source/lang/cpp/enum.rst @@ -18,8 +18,7 @@ which has values ``HOT``, ``COMFY``, and ``COLD``:: enum weather {HOT, COMFY, COLD}; Once you've defined this type, you can create variables of type -``weather``, in the same way you would with an :ref:`int ` -or a :ref:`long `:: +``weather``, in the same way you would with an :ref:`int `:: // create a weather variable named theWeather, with value COMFY: weather theWeather = COMFY; diff --git a/source/lang/cpp/int.rst b/source/lang/cpp/int.rst index ca75f75..3e96b69 100644 --- a/source/lang/cpp/int.rst +++ b/source/lang/cpp/int.rst @@ -24,6 +24,10 @@ arithmetic operations work mostly as you'd expect. There can be an dealing with the :ref:`bitshift right operator (>>) `, however. +.. _lang-long: + +The ``long`` type is a synonym for ``int``. + Here is an example of declaring an ``int`` variable named ``ledPin``, then giving it value 13:: @@ -56,8 +60,8 @@ See Also - :ref:`unsigned int ` - :ref:`char ` - :ref:`unsigned char ` -- :ref:`long ` -- :ref:`unsigned long ` +- :ref:`long long ` +- :ref:`unsigned long long ` - :ref:`Integer Constants ` - :ref:`Variables ` diff --git a/source/lang/cpp/keywords.rst b/source/lang/cpp/keywords.rst index e3bc20d..f21cd0d 100644 --- a/source/lang/cpp/keywords.rst +++ b/source/lang/cpp/keywords.rst @@ -89,11 +89,11 @@ Types The following keywords are used for built-in types. - :ref:`bool ` -- :ref:`lang-char` -- :ref:`lang-double` -- :ref:`lang-float` -- :ref:`lang-int` -- :ref:`lang-long` +- :ref:`char ` +- :ref:`double ` +- :ref:`float ` +- :ref:`int ` +- :ref:`long ` - :ref:`short ` - :ref:`void ` (not really a type, but used in the absence of one) @@ -109,8 +109,7 @@ Qualifiers variables; it has other uses not documented here. - ``unsigned`` is used to specify an unsigned integral type. - Examples: :ref:`lang-unsignedint`, :ref:`lang-unsignedchar`, - :ref:`lang-unsignedlong`. + Examples: :ref:`lang-unsignedint`, :ref:`lang-unsignedchar`. - :ref:`volatile ` is useful when declaring variables that may be modified by external interrupts. diff --git a/source/lang/cpp/long.rst b/source/lang/cpp/long.rst deleted file mode 100644 index d8498c0..0000000 --- a/source/lang/cpp/long.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _lang-long: - -``long`` -======== - -The ``long`` data type stores extended size integer values. You can -use a ``long`` when your values are too large to fit into an :ref:`int -`. A ``long`` occupies 8 bytes of memory. This yields a -range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion -billion, or about 92 million times the number of stars in the Milky -Way galaxy). The exact range of a ``long`` on the Maple is from --9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to -(2^63-1). A ``long`` it is subject to the same :ref:`overflow issues -` as any numeric data type. - -Here's an example of declaring a long (see :ref:`integer constants -` for an explanation of the "L" at the end of the -number):: - - // Speed of light in nanometers per second (approximate). - long c = 299792458000000000L; - -The general syntax for declaring an ``long`` variable named ``var``, -then giving it value ``val``, looks like:: - - long var = val; - -This is identical to the ``int`` syntax, with ``long`` replacing -``int``. - -Note that ``long`` values will still :ref:`overflow -`, just like ``int`` values, but their much -larger range makes this less likely to happen. - -The downside to using a ``long`` instead of an ``int`` (besides the -extra storage) is that :ref:`arithmetic ` operations -on ``long``\ s will take slightly longer than on ``int``\ s. - -See Also --------- - -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`int ` -- :ref:`unsigned int ` -- :ref:`unsigned long ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - -.. include:: cc-attribution.txt diff --git a/source/lang/cpp/longcast.rst b/source/lang/cpp/longcast.rst index 2b92345..f588fc6 100644 --- a/source/lang/cpp/longcast.rst +++ b/source/lang/cpp/longcast.rst @@ -21,7 +21,7 @@ precision and limitations of ``long`` variables on the Maple. See Also -------- -- :ref:`long ` - +- :ref:`long ` +- :ref:`long long ` .. include:: cc-attribution.txt diff --git a/source/lang/cpp/longlong.rst b/source/lang/cpp/longlong.rst new file mode 100644 index 0000000..0ba56ed --- /dev/null +++ b/source/lang/cpp/longlong.rst @@ -0,0 +1,56 @@ +.. highlight:: cpp + +.. _lang-longlong: + +``long long`` +============= + +The ``long long`` data type stores extended size integer values. You +can use a ``long long`` when your values are too large to fit into an +:ref:`int `. A ``long long`` occupies 8 bytes of memory. +This yields a range of approximately -9.2×10^18 to 9.2×10^18 (that's +9.2 billion billion, or about 92 million times the number of stars in +the Milky Way galaxy). The exact range of a ``long long`` on the +Maple is from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, +or -2^63 to (2^63-1). A ``long long`` it is subject to the same +:ref:`overflow issues ` as any numeric data +type. + +A synonym for the ``long long`` type is ``int64``. + +Here's an example of declaring a long long (see :ref:`integer +constants ` for an explanation of the +"LL" at the end of the number):: + + // Speed of light in nanometers per second (approximate). + long long c = 299792458000000000LL; + +The general syntax for declaring an ``long long`` variable named ``var``, +then giving it value ``val``, looks like:: + + long long var = val; + +This is identical to the ``int`` syntax, with ``long long`` (or, at +your option, ``int64``) replacing ``int``. + +Note that ``long long`` values will still :ref:`overflow +`, just like ``int`` values, but their much larger +range makes this less likely to happen. + +The downside to using a ``long long`` instead of an ``int`` (besides +the extra storage) is that :ref:`arithmetic ` +operations on ``long long``\ s will take slightly longer than on +``int``\ s. + +See Also +-------- + +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`int ` +- :ref:`unsigned int ` +- :ref:`unsigned long long ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/return.rst b/source/lang/cpp/return.rst index 7b5039e..b4ef5fd 100644 --- a/source/lang/cpp/return.rst +++ b/source/lang/cpp/return.rst @@ -21,7 +21,7 @@ Syntax: In the second case, ``value`` should have a type which is the same as the return type of the function, or be convertible to it (like an -``int`` to a ``long``, etc.; see :ref:`this note +``int`` to a ``double``, etc.; see :ref:`this note ` for some references). Examples: diff --git a/source/lang/cpp/unsignedint.rst b/source/lang/cpp/unsignedint.rst index f6311da..ad3e2f2 100644 --- a/source/lang/cpp/unsignedint.rst +++ b/source/lang/cpp/unsignedint.rst @@ -31,6 +31,10 @@ that an ``unsigned int`` will "underflow" at 0, and "overflow" at x--; // x now contains 4,294,967,295; rolled over "left to right" x++; // x now contains 0; rolled over "right to left" +.. _lang-unsignedlong: + +The ``unsigned long`` type is a synonym for ``unsigned int``. + Here is an example of declaring an ``unsigned int`` variable named ``ledPin``, then giving it value 13:: @@ -47,8 +51,8 @@ See Also - :ref:`int ` - :ref:`char ` - :ref:`unsigned char ` -- :ref:`long ` -- :ref:`unsigned long ` +- :ref:`long long ` +- :ref:`unsigned long long ` - :ref:`Integer Constants ` - :ref:`Variables ` diff --git a/source/lang/cpp/unsignedlong.rst b/source/lang/cpp/unsignedlong.rst deleted file mode 100644 index 14a4fc3..0000000 --- a/source/lang/cpp/unsignedlong.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. highlight:: cpp - -.. _lang-unsignedlong: - -``unsigned long`` -================= - -An unsigned version of the :ref:`long ` data type. An -``unsigned long`` occupies 8 bytes of memory; it stores an integer -from 0 to 2^64-1, which is approximately 1.8×10^19 (18 quintillion, or -18 billion billion). - -Like an :ref:`unsigned int `, an ``unsigned long`` -won't store negative numbers; it is also subject to the same -:ref:`overflow issues ` as any integral data type. - -Here is an example of declaring an ``unsigned long`` variable named -``c``, then giving it value 299,792,458,000,000,000 (see :ref:`integer -constants ` for an explanation of the "L" -at the end of the number):: - - // Speed of light in nanometers per second (approximate). - unsigned long c = 299792458000000000L; - -The general syntax for declaring an ``unsigned long`` variable named -``var``, then giving it value ``val``, looks like:: - - unsigned long var = val; - -See Also --------- - -- :ref:`long ` -- :ref:`int ` -- :ref:`unsigned ` -- :ref:`char ` -- :ref:`unsigned char ` -- :ref:`Integer Constants ` -- :ref:`Variables ` - -.. include:: cc-attribution.txt diff --git a/source/lang/cpp/unsignedlonglong.rst b/source/lang/cpp/unsignedlonglong.rst new file mode 100644 index 0000000..910b7e4 --- /dev/null +++ b/source/lang/cpp/unsignedlonglong.rst @@ -0,0 +1,43 @@ +.. highlight:: cpp + +.. _lang-unsignedlonglong: + +``unsigned long long`` +====================== + +An unsigned version of the :ref:`long long ` data type. +An ``unsigned long long`` occupies 8 bytes of memory; it stores an +integer from 0 to 2^64-1, which is approximately 1.8×10^19 (18 +quintillion, or 18 billion billion). + +A synonym for the ``unsigned long long`` type is ``uint64``. + +Like an :ref:`unsigned int `, an ``unsigned long +long`` won't store negative numbers; it is also subject to the same +:ref:`overflow issues ` as any integral data type. + +Here is an example of declaring an ``unsigned long long`` variable +named ``c``, then giving it value 299,792,458,000,000,000 (see +:ref:`integer constants ` for an +explanation of the "ULL" at the end of the number):: + + // Speed of light in nanometers per second (approximate). + unsigned long long c = 299792458000000000ULL; + +The general syntax for declaring an ``unsigned long long`` variable named +``var``, then giving it value ``val``, looks like:: + + unsigned long long var = val; + +See Also +-------- + +- :ref:`long long ` +- :ref:`int ` +- :ref:`unsigned ` +- :ref:`char ` +- :ref:`unsigned char ` +- :ref:`Integer Constants ` +- :ref:`Variables ` + +.. include:: cc-attribution.txt diff --git a/source/lang/cpp/variables.rst b/source/lang/cpp/variables.rst index e6da0c9..336d5ab 100644 --- a/source/lang/cpp/variables.rst +++ b/source/lang/cpp/variables.rst @@ -44,7 +44,7 @@ Here are a few examples of declaring variables of different types:: int lightSensVal; char currentLetter; - unsigned long speedOfLight = 186000UL; + unsigned long long speedOfLight = 186000ULL; char errorMessage = {"choose another option"}; // see string Naming Variables diff --git a/source/language.rst b/source/language.rst index 018eb8c..2ebe03c 100644 --- a/source/language.rst +++ b/source/language.rst @@ -102,59 +102,59 @@ A more exhaustive index is available at the :ref:`language-index`. | |* :ref:`unsigned int ` | | |* :ref:`#include ` | (4 bytes) |* :ref:`micros() ` | | | | | -| |* :ref:`long ` (8 bytes) |* :ref:`delay() ` | -|**Arithmetic Operators** | | | -| |* :ref:`unsigned long ` |* :ref:`delayMicroseconds() | -|* :ref:`= ` | (8 bytes) | ` | -| (assignment operator) | | | -| |* :ref:`float ` (4 bytes) | | -|* :ref:`+ ` (addition) | |**Math** | -| |* :ref:`double ` (8 bytes) | | -|* :ref:`- ` | |* :ref:`min() ` | -| (subtraction) |* :ref:`Strings ` | | +| |* ``long`` (4 bytes), synonym for :ref:`int |* :ref:`delay() ` | +|**Arithmetic Operators** | ` | | +| | |* :ref:`delayMicroseconds() | +|* :ref:`= ` |* ``unsigned long`` (4 bytes), synonym for | ` | +| (assignment operator) | :ref:`unsigned int ` | | +| | | | +|* :ref:`+ ` (addition) |* :ref:`long long ` (8 bytes) |**Math** | +| | | | +|* :ref:`- ` |* :ref:`unsigned long |* :ref:`min() ` | +| (subtraction) | long ` (8 bytes) | | | | |* :ref:`max() ` | -|* :ref:`* ` |* :ref:`Arrays ` | | +|* :ref:`* ` |* :ref:`float ` (4 bytes) | | | (multiplication) | |* :ref:`abs() ` | -| |* :ref:`enum ` | | +| |* :ref:`double ` (8 bytes) | | |* :ref:`/ ` (division) | |* :ref:`constrain() ` | -| |* :ref:`Numeric types ` | | +| |* :ref:`strings ` | | |* :ref:`% ` (modulo) | |* :ref:`map() ` | -| |**Conversion** | | +| |* :ref:`arrays ` | | | | |* :ref:`pow() ` | -|**Comparison Operators** |* :ref:`char() ` | | +|**Comparison Operators** |* :ref:`enum ` | | | | |* :ref:`sqrt() ` | -|* :ref:`== ` (equal to) |* :ref:`byte() ` | | +|* :ref:`== ` (equal to) |* :ref:`numeric types ` | | | | | | -|* :ref:`\!= ` |* :ref:`int() ` |**Trigonometry** | +|* :ref:`\!= ` |**Conversion** |**Trigonometry** | | (not equal to) | | | -| |* :ref:`long() ` |* :ref:`sin() ` | +| |* :ref:`char() ` |* :ref:`sin() ` | |* :ref:`< ` (less than) | | | -| |* :ref:`float() ` |* :ref:`cos() ` | +| |* :ref:`byte() ` |* :ref:`cos() ` | |* :ref:`> ` | | | -| (greater than) |* :ref:`double() ` |* :ref:`tan() ` | +| (greater than) |* :ref:`int() ` |* :ref:`tan() ` | | | | | -|* :ref:`<= ` | | | -| (less than or equal to) |**Variable Scope & Qualifiers** |**Random Numbers** | -| | | | -|* :ref:`>= ` |* :ref:`variables `, |* :ref:`randomSeed() ` | -| (greater than or equal to) | :ref:`scope ` | | +|* :ref:`<= ` |* :ref:`long() ` | | +| (less than or equal to) | |**Random Numbers** | +| |* :ref:`float() ` | | +|* :ref:`>= ` | |* :ref:`randomSeed() ` | +| (greater than or equal to) |* :ref:`double() ` | | | | |* :ref:`random() ` | -| |* :ref:`static ` | | -|**Boolean Operators** | | | -| |* :ref:`volatile ` |**Bits and Bytes** | -|* :ref:`&& ` (and) | | | -| |* :ref:`const ` |* :ref:`lowByte() ` | -|* :ref:`|| ` (or) | | | -| | |* :ref:`highByte() ` is | -|* :ref:`\! ` (not) |**Utilities** | provided, though its use is discouraged. | | | | | -| |* :ref:`sizeof() ` |* :ref:`bitRead() ` | -|**Pointer Operators** | | | +|**Boolean Operators** |**Variable Scope & Qualifiers** | | +| | |**Bits and Bytes** | +|* :ref:`&& ` (and) |* :ref:`variables `, | | +| | :ref:`scope ` |* :ref:`lowByte() ` | +|* :ref:`|| ` (or) | | | +| |* :ref:`static ` |* :ref:`highByte() ` is | +|* :ref:`\! ` (not) | | provided, though its use is discouraged. | +| |* :ref:`volatile ` | | +| | |* :ref:`bitRead() ` | +|**Pointer Operators** |* :ref:`const ` | | | | |* :ref:`bitWrite() ` | |* :ref:`* dereference operator | | | -| ` | |* :ref:`bitSet() ` | +| ` |**Utilities** |* :ref:`bitSet() ` | | | | | -|* :ref:`& reference operator | |* :ref:`bitClear() ` | +|* :ref:`& reference operator |* :ref:`sizeof() ` |* :ref:`bitClear() ` | | ` | | | | | |* :ref:`bit() ` | | | | | -- cgit v1.2.3 From 19d43c57bd130b67aa67249a5c7b3eb596d341e9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 11 Feb 2011 22:03:07 -0500 Subject: [wip] docs fixes; beginning to generalize for multiple devices --- source/hardware/maple-mini.rst | 6 +++ source/hardware/maple-native.rst | 6 +++ source/hardware/maple.rst | 7 +++ source/index.rst | 22 ++++++--- source/libmaple.rst | 5 +- source/unix-toolchain.rst | 103 ++++++--------------------------------- 6 files changed, 52 insertions(+), 97 deletions(-) create mode 100644 source/hardware/maple-mini.rst create mode 100644 source/hardware/maple-native.rst create mode 100644 source/hardware/maple.rst diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst new file mode 100644 index 0000000..a8a4186 --- /dev/null +++ b/source/hardware/maple-mini.rst @@ -0,0 +1,6 @@ +.. _hardware-maple-mini: + +Maple Mini +========== + +Stub. diff --git a/source/hardware/maple-native.rst b/source/hardware/maple-native.rst new file mode 100644 index 0000000..79115fc --- /dev/null +++ b/source/hardware/maple-native.rst @@ -0,0 +1,6 @@ +.. _hardware-maple-native: + +Maple Native +============ + +Stub. diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst new file mode 100644 index 0000000..aabf39f --- /dev/null +++ b/source/hardware/maple.rst @@ -0,0 +1,7 @@ +.. _hardware-maple: + +Maple +===== + +Stub. TODO picture, describe what things do, serial bootloader +uploading, etc. etc. diff --git a/source/index.rst b/source/index.rst index 825ec81..25bda65 100644 --- a/source/index.rst +++ b/source/index.rst @@ -16,27 +16,26 @@ Have fun! **Usage Guides:** .. toctree:: - :maxdepth: 2 + :maxdepth: 1 Quickstart IDE Installation IDE Anatomy + Command-Line Toolchain .. _index-maple-programming: **Maple Programming:** .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - Maple Language + Maple Language Maple Libraries Arduino Compatibility External Interrupts - Command-Line Tools & APIs Bootloader - - + libmaple Troubleshooting Known Problems @@ -57,6 +56,17 @@ Have fun! usart timers +.. _index-schematics: + +**Board Hardware Documentation:** + +.. toctree:: + :maxdepth: 1 + + hardware/maple.rst + hardware/maple-mini.rst + hardware/maple-native.rst + .. _index-reference: **Reference:** diff --git a/source/libmaple.rst b/source/libmaple.rst index b76c7c8..8cc39a3 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -2,8 +2,8 @@ .. _libmaple: -``libmaple`` Reference -====================== +``libmaple`` +============ .. image:: /_static/img/libmaple-screenshot-small.png :align: center @@ -35,7 +35,6 @@ wrappers and code to imitate the Arduino programming library. .. toctree:: :maxdepth: 2 - Unix Toolchain Quickstart Guide to using GCC's ARM target .. TODO LATER create, style, and host a pure Doxygen libmaple diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index b2cabbb..8e766bd 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -55,7 +55,7 @@ First I'll give the commands to run, then explain:: You'll want to install a bunch of developer "basics" like :command:`make`, :command:`tar`, etc. A good catch-all for these -tools is the "build-essential" meta-package on most debian platforms: +tools is the "build-essential" meta-package on most Debian platforms: installing this fake package will pull in dozens of useful tools without bogging your system down too much. ``git-core`` is the name of the git package; `Git `_ is a distributed code @@ -104,6 +104,9 @@ where you put the toolchain, make sure to preserve its internal directory layout, as the binaries make relative path calls and references. +After you're done, you'll probably want to update your shell startup +script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. + .. _toolchain-udev: **3. Install udev Rules** @@ -136,15 +139,11 @@ stated previously, this document assumes a general level of Unix aptitude on the part of the reader; if you're uncomfortable using Terminal (or if you don't know what that means), then you should probably stick with using the `Maple IDE -`_ to develop programs. Some of -these software packages might be available on `MacPorts -`_. The author had some bad experiences with -MacPorts a few years ago, though, and hasn't touched it since. Of -course, your mileage may vary. +`_ to develop programs. **1. Collect and Install Tools** -You will need the following tools to get started: +You will need the following tools\ [#fmacports]_ to get started: 1. `XCode `_: If you're reading this, you've probably already got this. Provides @@ -349,6 +348,8 @@ able to fix it with :: Starting your own projects -------------------------- +.. TODO fix the build-targets.mk mess, note the "library" target + So everything worked, and you want to start your own project? Great! It's easy. Just set the environment variable ``LIB_MAPLE_HOME`` in your shell startup script to point to the libmaple repository you @@ -402,87 +403,6 @@ TODO. For now see `this great guide `_ from fun-tech.se, and the ``jtag`` Makefile target. -.. _toolchain-codeblocks: - -Do it all with Code::Blocks ---------------------------- - -.. TODO this really should reflect the new, more pleasant build system - -Optional. `Code::Blocks `_ is a generic -cross platform IDE. We don't personally use it for development, so we -haven't worked out all the kinks (e.g., debugging isn't integrated), -but it might be helpful for people who are allergic to `vim -`_ and/or `Emacs -`_. The simple configuration -described here just calls down to the :file:`Makefile`, so follow the -above directions to get the command line tools configured (you'll -definitely need the arm-none-eabi-* tools on your ``PATH``), then -`install Code::Blocks `_. You -can do this on Linux with:: - - $ sudo aptitude install codeblocks - -The first time it runs you'll maybe want to disable all the glitzy -"Getting Started" crap (when will they learn?). We've added a .cbp -"projects" file to the libmaple repository: you can try using that one -by copying it from :file:`support/codeblocks/libmaple.cbp` to the top -level directory, but no promises (it might be missing new source files -etc). It's probably worth reading through these instructions as well -to get a feel for how it all works. - -To create your own "libmaple" project, start with an "Empty Project" -with the "Folder to create project in" set to your -``LIB_MAPLE_HOME``. Make sure that the "Resulting filename" is in the -top level directory as well. - -.. image:: /_static/img/codeblocks_newproject.png - :align: center - :alt: Code::Blocks new project wizard - -Select the "GNU GCC Compiler" (it won't be used, anyway) and disable -the "Debug" configuration in the next window. Now you should have a -project with no files; add files by right clicking on the project in -the left panel file hierarchy and "Add files recursively". Import both -the :file:`wirish` and :file:`libmaple` directories recursively, then -add :file:`main.cpp` separately. - -.. image:: /_static/img/codeblocks_makefile.png - :align: center - :alt: Code::Blocks targets options - -Next we have to configure the Makefile targets. Go to the -"Properties..." menu under "Project" and check the "This is a custom -Makefile" box. Then go to the "Build targets" tab and create "ram" and -"flash" targets, both of type "Console application" and without the -Auto-generated filename prefixes or extensions. Set the Output -filename to :file:`support/codeblocks/program_flash.sh` and -:file:`support/codeblocks/program_ram.sh` respectively; these scripts -just call the program_ram/program_flash make targets and are a hack to -get the "run" button to upload code to the Maple. The IDE will warn -that these files will be overwritten, but they won't be. For both the -"flash" and "ram" targets, click the "Build options..." button (below -"Virtual targets..." etc) and go to the far right tab ("'Make' -commands"). Edit the Clean project/target line so it's just "clean" -(not "clean$target"), and set the "Build project/target" and "Compile -single file" commands to ``$make -f $makefile MAPLE_TARGET=$target`` -and ``$make -f $makefile MAPLE_TARGET=$target $file``, respectively. - -.. image:: /_static/img/codeblocks_maketargets.png - :align: center - :alt: Code::Blocks make targets - -Save all these changes, go back to the main IDE window, and try to -build/run. "Build" will compile everything, "Run" will run the upload -script in a terminal window (if there are problems they will flash by -very quickly; you can start Code::Blocks in a terminal window and -check the output in that base window if necessary), and "Rebuild" will -clean before rebuilding. - -.. image:: /_static/img/codeblocks_build.png - :align: center - :alt: Success! - .. _toolchain-exuberantly: Go forth exuberantly! @@ -491,3 +411,10 @@ Go forth exuberantly! Let us know what you come up with! Use #leaflabs on Twitter, post in the `forum`_, track us down in the real world, whatever. We love projects! + +.. rubric:: Footnotes + +.. [#fmacports] Some of these software packages might be available on + `MacPorts `_. The author had some bad + experiences with MacPorts a few years ago, though, and hasn't + touched it since. Of course, your mileage may vary. -- cgit v1.2.3 From e6317f828d346adafad4f03e9f7cf74b1e9acfa8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 12 Feb 2011 02:46:42 -0500 Subject: Reorganized docs index for more readability, added information about Maple hardware and design files. Other tweaks and improvements. --- source/_templates/layout.html | 3 +- source/errata.rst | 30 ++++--------- source/hardware/maple.rst | 101 +++++++++++++++++++++++++++++++++++++++++- source/index.rst | 24 ++++++---- source/maple-ide-install.rst | 7 +++ source/maple-quickstart.rst | 2 +- source/unix-toolchain.rst | 29 ++++++------ 7 files changed, 147 insertions(+), 49 deletions(-) diff --git a/source/_templates/layout.html b/source/_templates/layout.html index bf05832..93547f0 100644 --- a/source/_templates/layout.html +++ b/source/_templates/layout.html @@ -1,6 +1,5 @@ {% extends "!layout.html" %} {% block rootrellink %} -
  • LeafLabs |
    • -
  • Docs Home |
    • +
  • LeafLabs |
    • {{ super() }} {% endblock %} diff --git a/source/errata.rst b/source/errata.rst index a3bb66a..8feb6ea 100644 --- a/source/errata.rst +++ b/source/errata.rst @@ -10,22 +10,22 @@ but are easy ways to break or damage your board permanently. For a list of differences between the Maple and Arduinos, see the :ref:`compatibility reference `. +The errata are grouped by Maple version ("Rev"). Rev 5 is currently +on sale. If you are unsure which version you own, the :ref:`Maple +hardware page ` has pictures and +descriptions of each version. + .. contents:: Contents :local: Maple Rev 5 ----------- -These boards went on sale in November 2010. They have white buttons, -and "r5" in small print near the "LeafLabs Maple" text next to the -"infinity-leaf" logo, among other changes: - -.. figure:: /_static/img/maple_rev5.png - :align: center - :alt: Maple Rev 5 - Known issues: +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the + corresponding "AIN" is missing from its silkscreen. + * **GPIO 39-43 not configured**: this is really more of a software "TODO" item. Some of the JTAG header pins are numbered 39-43. These STM32 pins are indeed fully functional :ref:`GPIO ` when the a @@ -43,13 +43,6 @@ Potential failure modes: Maple Rev 3 ----------- -This batch of boards went on sale beginning in May 2010. They have a -darker red silkscreen and the "infinity-leaf" logo: - -.. figure:: /_static/img/maple_rev3.png - :align: center - :alt: Maple Rev 3 - Known issues: * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 @@ -106,13 +99,6 @@ Potential failure modes: Maple Rev 1 ----------- -This batch of 100 boards shipped in later 2009. They have a red -silkscreen and the logo is a single pixelated leaf: - -.. figure:: /_static/img/maple_rev1.png - :align: center - :alt: Maple Rev 1 - Known issues: * **ADC noise**: generally very high, in particular when the USB port diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index aabf39f..8350cc5 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -1,7 +1,104 @@ +.. highlight:: sh + .. _hardware-maple: Maple ===== -Stub. TODO picture, describe what things do, serial bootloader -uploading, etc. etc. +.. contents:: Contents + :local: + +.. _maple-hardware-identify-rev: + +Identifying your Rev +-------------------- + +We went through three versions ("Revs") of the Maple hardware: Rev 1, +Rev 3, and Rev 5 [#frev2_4]_; Rev 5, the final design, is currently on +sale. The following sections will help you to help you identify your +Rev. Known issues are listed in the :ref:`errata `. + +Rev 1 +^^^^^ + +A small number of Maple Rev 1 boards went on sale in late 2009. They +have a light red silkscreen and a single pixelated leaf as a logo. + +.. figure:: /_static/img/maple_rev1.png + :align: center + :alt: Maple Rev 1 + +.. rubric:: Footnotes + +.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal + testing. + +Rev 3 +^^^^^ + +This batch of boards went on sale beginning in May 2010. They have a +darker red silkscreen and the "infinity leaf" logo. The Maple Rev 3 +was the first version which includes the built-in button, labeled BUT. +It also includes a built-in LiPo battery charger. + +.. figure:: /_static/img/maple_rev3.png + :align: center + :alt: Maple Rev 3 + +Rev 5 +^^^^^ + +These boards went on sale in November 2010. They have white buttons, +and "r5" in small print near the "LeafLabs Maple" text next to the +"infinity leaf" logo. The Maple Rev 5 repositioned the double header +on the right hand side to better fit 0.1 inch pitch breadboard. This +necessitated the removal of pins 21 and 22 from the double header; +they are still available, but don't have any headers installed on +them. + +.. figure:: /_static/img/maple_rev5.png + :align: center + :alt: Maple Rev 5 + +Powering the Maple +------------------ + +The Maple's power source is determined by the header to the left of +the "LeafLabs" label on the silkscreen. All versions of the Maple can +be powered from the barrel jack connector, USB, or a LiPo battery. We +ship the Maple with a jumper on the USB selector. In order to power +it off of an alternative source, unplug the Maple, then move the +jumper to the desired selector before reconnecting power. + +You can also power the Maple via the pin labeled "Vin" on the lower +header. However, don't do this while simultaneously powering the +Maple from another source, or you could damage the board. + +Using the Built-in Battery Charger +---------------------------------- + +Maples Rev 3 and Rev 5 also have a built-in LiPo battery charger. In +order to use it, put a jumper across the CHRG header on the power +selection header and across the USB, or EXT selectors, depending on +whether you're charging the battery via USB cable or barrel jack +connector. The LED labeled CHRG will light up while the battery is +being charged. When the battery is finished charging, the LED labeled +DONE will also light up. + +Hardware Design Files +--------------------- + +The hardware schematics and board layout files are available in the +`Maple github repository `_. The +design files for Rev 1, Rev 3, and Rev 5 are respectively in the +``maple-r1``, ``maple-r3``, and ``maple-r5`` subdirectories. A +schematic for a JTAG adapter suitable for use with Maple is available +in the ``jtagadapter`` directory. + +From the github repository main page, you can download the entire +repository by clicking the "Download" button. If you are familiar +with `git `_, you can also clone the repository +at the command line with :: + + $ git clone git://github.com/leaflabs/maple.git + diff --git a/source/index.rst b/source/index.rst index 25bda65..5c1718f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -20,7 +20,7 @@ Have fun! Quickstart IDE Installation - IDE Anatomy + IDE Usage Command-Line Toolchain .. _index-maple-programming: @@ -30,12 +30,12 @@ Have fun! .. toctree:: :maxdepth: 1 - Maple Language - Maple Libraries + Language + Libraries Arduino Compatibility + libmaple External Interrupts Bootloader - libmaple Troubleshooting Known Problems @@ -46,15 +46,15 @@ Have fun! .. toctree:: :maxdepth: 1 - i2c - pwm + adc gpio - usb + i2c jtag - adc + pwm spi - usart timers + usb + usart .. _index-schematics: @@ -64,6 +64,12 @@ Have fun! :maxdepth: 1 hardware/maple.rst + +.. TODO write/include these upon Mini and Native release + +.. toctree:: + :hidden: + hardware/maple-mini.rst hardware/maple-native.rst diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index ce50c49..92d1a96 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -61,6 +61,13 @@ First, extract all the files in the ZIP file to a suitable location on your system (like your Desktop folder). Next, you have to install some drivers. Sorry! +.. note:: Note that while these instructions work on Windows XP, + changes in Windows 7 mean that you won't be able to install the IDE + without disabling driver signing on your computer. We're working + on resolving this situation. For now, `users on the forum have + reported some workarounds + `_. + First, install DFU drivers (for uploading code to your Maple) using the following steps. diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index ca902f3..08fa5c1 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -6,7 +6,7 @@ Maple Quickstart Guide ======================== -You'll need a `Maple board `_, a `mini-b +You'll need a `Maple board `_, a `Mini-B USB cable `_, a functional computer, and possibly root (or "administrator") access to that computer. diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 8e766bd..836f777 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -8,7 +8,7 @@ This is a tutorial for using the Maple with a standard Unix toolchain. It's not necessary to do this in order to program the Maple; you can -always use our `IDE `_ instead. +always :ref:`install the Maple IDE ` instead. You'll need a Maple board, a mini-b USB cable, a functional computer, and root access to that computer. This guide assumes you've had @@ -16,10 +16,10 @@ success with the IDE on your machine and that you are fairly comfortable with the Unix command line; some previous experience with editing your shell startup script (.bashrc, .tcshrc, etc.) and using `make `_ is recommended. For -generic installation/setup issues, the `IDE install -`_ and -:ref:`troubleshooting` pages may be helpful. If all else fails, try -our `forum`_, or `contact us directly`_\ ! +generic installation/setup issues, the :ref:`IDE installation +` and :ref:`troubleshooting` pages may be +helpful. If all else fails, try our `forum`_, or `contact us +directly`_\ ! We currently have instructions for 32- and 64-bit Linux and OS X Snow Leopard. If you're on another Unix platform, Windows, or an earlier @@ -28,7 +28,7 @@ directions on your own. As a jumping off point, you might want to begin with these `stripped down distributions `_ of the `CodeSourcery GCC compiler tools `_ -(including win32 versions). If you do have success on other platforms, +(including Win32 versions). If you do have success on other platforms, please post in the forums, so we can fold your tips into this document! @@ -325,7 +325,7 @@ something like :file:`/dev/ttyACMXXX` on Linux or :file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly different name on your system. To open up a session, run :: - $ screen /dev/tty-whatever-it-is + $ screen /dev/ttyXXX If the interactive test program built and uploaded correctly, you should be able to connect without any errors reported by @@ -334,14 +334,17 @@ there are a number of commands which demonstrate Maple peripheral features. As of October 2010, the HardwareSerial library is blocking, so using any commands which would write to the USART Serial ports will cause the program to hang. To exit the screen session, type :kbd:`C-a -C-\\` (control-a, followed by control-backslash), and type ``y`` when -prompted if you're sure. +C-\\` (control-a, followed by control-backslash) on Mac, or :kbd:`C-a +k` (control-a k) on Linux, and type ``y`` when prompted if you're +sure. -Using :command:`screen` in this way sometimes messes up your session. -If your shell starts acting up after you exit screen, you should be -able to fix it with :: +.. note:: - $ reset && clear + Using :command:`screen` in this way sometimes messes up your + terminal session on OS X. If your shell starts acting up after you + exit screen, you should be able to fix it with :: + + $ reset && clear .. _toolchain-projects: -- cgit v1.2.3 From c4177d18f5a433fcac11f8ce96a91bdb5a4207e7 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 16 Feb 2011 05:45:40 -0500 Subject: docs fixes --- source/compatibility.rst | 48 +++++++++++++------------- source/errata.rst | 10 +++--- source/gpio.rst | 17 +++++++--- source/hardware/maple.rst | 12 ++++--- source/index.rst | 8 ++--- source/jtag.rst | 3 ++ source/lang/api/hardwarespi.rst | 28 ++++++++++----- source/lang/api/hardwaretimer.rst | 3 ++ source/maple-quickstart.rst | 71 +++++++++++++++++++++------------------ source/troubleshooting.rst | 8 ++--- source/unix-toolchain.rst | 9 ++--- 11 files changed, 126 insertions(+), 91 deletions(-) diff --git a/source/compatibility.rst b/source/compatibility.rst index 848a3d3..0d6319f 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -13,17 +13,17 @@ Overview -------- The biggest difference between the Maple and most Arduino boards is -that the Maple uses a 32-bit ARM Cortex-M3 architecture chip while the -Arduinos have 8-bit Atmel AVR chips. The different instruction set -means that machine code (executable binary programs) is incompatible -between the two, and a different compiler (actually just a different -version of `gcc `_) is required. - -The compiler for the regular Arduino IDE is the popular -:command:`avr-gcc` package; the compiler for the Maple version of the -IDE is CodeSourcery's edition of gcc for the ARM EABI target -(:command:`arm-non-eabi-gcc`). A (preliminary) reference on -:ref:`using arm-none-eabi-gcc ` is available. +that the Maple uses a 32-bit ARM Cortex-M3 architecture chip, while +the Arduinos have 8-bit Atmel AVR chips. The different instruction set +means that machine code (which makes up executable binary program) is +incompatible between the two, and a different compiler (actually just +a different version of `gcc `_) is required. + +The compiler for the regular Arduino IDE is the popular `avr-gcc +`_ package; the compiler for the +Maple version of the IDE is CodeSourcery's edition of gcc for the ARM +EABI target (:command:`arm-non-eabi-gcc`). A (preliminary) reference +on :ref:`using arm-none-eabi-gcc ` is available. The bitwidth of the processor means that the Maple can process 32-bit operations (like adding two 32-bit integers) in a single instruction, @@ -31,12 +31,12 @@ while an Arduino processor would have to split up large operations into several smaller ones. In a lot of cases 8-bit operations are plenty (integers 0-255, single characters of text, etc.), but if you're dealing with higher resolution data, the speed up could be -significant. A trade-off is that code could be larger as well; program -instructions and memory locations can be up to 32-bits each, which in -the worst case would quadruple program size. In reality, the removal -of extra instructions and fancy packing together of simple -instructions means that programs aren't much larger (or are even -smaller). +significant. + +A trade-off is that code could be larger as well; program instructions +and memory locations can be up to 32 bits each. However, removal of +extra instructions and fancy packing together of simple instructions +means that programs aren't much larger (or are even smaller). Header Numbering and Incompatibilities -------------------------------------- @@ -63,9 +63,9 @@ The incompatible hardware differences are: peripheral internally using low level configuration, but we haven't looked in to it. -* **No External Voltage Reference**: The Arduino has an Aref pin which +* **No External Voltage Reference**: The Arduino has an AREF pin which allows the use of an external ADC voltage reference; the Maple has - an extra GPIO pin (14) with PWM capability in this spot, and does + an extra GPIO pin (D14) with PWM capability in this spot, and does not allow an external voltage reference to be configured. * **EEPROM**: the Maple does not have any internal EEPROM. This @@ -93,11 +93,13 @@ differences, most of which are improvements: * :ref:`pinMode() ` **types**: any :ref:`GPIO ` (including analog pins) can be configured into one of the following - modes with a single call to ```pinMode()``: ``OUTPUT``, + modes with a single call to ``pinMode()``: ``OUTPUT``, ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``, - ``INPUT_PULLDOWN``. Additionally, the PWM and Analog Input pins can - be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the - :ref:`GPIO documentation ` for more information. + ``INPUT_PULLDOWN``. Additionally, the PWM pins (labeled "PWM" on the + Maple's silkscreen) can be configured in ``PWM`` and + ``PWM_OPEN_DRAIN`` modes, and the analog input pins (labeled "AIN") + can be configured in ``INPUT_ANALOG`` mode. See the :ref:`GPIO + documentation ` for more information. * :ref:`Serial port ` **syntax**: like the `Arduino Mega `_, the Maple has diff --git a/source/errata.rst b/source/errata.rst index 8feb6ea..657abd9 100644 --- a/source/errata.rst +++ b/source/errata.rst @@ -24,20 +24,20 @@ Maple Rev 5 Known issues: * **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the - corresponding "AIN" is missing from its silkscreen. + corresponding "AIN" is missing from its silkscreen. * **GPIO 39-43 not configured**: this is really more of a software "TODO" item. Some of the JTAG header pins are numbered 39-43. These - STM32 pins are indeed fully functional :ref:`GPIO ` when the a + STM32 pins are indeed fully functional :ref:`GPIO ` when a :ref:`JTAG ` device is not connected, but we have not enabled them in software and thus they can not be accessed with the regular :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. Potential failure modes: -* **TTL voltage on non-tolerant pins**: not all header pins are 5V - compatible; connecting certain serial devices in the wrong way could - over voltage the pins. The :ref:`Pin-Mapping Mega Table +* **High voltage on non-tolerant pins**: not all header pins are 5V + compatible; so e.g. connecting certain serial devices in the wrong + way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table ` details which pins are 5V-tolerant. Maple Rev 3 diff --git a/source/gpio.rst b/source/gpio.rst index 4017862..cebb402 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -11,7 +11,7 @@ silkscreen. Many of these pins may additionally be used for special features or peripheral functions. This page documents those capabilities, by pin. -The current and voltage limitations have not been copied over from the +The current and voltage limitations have been copied over from the STM32 datasheet (see the :ref:`Recommended Reading ` for a link). In particular, a number of GPIO pins are 5V tolerant (which means that applying 5 volts to a pin @@ -31,6 +31,9 @@ peripheral type. The "STM32" column refers to the port and number that the header is connected to on the microcontroller. The "5V?" column documents whether or not the pin is 5 volt tolerant (see above). +.. TODO silkscreen pictures which let you know what each abbreviation +.. means, with links to the relevant documentation. + .. csv-table:: :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" @@ -83,13 +86,17 @@ GPIO Modes Function Reference ------------------ -.. doxygenfunction:: pinMode +- :ref:`pinMode() ` + +- :ref:`digitalRead() ` -.. doxygenfunction:: digitalRead +- :ref:`digitalWrite() ` -.. doxygenfunction:: digitalWrite +- :ref:`analogRead() ` -.. doxygenfunction:: analogRead +- :ref:`pwmWrite() ` (Maple's equivalent to + ``analogWrite()``; see the :ref:`analogWrite() reference + ` for differences from the Arduino version). .. _gpio-recommended-reading: diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 8350cc5..874ee82 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -28,11 +28,6 @@ have a light red silkscreen and a single pixelated leaf as a logo. :align: center :alt: Maple Rev 1 -.. rubric:: Footnotes - -.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal - testing. - Rev 3 ^^^^^ @@ -60,6 +55,8 @@ them. :align: center :alt: Maple Rev 5 +.. _hardware-maple-powering: + Powering the Maple ------------------ @@ -102,3 +99,8 @@ at the command line with :: $ git clone git://github.com/leaflabs/maple.git +.. rubric:: Footnotes + +.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal + testing. + diff --git a/source/index.rst b/source/index.rst index 5c1718f..4369fbd 100644 --- a/source/index.rst +++ b/source/index.rst @@ -67,11 +67,11 @@ Have fun! .. TODO write/include these upon Mini and Native release -.. toctree:: - :hidden: +.. .. toctree:: +.. :hidden: - hardware/maple-mini.rst - hardware/maple-native.rst +.. hardware/maple-mini.rst +.. hardware/maple-native.rst .. _index-reference: diff --git a/source/jtag.rst b/source/jtag.rst index e3c8111..858021e 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -4,6 +4,9 @@ JTAG ====== +.. TODO update adapter schematic, add information on using it with our +.. devices. + JTAG is an interface for low-level debugging of digital devices. It gives instruction by instruction control over the microprocessor and allows data to be read and written to arbitrary memory and register diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst index c71b2c3..53a225d 100644 --- a/source/lang/api/hardwarespi.rst +++ b/source/lang/api/hardwarespi.rst @@ -39,17 +39,29 @@ pins for other purposes. Library Documentation --------------------- +Using the SPI Class +^^^^^^^^^^^^^^^^^^^ + +You can declare that you want to use SPI in your sketch by putting +``HardwareSPI Spi(number);`` with your variables, where ``number`` is +1 or 2, depending on which SPI you want to use. Then you can use the +functions described in the next section. For example:: + + // Use SPI 1 + HardwareSpi Spi(1); + + void setup() { + Spi.begin(SPI_18MHZ); + } + + void loop() { + // Get the next byte from the peripheral + uint8 byte = Spi.recv(); + } + HardwareSPI Class Reference ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can use the SPI interface by including a declaration ``HardwareSPI -Spi(number);`` at the start of the sketch or program. The ``number`` -must be either 1 or 2 and specifies which port to use. Once this is -done, you can call any of the methods documented here using -``Spi.method(arguments)``; for example, ``Spi.send(0x13)`` would send -the value ``0x13`` into the port buffer to be transmitted as soon as -possible. - .. cpp:class:: HardwareSPI Class for interacting with SPI. diff --git a/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst index 3e5424c..c7a630d 100644 --- a/source/lang/api/hardwaretimer.rst +++ b/source/lang/api/hardwaretimer.rst @@ -21,6 +21,9 @@ documented below on one of the predefined ``HardwareTimer`` instances. For example, to set the prescale factor on timer 1 to 5, call ``Timer1.setPrescaleFactor(5)``. +.. TODO add code examples that people can copy and paste in case +.. they're unfamiliar with namespace syntax + .. cpp:class:: HardwareTimer Class for interacting with a timer. There are four predefined diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 08fa5c1..899f720 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -6,6 +6,8 @@ Maple Quickstart Guide ======================== +.. TODO update the images since we changed "to FLASH" -> "to Flash" + You'll need a `Maple board `_, a `Mini-B USB cable `_, a functional computer, and possibly root (or "administrator") access to @@ -58,9 +60,9 @@ Next, select Tools > Board > "LeafLabs Maple ... to FLASH": :align: left :alt: Verify button -Now press the "verify" button (furthest to the left with a "play" -arrow) to compile the code. Some output should scroll by in the -bottom window, and then a confirmation message will appear: +Now press the "Verify" button (the "play" symbol; see image at left) +to compile the code. Some output should scroll by in the bottom +window, and then a confirmation message will appear: .. image:: /_static/img/verify-success.png :align: center @@ -71,11 +73,12 @@ bottom window, and then a confirmation message will appear: Upload that program! -------------------- -Now it's (finally!) time to plug in your Maple. Use a mini-b cable, -making sure that the power source jumper is on the USB header first. -We ship Maples with the power source jumper configured that way, so -you shouldn't have to do anything. For reference, it should look like -this: +Now it's time to plug in your Maple. Use a Mini-B cable, making sure +that the :ref:`power source jumper ` is on +the USB header first. We ship the Maple with the power source jumper +configured that way, so you shouldn't have to do anything. For +reference, it should look like this (don't worry if a jumper is +hanging half off of the CHRG header): .. image:: /_static/img/plugged-in-maple.png :align: center @@ -105,10 +108,10 @@ it's there. If it ever starts throbbing in a slow, smooth pattern, then you've got a problem: see the :ref:`troubleshooting ` page for help. -If all systems are go, select the Board type and Serial Port -(something like :file:`COM3`, :file:`/dev/ttyACM0`, or -:file:`/dev/tty.usbmodemfa221`, depending on your platform, from the -Tools menu: +If all systems are go, select the Maple's serial port in the Tools > +Serial Port menu. The Maple will appear as something like +:file:`COMx`, :file:`/dev/ttyACMx`, or :file:`/dev/tty.usbmodemxxxxx`, +depending on your platform, like so: Windows XP: @@ -137,12 +140,13 @@ Maple. You should see some text and a progress bar flash by in the status window of the IDE, then some blinky patterns on the Maple, and then a -constant blinking on and off. +constant blinking on and off. Congratulations! You've successfully +uploaded your first program to the Maple. -Go ahead and modify the file a little bit: if you change the -'delay(1000);' numbers to a different value the speed of the blink -will change. The value is a time in milliseconds to pause before -continuing with the program, so by default the LED will be on for 1 +Next, go ahead and modify the file a little bit. If you change the +``delay(1000);`` lines to a different value, the speed of the blink +will change. The value is a time in milliseconds to pause before +continuing with the program, so by default, the LED will be on for 1 second, then off for 1 second, etc. Any time you make any changes, go through the same Verify and Upload process to upload the new version of your program to your Maple. @@ -166,18 +170,18 @@ Use the serial port monitor! ---------------------------- As a last step to make sure everything has been configured correctly, -let's upload a hello world program that will send text from the Maple -back to the IDE over the USB connection. From the File menu, select -Examples > Stubs > HelloWorld (similarly to when you selected the -Blink program), and make sure the correct board and serial port -targets are selected from the Tools pull-down. - -Open the serial monitor window (button on the far right) and make sure -the 9600 baud speed is selected. Then go back to the code editing -window and upload your program (Upload will recompile your code -automatically if there's been any change since the last Verify). You -should get text spit at you over the serial monitor right after the -program is uploaded. Shout back! We can hear you! +let's upload a "Hello, world!" program that will send text from the +Maple back to the IDE over the USB connection. From the File menu, +select Examples > Stubs > HelloWorld (similarly to when you selected +the Blink program), and make sure the correct board and serial port +targets are selected from the Tools menu. + +Open the Serial Monitor window (on the far right of the toolbar) and +make sure the 9600 baud speed is selected. Then go back to the code +editing window and upload your program (Upload will recompile your +code automatically if there's been any change since the last +Verify). You should get text spit at you over the serial monitor right +after the program is uploaded. Shout back! We can hear you! Go forth exuberantly! --------------------- @@ -191,10 +195,11 @@ or maybe now is a good time for a trip to the kitchen for a delicious If you blew through this guide and are the kind of person who drinks their coffee straight, has more than a 100 lines of vim or emacs customization, and doesn't even have a mouse plugged into their -computer, you may want to look at the :ref:`Unix Toolchain quickstart +computer, you may want to look at the :ref:`Unix toolchain quickstart ` guide. It's the tutorial for getting working with -your old friends :command:`make`, :command:`jtag`, and :command:`gcc`. +your old friends :command:`make`, :command:`gcc`, and :command:`jtag`. Let us know what you come up with! Tag us with #leaflabs on Twitter, -post in the `forum`_, track us down in the real world, whatever. We -love projects! +post in the `forum`_, post on `our wiki's Projects page +`_, track us down +in the real world, whatever. We love projects! diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index f3052d9..9146ebe 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -106,10 +106,10 @@ A classic! Make sure you have selected a board from the pulldown menu. ----------------------------------------- Your sketch/program either does not include one of the :ref:`setup() -` or `loop() ` functions, or it was not found -by the compiler. Your program must include both ``void setup()`` and -``void loop()`` functions; they don't have to do anything, but they -**must** be there. +` or :ref:`loop() ` functions, or it was not +found by the compiler. Your program must include both ``void setup()`` +and ``void loop()`` functions; they don't have to do anything, but +they **must** be there. You can start with an example program (to see one in the IDE, click on File > Examples > Stubs > BareMinimum) to get the basic structure. diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 836f777..d49b642 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -6,11 +6,12 @@ Unix Toolchain Quickstart =========================== -This is a tutorial for using the Maple with a standard Unix toolchain. -It's not necessary to do this in order to program the Maple; you can -always :ref:`install the Maple IDE ` instead. +This is a tutorial for using the Maple with a standard Unix toolchain +(make, gcc, etc.). It's not necessary to do this in order to program +the Maple; you can always :ref:`install the Maple IDE +` instead. -You'll need a Maple board, a mini-b USB cable, a functional computer, +You'll need a Maple board, a Mini-B USB cable, a functional computer, and root access to that computer. This guide assumes you've had success with the IDE on your machine and that you are fairly comfortable with the Unix command line; some previous experience with -- cgit v1.2.3 From d66669360823f4a958f7c8e5699250bbb0d1ea7b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 16 Feb 2011 15:56:22 -0500 Subject: another minor docs fix --- source/language-index.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/language-index.rst b/source/language-index.rst index e160e2b..3c55c33 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -7,9 +7,8 @@ Complete Language Index This is the index of Maple's :ref:`language reference ` documentation. The "Maple API" column provides API references for documented libmaple functionality. The "C++ for -Maple".. pages are adaptations of the Arduino C++ documentation to the -.. Maple, and are intended as a minimal reference/refresher for -.. programmers familiar with the Arduino language. +Maple" pages are intended as a minimal reference/refresher for +programmers familiar with the Arduino language. .. _index-language-index-cpp: .. _index-language-index-api: -- cgit v1.2.3 From 01c3eb389e314b4363eb670940b5bf7978b1678e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 24 Feb 2011 14:42:30 -0500 Subject: Rewrote Print class. The old Print class couldn't print uint64 values, and featured hand-hacked functionality better handled by snprintf(). Redid it using snprintf(), using "[u]int[8,16,32,64]" types for more clarity, and eliminated some private methods in favor of auxiliary functions in Print.cpp. Breaking compatibility with original implementation in three ways: - Print::print(double) is now accurate to 6 digits, rather than 2; this is consistent with the default behavior of the %f format specifier, and if you're using floating point, it's slow enough that you probably want the increased accuracy. - The only bases you can print a number to are 2, 8, 10, and 16. 8, 10, and 16 already have format specifiers, and 2 is an important special case; others complicate matters unnecessarily. - Printing numbers in bases other than 10 treats them as unsigned quantities (i.e., won't print '-' characters). This is more consistent with C++'s behavior for hexadecimal and octal literals (e.g., 0xFFFFFFFF has type uint32). Updated HardwareSerial and USBSerial class documentation to reflect the new behavior. --- source/lang/api/serial.rst | 35 ++++++++++++++++++++++++----------- source/lang/api/serialusb.rst | 35 ++++++++++++++++++++++++----------- 2 files changed, 48 insertions(+), 22 deletions(-) diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst index ca89b31..58002e3 100644 --- a/source/lang/api/serial.rst +++ b/source/lang/api/serial.rst @@ -113,25 +113,34 @@ means that you can use any of these functions on any of ``Serial1``, Print the argument's digits over the USART, in decimal format. -.. cpp:function:: HardwareSerial::print(long n) +.. cpp:function:: HardwareSerial::print(long long n) Print the argument's digits over the USART, in decimal format. Negative values will be prefixed with a ``'-'`` character. -.. cpp:function:: HardwareSerial::print(unsigned long n) +.. cpp:function:: HardwareSerial::print(unsigned long long n) Print the argument's digits over the USART, in decimal format. -.. cpp:function:: HardwareSerial::print(long n, int base) +.. _lang-serial-print-n-base: - Print the digits of ``n`` over the USART, in base ``base`` (which - may be between 2 and 16). The ``base`` value 2 corresponds to - binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative - values will be prefixed with a ``'-'`` character. +.. cpp:function:: HardwareSerial::print(int n, int base) + + Print the digits of ``n`` over the USART, in base ``base``. The + ``base`` value 2 corresponds to binary, 8 to octal, 10 to decimal, + and 16 to hexadecimal (you can also use the symbolic constants + ``BIN``, ``OCT``, ``DEC``, ``HEX``). If ``base`` is 10, negative + values will be prefixed with a ``'-'`` character (otherwise, ``n`` + will be interpreted as an unsigned quantity). + +.. cpp:function:: HardwareSerial::print(long long n, int base) + + Same behavior as the above :ref:`print(int n, int base) + `, except with 64-bit values. .. cpp:function:: HardwareSerial::print(double n) - Print ``n``, accurate to 2 digits after the decimal point. + Print ``n``, accurate to 6 digits after the decimal point. .. _lang-serial-println: @@ -155,15 +164,19 @@ means that you can use any of these functions on any of ``Serial1``, Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(long n) +.. cpp:function:: HardwareSerial::println(long long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(unsigned long n) +.. cpp:function:: HardwareSerial::println(unsigned long long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(long n, int base) +.. cpp:function:: HardwareSerial::println(int n, int base) + + Like ``print(n, b)``, followed by ``"\r\n"``. + +.. cpp:function:: HardwareSerial::println(long long n, int base) Like ``print(n, b)``, followed by ``"\r\n"``. diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst index 3bb8c00..87fa641 100644 --- a/source/lang/api/serialusb.rst +++ b/source/lang/api/serialusb.rst @@ -109,26 +109,35 @@ world!")``. Print the argument's digits over the USB connection, in decimal format. -.. cpp:function:: USBSerial::print(long n) +.. cpp:function:: USBSerial::print(long long n) Print the argument's digits over the USB connection, in decimal format. Negative values will be prefixed with a ``'-'`` character. -.. cpp:function:: USBSerial::print(unsigned long n) +.. cpp:function:: USBSerial::print(unsigned long long n) Print the argument's digits over the USB connection, in decimal format. -.. cpp:function:: USBSerial::print(long n, int base) +.. _lang-serial-print-n-base: - Print the digits of ``n`` over the USB connection, in base ``base`` - (which may be between 2 and 16). The ``base`` value 2 corresponds - to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. - Negative values will be prefixed with a ``'-'`` character. +.. cpp:function:: USBSerial::print(int n, int base) + + Print the digits of ``n`` over USB, in base ``base``. The ``base`` + value 2 corresponds to binary, 8 to octal, 10 to decimal, and 16 to + hexadecimal (you can also use the symbolic constants ``BIN``, + ``OCT``, ``DEC``, ``HEX``). If ``base`` is 10, negative values + will be prefixed with a ``'-'`` character (otherwise, ``n`` will be + interpreted as an unsigned quantity). + +.. cpp:function:: HardwareSerial::print(long long n, int base) + + Same behavior as the above :ref:`print(int n, int base) + `, except with 64-bit values. .. cpp:function:: USBSerial::print(double n) - Print ``n``, accurate to 2 digits after the decimal point. + Print ``n``, accurate to 6 digits after the decimal point. .. _lang-serialusb-println: @@ -152,15 +161,19 @@ world!")``. Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: USBSerial::println(long n) +.. cpp:function:: USBSerial::println(long long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: USBSerial::println(unsigned long n) +.. cpp:function:: USBSerial::println(unsigned long long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: USBSerial::println(long n, int base) +.. cpp:function:: USBSerial::println(int n, int base) + + Like ``print(n, b)``, followed by ``"\r\n"``. + +.. cpp:function:: USBSerial::println(long long n, int base) Like ``print(n, b)``, followed by ``"\r\n"``. -- cgit v1.2.3 From 076f42c1650f78797d8fba59b375d28bd26dea82 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 27 Feb 2011 11:42:56 -0500 Subject: Cleaned out libmaple.h; this had wide-ranging implications. Many of the #defines in libmaple.h were board-specific, not MCU-specific. Most of these were only used by code under libmaple/usb/. These were moved into usb_config.h, and are clearly marked as being terrible hacks. I'm going to treat the USB stack as a black box that we'll deal with later. Further, instead of having a variety of #defines like "How many USARTS do I have?", we decide that based on the density of the chip. This is determined by testing for STM32_MEDIUM_DENSITY or STM32_HIGH_DENSITY defines. libmaple currently doesn't support low-density chips, so that suffices. The Makefile will set these automatically based on the MCU. Other offending #defines are ERROR_LED_PORT and ERROR_LED_PIN; these were made optional, but they're set in the Makefile as a hack to keep things working. --- source/language.rst | 57 +++++++++++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/source/language.rst b/source/language.rst index 2ebe03c..b2f4650 100644 --- a/source/language.rst +++ b/source/language.rst @@ -17,36 +17,6 @@ language and C++ may wish to skip to the .. contents:: Contents :local: -Unique Maple Additions ----------------------- - -.. _language-assert: - -``ASSERT(...)`` - The ``ASSERT()`` function can be very useful for basic program - debugging. The function accepts a boolean; for example:: - - ASSERT(state == WAIT); - - zero is false and any other number is true. If the boolean is true - the assertion passes and the program continues as usual. If it is - false, the assertion fails: the program is halted, debug - information is printed to USART2, and the status LED begins to - throb in intensity (it's noticeably different from blinking). The - debug information is printed at 9600 baud and consists of the - filename and line number where the particular assertion failed. - - Including assertions in a program increases the program size. When - using libmaple **from the command line only**, they can be - disabled by making the definition :: - - #define DEBUG_LEVEL DEBUG_NONE - - before including either wirish.h or libmaple.h. In this case, all - assertions will pass without any lost clock cycles. Note that - this will **not work in the IDE**; even with this definition, - assertions will still be enabled. - .. _language-lang-docs: Maple Language Reference @@ -217,6 +187,33 @@ A more exhaustive index is available at the :ref:`language-index`. | | | | +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ +``ASSERT(...)`` +--------------- + +The ``ASSERT()`` function can be very useful for basic program +debugging. The function accepts a boolean; for example:: + + ASSERT(state == WAIT); + +Zero is false and any other number is true. If the boolean is true, the +assertion passes and the program continues as usual. If it is false, +the assertion fails: the program is halted, debug information is +printed to USART2, and the status LED begins to throb in intensity +(it's noticeably different from blinking). The debug information is +printed at 9600 baud and consists of the filename and line number +where the particular assertion failed. + +Including assertions in a program increases the program size. When +using libmaple **from the command line only**, they can be disabled by +making the definition :: + + #define DEBUG_LEVEL DEBUG_NONE + +before including either wirish.h or libmaple.h. In this case, all +assertions will pass without any lost clock cycles. Note that this +will **not work in the IDE**; even with this definition, assertions +will still be enabled. + .. _language-missing-features: Missing Arduino Features -- cgit v1.2.3 From 9e0e3b5078b730b0b789faefddbab90d9b1234a7 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 4 Mar 2011 19:15:24 -0500 Subject: Untabifying docs/source/conf.py --- source/conf.py | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/source/conf.py b/source/conf.py index 1ad4e57..f232b7c 100644 --- a/source/conf.py +++ b/source/conf.py @@ -117,25 +117,25 @@ html_theme = 'default' # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - ## Sidebar placement options - #'stickysidebar' : 'true', - 'rightsidebar' : 'true', - #'collapsiblesidebar' : 'true', - - ## Color - 'sidebarbgcolor' : '#C8C8C8', - 'sidebarlinkcolor' : 'green', - 'sidebartextcolor' : 'black', + ## Sidebar placement options + #'stickysidebar' : 'true', + 'rightsidebar' : 'true', + #'collapsiblesidebar' : 'true', + + ## Color + 'sidebarbgcolor' : '#C8C8C8', + 'sidebarlinkcolor' : 'green', + 'sidebartextcolor' : 'black', #'sidebarbtncolor' : 'black', - 'footerbgcolor' : 'green', - 'relbarbgcolor' : 'green', - 'headlinkcolor' : '#000000', - 'linkcolor' : 'green', - 'visitedlinkcolor' : 'green', - - ## Font - 'headfont' : 'Georgia', - 'bodyfont' : 'Lucidia' + 'footerbgcolor' : 'green', + 'relbarbgcolor' : 'green', + 'headlinkcolor' : '#000000', + 'linkcolor' : 'green', + 'visitedlinkcolor' : 'green', + + ## Font + 'headfont' : 'Georgia', + 'bodyfont' : 'Lucidia' } # Add any paths that contain custom themes here, relative to this directory. @@ -174,7 +174,7 @@ html_last_updated_fmt = '%b %d, %Y' # re-add commented line when custom template for api finished html_sidebars = { '**': ['globaltoc.html', 'searchbox.html'], - #'lang/api**':['searchbox.html', 'apilist.html'], + #'lang/api**':['searchbox.html', 'apilist.html'], } -- cgit v1.2.3 From 5a5aea2044997c83e330867ada4acee8b487470b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 4 Mar 2011 23:16:53 -0500 Subject: USBSerial docs fix. --- source/lang/api/serialusb.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst index 87fa641..4ddfa4a 100644 --- a/source/lang/api/serialusb.rst +++ b/source/lang/api/serialusb.rst @@ -224,7 +224,7 @@ running from battery, or connected but not monitored. You may need to experiment with the DTR/RTS logic for your platform and device configuration. :: - #define LED_PIN 13 + #define LED_PIN BOARD_LED_PIN void setup() { /* Set up the LED to blink */ @@ -232,22 +232,22 @@ configuration. :: } void loop() { - // LED will stay off if we are disconnected; - // will blink quickly if USB is unplugged (battery etc) + // LED will stay off if we are disconnected, and will blink + // quickly if USB is unplugged (battery power, etc.). if(SerialUSB.isConnected()) { digitalWrite(LED_PIN, 1); } delay(100); - // If this logic fails to detect if bytes are going to - // be read by the USB host, then the println() will fully - // many times, causing a very slow LED blink. - // If the characters are printed and read, the blink will - // only slow a small amount when "really" connected, and fast - // when the virtual port is only configured. + // If this logic fails to detect if bytes are going to be read + // by the USB host, then the println() take a long time, + // causing a very slow LED blink. If the characters are + // printed and read, the blink will only slow a small amount + // when "really" connected, and will be fast fast when the + // virtual port is only configured. if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) { - for(int i=0; i<10; i++) { - SerialUSB.println(123456,BIN); + for(int i = 0; i < 10; i++) { + SerialUSB.println(123456, BIN); } } digitalWrite(LED_PIN, 0); -- cgit v1.2.3 From 8c78529f58dffb28938daf4dda0e7adb534b903c Mon Sep 17 00:00:00 2001 From: Perry Hung Date: Wed, 9 Mar 2011 23:25:03 -0500 Subject: Merge refactor into i2c-wip: Squashed commit of the following: commit 4d6662dadfda7f2fd55107535165dc98a0638a3c Merge: 174d9ab 7ddc844 Author: Marti Bolivar Date: Fri Mar 4 23:18:29 2011 -0500 Merge remote branch 'origin/refactor' into refactor commit 174d9ab73cc3387a3812e6f3d3e97519bf5b2150 Author: Marti Bolivar Date: Fri Mar 4 23:16:53 2011 -0500 USBSerial docs fix. commit f217acb73d94f0a88bf33a42684e6e988dcb3685 Author: Marti Bolivar Date: Fri Mar 4 20:25:26 2011 -0500 Brought examples/ up to date; PIN_MAP bugfix for D24. commit c4ba3ba05fc39ef260cd80d91759966952df74ae Author: Marti Bolivar Date: Fri Mar 4 19:16:42 2011 -0500 Cosmetic/documentation changes to adc.c commit e7747b4eb831621951deef6d31629f55cb5c3500 Author: Marti Bolivar Date: Fri Mar 4 19:16:07 2011 -0500 Cosmetic changes to wirish/main.cxx commit e2f9d4116e59d8487c936989384228ea084a3501 Author: Marti Bolivar Date: Fri Mar 4 19:15:24 2011 -0500 Untabifying docs/source/conf.py commit 7ddc84481b4eebe337065a0219e3d8dc000791e5 Author: Perry Hung Date: Wed Mar 2 00:30:19 2011 -0500 cscope: Find .S instead of .s files commit 62cb09ed6357eae58b0234fbc074c44e9c0aa5e5 Author: Marti Bolivar Date: Wed Mar 2 00:07:10 2011 -0500 Fixing typo in main.cpp.example. --- source/conf.py | 38 +++++++++++++++++++------------------- source/lang/api/serialusb.rst | 22 +++++++++++----------- 2 files changed, 30 insertions(+), 30 deletions(-) diff --git a/source/conf.py b/source/conf.py index 1ad4e57..f232b7c 100644 --- a/source/conf.py +++ b/source/conf.py @@ -117,25 +117,25 @@ html_theme = 'default' # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - ## Sidebar placement options - #'stickysidebar' : 'true', - 'rightsidebar' : 'true', - #'collapsiblesidebar' : 'true', - - ## Color - 'sidebarbgcolor' : '#C8C8C8', - 'sidebarlinkcolor' : 'green', - 'sidebartextcolor' : 'black', + ## Sidebar placement options + #'stickysidebar' : 'true', + 'rightsidebar' : 'true', + #'collapsiblesidebar' : 'true', + + ## Color + 'sidebarbgcolor' : '#C8C8C8', + 'sidebarlinkcolor' : 'green', + 'sidebartextcolor' : 'black', #'sidebarbtncolor' : 'black', - 'footerbgcolor' : 'green', - 'relbarbgcolor' : 'green', - 'headlinkcolor' : '#000000', - 'linkcolor' : 'green', - 'visitedlinkcolor' : 'green', - - ## Font - 'headfont' : 'Georgia', - 'bodyfont' : 'Lucidia' + 'footerbgcolor' : 'green', + 'relbarbgcolor' : 'green', + 'headlinkcolor' : '#000000', + 'linkcolor' : 'green', + 'visitedlinkcolor' : 'green', + + ## Font + 'headfont' : 'Georgia', + 'bodyfont' : 'Lucidia' } # Add any paths that contain custom themes here, relative to this directory. @@ -174,7 +174,7 @@ html_last_updated_fmt = '%b %d, %Y' # re-add commented line when custom template for api finished html_sidebars = { '**': ['globaltoc.html', 'searchbox.html'], - #'lang/api**':['searchbox.html', 'apilist.html'], + #'lang/api**':['searchbox.html', 'apilist.html'], } diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst index 87fa641..4ddfa4a 100644 --- a/source/lang/api/serialusb.rst +++ b/source/lang/api/serialusb.rst @@ -224,7 +224,7 @@ running from battery, or connected but not monitored. You may need to experiment with the DTR/RTS logic for your platform and device configuration. :: - #define LED_PIN 13 + #define LED_PIN BOARD_LED_PIN void setup() { /* Set up the LED to blink */ @@ -232,22 +232,22 @@ configuration. :: } void loop() { - // LED will stay off if we are disconnected; - // will blink quickly if USB is unplugged (battery etc) + // LED will stay off if we are disconnected, and will blink + // quickly if USB is unplugged (battery power, etc.). if(SerialUSB.isConnected()) { digitalWrite(LED_PIN, 1); } delay(100); - // If this logic fails to detect if bytes are going to - // be read by the USB host, then the println() will fully - // many times, causing a very slow LED blink. - // If the characters are printed and read, the blink will - // only slow a small amount when "really" connected, and fast - // when the virtual port is only configured. + // If this logic fails to detect if bytes are going to be read + // by the USB host, then the println() take a long time, + // causing a very slow LED blink. If the characters are + // printed and read, the blink will only slow a small amount + // when "really" connected, and will be fast fast when the + // virtual port is only configured. if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) { - for(int i=0; i<10; i++) { - SerialUSB.println(123456,BIN); + for(int i = 0; i < 10; i++) { + SerialUSB.println(123456, BIN); } } digitalWrite(LED_PIN, 0); -- cgit v1.2.3 From a72539472a70be072da3fcaeb495abbfa2ba8971 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 7 Mar 2011 13:11:54 -0500 Subject: [WIP] GPIO refactor: seems ok, ready for review --- Doxyfile | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doxyfile b/Doxyfile index 3290843..9bf02fc 100644 --- a/Doxyfile +++ b/Doxyfile @@ -620,7 +620,9 @@ RECURSIVE = YES # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. -EXCLUDE = +# FIXME The USB thing needs to get redone (ST code stripped out, +# etc.). Until then, just ignore it. +EXCLUDE = ../libmaple/usb/ # The EXCLUDE_SYMLINKS tag can be used select whether or not files or # directories that are symbolic links (a Unix filesystem feature) are excluded @@ -1369,7 +1371,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = ALWAYS_INLINE= \ +PREDEFINED = __attribute__()= \ __cplusplus # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -- cgit v1.2.3 From 0a7db537ea2b28c3ea2b656dd6a4c8e026a7bf9f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 11 Mar 2011 16:46:33 -0500 Subject: Cleanups; new support/gdb/gpio.gdb. --- README | 73 ++++++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 29 deletions(-) diff --git a/README b/README index 326d278..7a50a54 100644 --- a/README +++ b/README @@ -1,16 +1,42 @@ -This directory contains the Sphinx documentation for libmaple, as well -as a Doxygen configuration file; we turn Doxygen XML output into -Sphinx documentation. You can generate HTML documentation using the -Makefile if you have make, or using make.bat from Windows. +This directory contains source files used to generate libmaple's +documentation. + +The generated documentation for the latest libmaple release is +available online in HTML form at http://leaflabs.com/docs/. The web +interface is the recommended way for users to read the documentation. + +This file contains instructions for generating the HTML files. + +About the Documentation +----------------------- + +The docs are written in Sphinx's extensions to reStructuredText +(reST). You can read more about Sphinx here: + + http://sphinx.pocoo.org/tutorial.html + +Much of the documentation is pulled out of the libmaple source code; +we use Doxygen XML output into Sphinx documentation. You can read +more about Doxygen here: + + http://doxygen.org + +We use a Sphinx plugin called Breathe to parse Doxygen's XML output +into a form usable by Sphinx. You can read more about Breathe here: + + http://michaeljones.github.com/breathe/ Documentation Build Steps ------------------------- +You first need to produce Doxygen XML output, then you can generate +the HTML documentation. + 1. You need a recent-ish version of Doxygen in your PATH: http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc -2. Install breathe, which does Doxygen-to-Sphinx conversion: +2. Install Breathe, which does Doxygen-to-Sphinx conversion: Read/write version (for LeafLabs developers): @@ -37,9 +63,11 @@ Documentation Build Steps $ sudo easy_install -U Sphinx + You need Sphinx version >= 1.0.6. + 4. Before the first time you run Sphinx (and any time the Doxygen comments in the libmaple source code are changed), you'll need to - rebuild the Doxygen XML output: + build the Doxygen XML output: $ cd libmaple/docs/source $ doxygen @@ -48,36 +76,23 @@ Documentation Build Steps $ make html - (Read the Makefile for more targets). + On Windows, use the batch file make.bat instead. Reading and Modifying the Documentation --------------------------------------- -The net effect of the above is to produce Doxygen XML output (ignore -this) in libmaple/docs/doxygen/xml, and HTML documentation (this is -what you want) in libmaple/docs/build/html. - Just point your web browser at the file - libmaple/docs/build/html/index.html + /docs/build/html/index.html -it corresponds to the Sphinx file +It corresponds to the Sphinx file - libmaple/docs/source/index.rst - -All of the documentation itself lives in libmaple/docs/source/. The -directory source/_static/ is for static content (like style sheets); -source/_templates/ contains Sphinx templates (or, it would, if we had -any). - -The docs are written in Sphinx's version of reStructuredText (reST); -it's a Python thing that they use to produce the docs at -http://python.org. You can read more about Sphinx here: - - http://sphinx.pocoo.org/tutorial.html + /docs/source/index.rst -You can view the source for any generated page of documentation by -clicking the "Show Source" link in the sidebar. +The file /docs/source/conf.py is the Sphinx configuration file; you +can go read it for more information about our setup. -The file libmaple/docs/source/conf.py is the Sphinx configuration -file; you can go read it for more information about our setup. +All of the documentation which isn't pulled out of source code +comments lives in /docs/source/. The directory /docs/source/_static/ +is for static content (like style sheets); /docs/source/_templates/ +contains Sphinx templates. -- cgit v1.2.3 From 5d3d198d87df5224f5caabccc18ae895b437cebd Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 11 Mar 2011 20:43:59 -0500 Subject: shiftOut(), docs fixes --- source/bootloader.rst | 56 +++++++------- source/lang/api/constants.rst | 8 -- source/lang/api/shiftout.rst | 99 ++++++++++++++++++++++++ source/lang/unimplemented/shiftout.rst | 136 --------------------------------- source/language-index.rst | 1 - source/language.rst | 9 ++- 6 files changed, 132 insertions(+), 177 deletions(-) create mode 100644 source/lang/api/shiftout.rst delete mode 100644 source/lang/unimplemented/shiftout.rst diff --git a/source/bootloader.rst b/source/bootloader.rst index 57833ed..cfbf545 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -66,7 +66,7 @@ have embedded USB support. Thus, Maple doesn’t need the extra FTDI chip. Firmware is uploaded via the standard DFU protocol (also used by iPhone and openMoko). Since DFU is a standard, there is no need for custom software running on the host to upload the firmware. Any DFU -compliant program will work. The maple ide is based around +compliant program will work. The Maple IDE is based around :command:`dfu-util`, openMoko’s DFU utility. Using DFU came at a cost, however. The USB port must additionally implement a separate serial port at the same time (we use the CDC ACM class for serial @@ -87,11 +87,11 @@ important what this means, except for two things. 1. Four drivers were necessary to make everything work. 2. IAD is not supported by OS X. -Mac, on the other hand, only supported Compound USB, a different trick -that is not supported by Windows. While a perpetual background +Mac OS X, on the other hand, only supported Compound USB, a different +trick that is not supported by Windows. While a perpetual background bootloader was attractive, it became clear, after much toiling, we -were going to have to write some custom drivers across several -platforms to make everything work this way. +were going to have to write custom drivers across several platforms to +make everything work this way. .. _bootloader-rev3: @@ -103,22 +103,21 @@ Arduino. In Rev 3, the device resets into bootloader mode, which stays alive for a few moments to receive commands, and then jumps to user code. The bootloader is implemented as a DFU device -- just a DFU device, no serial port. This requires one driver for Windows -(:file:`drivers/mapleDrv/dfu` in the Windows IDE directory). As part -of the :ref:`libmaple ` library, user code is automatically -supplied with serial support via some behind the scenes work that -happens automatically when you compile (``setupUSB()`` is appended to -``setup()``). This user mode code only implements a CDC ACM class USB -device, giving you functions like ``Usb.print()``. Separating these -two modes fixed the driver issue, required no complicated compound USB -device nonsense, and works well across platforms, requiring only two -drivers (serial and DFU) on Windows. +(:file:`drivers/mapleDrv/dfu` in the Windows IDE directory). + +As part of the :ref:`libmaple ` library, user code is +automatically supplied with serial support via some behind the scenes +work (``setupUSB()`` is called from ``init()``). This user mode code +only implements a CDC ACM class USB device, giving you functions like +:ref:`SerialUSB.read() `. Separating these two +modes fixed the driver issues and works well across platforms, +requiring only two drivers (serial and DFU) on Windows. However, it is no longer possible to upload code at will, since there -is no bootloader quietly listening in the background. Instead you have -to reset the board, then initiate a DFU transaction. This reset is -performed automatically by the IDE by sending a command over the USB -serial port. You can generate this reset on your own using a Python -script or some other scheme. All you need do is: +is no bootloader quietly listening in the background. Instead, you +must reset the board, then initiate a DFU transaction. The IDE +performs this reset automatically by performing a special sequence of +changes on the USB serial port: 1. Pulse DTR (high and then low, so that you've created a negative edge) @@ -128,15 +127,16 @@ script or some other scheme. All you need do is: negative edge, rather than just ensuring DTR is low. After the reset, the host OS takes a few moments (.5-2 seconds) to -re-enumerate the device as DFU. This delay is unpredictable, and its -the reason the bootloader on Maple Rev3 stays alive for so -long. Sometimes the bootloader was exiting before the OS had even -enumerated the device! Once in bootloader mode, however, -:command:`dfu-util` uploads your sketch into either flash or RAM (DFU -alternate setting 0 or 1, respectively) and resets the board again. -This time, however, no DFU transaction is initiated, and the -bootloader gives way to user code, closing down the DFU pipe and -bringing up the USB serial. +re-enumerate the device as DFU. This delay is unpredictable, and is +the reason the bootloader on Maple Rev 3/Rev 5 stays alive for so +long. (Sometimes, the bootloader was exiting before the OS had even +enumerated the device.) + +Once in bootloader mode, :command:`dfu-util` uploads your sketch into +either flash or RAM (DFU alternate setting 0 or 1, respectively) and +resets the board again. This time, however, no DFU transaction is +initiated, and the bootloader gives way to user code, closing down the +DFU pipe and bringing up the USB serial port. .. .. _bootloader-rev6: diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst index 72738b8..2e968e7 100644 --- a/source/lang/api/constants.rst +++ b/source/lang/api/constants.rst @@ -61,14 +61,6 @@ pin is configured as an ``INPUT`` (using :ref:`pinMode() `, the microcontroller will report ``HIGH`` if a voltage of 3 volts or more is present at the pin. -.. TODO? Following seems false; check it out sometime, leave out for now: - -.. A pin may also be configured as an ``INPUT`` with ``pinMode()``, and -.. subsequently made ``HIGH`` with :ref:`digitalWrite() -.. `, this will set the internal pullup resistors, -.. which will *steer* the input pin to a HIGH reading unless it is pulled -.. LOW by external circuitry. - When a pin is configured to ``OUTPUT`` with pinMode, and set to ``HIGH`` with :ref:`digitalWrite() `, the pin is at 3.3 volts. In this state it can *source* current, e.g. light an LED diff --git a/source/lang/api/shiftout.rst b/source/lang/api/shiftout.rst new file mode 100644 index 0000000..1d9ba12 --- /dev/null +++ b/source/lang/api/shiftout.rst @@ -0,0 +1,99 @@ +.. highlight:: cpp + +.. _lang-shiftout: + +shiftOut() +========== + +Shift out a byte of data, one bit at a time. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: shiftOut + +Discussion +---------- + +This is a software implementation. There is also a hardware :ref:`SPI +` library available which will be faster and consume less CPU +cycles than this function. + +Note that the ``dataPin`` and ``clockPin`` must already be configured +to :ref:`OUTPUT ` mode by a call to +:ref:`pinMode() `. + +Also note that since shiftOut() outputs 1 byte (8 bits) at a time, it +requires multiple steps to output values larger than 255. + +Examples +-------- + +To use these examples, replace ``dataPin`` and ``clockPin`` with the +numbers of the pins you want to use:: + + /* MSBFIRST example */ + + uint16 data = 500; + // shift out high byte + shiftOut(dataPin, clockPin, MSBFIRST, (data >> 8)); + // shift out low byte + shiftOut(dataPin, clockPin, MSBFIRST, data); + + /* LSBFIRST serial */ + + data = 500; + // shift out low byte + shiftOut(dataPin, clockPin, LSBFIRST, data); + // shift out high byte + shiftOut(dataPin, clockPin, LSBFIRST, (data >> 8)); + +Arduino Tutorial Example +------------------------ + +This Arduino example runs unmodified on the Maple. For accompanying +circuit, see the `tutorial on controlling a 74HC595 shift register +`_. + +:: + + //**************************************************************// + // Name : shiftOutCode, Hello World // + // Author : Carlyn Maw, Tom Igoe // + // Date : 25 Oct, 2006 // + // Version : 1.0 // + // Notes : Code for using a 74HC595 Shift Register // + // : to count from 0 to 255 // + //**************************************************************// + + // Pin connected to ST_CP of 74HC595 + int latchPin = 8; + // Pin connected to SH_CP of 74HC595 + int clockPin = 12; + // Pin connected to DS of 74HC595 + int dataPin = 11; + + void setup() { + // Set pins to output because they are addressed in the main loop + pinMode(latchPin, OUTPUT); + pinMode(clockPin, OUTPUT); + pinMode(dataPin, OUTPUT); + } + + void loop() { + // Count up routine + for (int j = 0; j < 256; j++) { + // Ground latchPin and hold low for as long as you are transmitting + digitalWrite(latchPin, LOW); + shiftOut(dataPin, clockPin, LSBFIRST, j); + // Return the latch pin high to signal chip that it + // no longer needs to listen for information + digitalWrite(latchPin, HIGH); + delay(1000); + } + } + +.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/shiftout.rst b/source/lang/unimplemented/shiftout.rst deleted file mode 100644 index ff3852f..0000000 --- a/source/lang/unimplemented/shiftout.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. _lang-shiftout: - -shiftOut() -========== - -Description ------------ - -Shifts out a byte of data one bit at a time. Starts from either the -most (i.e. the leftmost) or least (rightmost) significant bit. Each -bit is written in turn to a data pin, after which a clock pin is -pulsed to indicate that the bit is available. - - - -This is a software implementation; Arduino (as of 0019) also -provides an `SPI library `_ -that uses the hardware implementation. - - - -Syntax ------- - -shiftOut(dataPin, clockPin, bitOrder, value) - - - -Parameters ----------- - -dataPin: the pin on which to output each bit (*int*) - - - -clockPin: the pin to toggle once the **dataPin** has been set to -the correct value (*int*) - - - -bitOrder: which order to shift out the bits; either **MSBFIRST** or -**LSBFIRST**. -(Most Significant Bit First, or, Least Significant Bit First) - - - -value: the data to shift out. (*byte*) - - - -Returns -------- - -None - - - -Note ----- - -The **dataPin** and **clockPin** must already be configured as -outputs by a call to -`pinMode `_\ (). - - - -**shiftOut** is currently written to output 1 byte (8 bits) so it -requires a two step operation to output values larger than 255. - -:: - - // Do this for MSBFIRST serial - int data = 500; - // shift out highbyte - shiftOut(dataPin, clock, MSBFIRST, (data >> 8)); - // shift out lowbyte - shiftOut(data, clock, MSBFIRST, data); - - // Or do this for LSBFIRST serial - data = 500; - // shift out lowbyte - shiftOut(dataPin, clock, LSBFIRST, data); - // shift out highbyte - shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); - - - -Example -------- - -*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register `_.* - - - -:: - - //**************************************************************// - // Name : shiftOutCode, Hello World // - // Author : Carlyn Maw,Tom Igoe // - // Date : 25 Oct, 2006 // - // Version : 1.0 // - // Notes : Code for using a 74HC595 Shift Register // - // : to count from 0 to 255 // - //**************************************************************** - - //Pin connected to ST_CP of 74HC595 - int latchPin = 8; - //Pin connected to SH_CP of 74HC595 - int clockPin = 12; - ////Pin connected to DS of 74HC595 - int dataPin = 11; - - void setup() { - //set pins to output because they are addressed in the main loop - pinMode(latchPin, OUTPUT); - pinMode(clockPin, OUTPUT); - pinMode(dataPin, OUTPUT); - } - - void loop() { - //count up routine - for (int j = 0; j < 256; j++) { - //ground latchPin and hold low for as long as you are transmitting - digitalWrite(latchPin, LOW); - shiftOut(dataPin, clockPin, LSBFIRST, j); - //return the latch pin high to signal chip that it - //no longer needs to listen for information - digitalWrite(latchPin, HIGH); - delay(1000); - } - } - - - - -.. include:: /lang/cc-attribution.txt diff --git a/source/language-index.rst b/source/language-index.rst index 3c55c33..c949988 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -33,7 +33,6 @@ programmers familiar with the Arduino language. lang/unimplemented/notone.rst lang/unimplemented/pulsein.rst - lang/unimplemented/shiftout.rst lang/unimplemented/stringclass.rst lang/unimplemented/stringobject.rst lang/unimplemented/tone.rst diff --git a/source/language.rst b/source/language.rst index b2f4650..d340aec 100644 --- a/source/language.rst +++ b/source/language.rst @@ -61,7 +61,7 @@ A more exhaustive index is available at the :ref:`language-index`. | |* :ref:`boolean ` (1 byte) | | |* :ref:`{} (curly braces) | |* noTone(): TODO | | ` |* :ref:`char ` (1 byte) | | -| | |* shiftOut(): TODO | +| | |* :ref:`shiftOut() ` | |* :ref:`// (single-line comment) |* :ref:`unsigned char | | | ` | ` (1 byte) |* pulseIn(): TODO | | | | | @@ -187,11 +187,13 @@ A more exhaustive index is available at the :ref:`language-index`. | | | | +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ +.. _language-assert: + ``ASSERT(...)`` --------------- The ``ASSERT()`` function can be very useful for basic program -debugging. The function accepts a boolean; for example:: +debugging. It accepts a boolean; for example:: ASSERT(state == WAIT); @@ -255,11 +257,10 @@ Unimplemented Arduino Features The following Wiring/Arduino features are currently unimplemented on the Maple. However, they will be present in future versions: +- `tone() `_ - `noTone() `_ - `pulseIn() `_ -- `shiftOut() `_ - `String `_ -- `tone() `_ .. _our reference page: http://leaflabs.com/docs/external-interrupts/ -- cgit v1.2.3 From 1e42c8777e04e100d2b1589ae71c6e76a1646eb9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 30 Mar 2011 00:55:51 -0400 Subject: Board-specific values; corresponding QA test generalizations. Various board-specific #defines and arrays of pins added. For the changelog (some of this information predates this commit): * wirish/boards.h now declares the following arrays of pin numbers: * boardPWMPins - PWM-capable pins * boardADCPins - ADC-capable pins * boardUsedPins - pins already in use, e.g. BOARD_BUTTON_PIN It also declares a bool boardUsesPin(uint8 pin) function for convenient testing of whether a pin is in use. * wirish/boards/*.h now define: * BOARD_USART1_TX_PIN * BOARD_USART1_RX_PIN * BOARD_USART2_TX_PIN * BOARD_USART2_RX_PIN * BOARD_USART3_TX_PIN * BOARD_USART3_RX_PIN * BOARD_NR_GPIO_PINS (renamed from NR_GPIO_PINS) * BOARD_NR_USARTS (renamed from NR_USARTS) * BOARD_NR_PWM_PINS * BOARD_NR_ADC_PINS * BOARD_NR_USED_PINS * wirish/boards/maple_native.h now defines: * BOARD_UART4_TX_PIN * BOARD_UART4_RX_PIN * BOARD_UART5_TX_PIN * BOARD_UART5_RX_PIN (Unfortunately, wirish/boards/maple_RET6.h cannot, since at least one of the UART4/UART5 pins are used already; this will require layout changes for a wide-release Maple form factor RET6 board). * wirish/boards/*.cpp all include the corresponding array definitions. They all live in flash by default, thanks to the new __FLASH__ macro in wirish/wirish_types.h, which is a synonym for the existing __attr_flash #define in libmaple/libmaple_types.h. The documentation was updated to include this information. It also gained various FIXME/TODO comments related to its generalization across boards. The quality assurance-related examples (examples/qa-slave-shield.cpp and examples/test-session.cpp) now make heavy use of board-specific values to ensure portability. --- source/arm-gcc.rst | 53 +++++++---- source/compatibility.rst | 2 + source/gpio.rst | 2 + source/i2c.rst | 19 ++-- source/index.rst | 1 + source/lang/api/analogread.rst | 33 ++++--- source/lang/api/board-values.rst | 155 +++++++++++++++++++++++++++++++++ source/lang/api/boardusespin.rst | 27 ++++++ source/lang/api/constants.rst | 26 +++--- source/lang/api/hardwaretimer.rst | 6 ++ source/lang/api/isbuttonpressed.rst | 5 +- source/lang/api/pwmwrite.rst | 2 + source/lang/api/toggleled.rst | 2 +- source/lang/api/waitforbuttonpress.rst | 2 + source/language-index.rst | 4 +- source/language.rst | 46 +++++++--- source/libmaple.rst | 12 +-- 17 files changed, 316 insertions(+), 81 deletions(-) create mode 100644 source/lang/api/board-values.rst create mode 100644 source/lang/api/boardusespin.rst diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index ef745f5..7ecb5d4 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -4,12 +4,11 @@ GCC for Maple ============= -This document provides notes on the current usage of -``arm-none-eabi-gcc``, the `CodeSourcery `_ -version of the GNU `GCC `_ compilers used to -compile programs for the Maple. It is not intended as a reference -manual for GCC; such manuals are available `elsewhere -`_. +This document provides notes on using of ``arm-none-eabi-gcc``, the +`CodeSourcery `_ version of the GNU `GCC +`_ compilers used for the Maple boards. It is +not intended as a reference manual for GCC; such manuals are available +`elsewhere `_. Obtaining ``arm-none-eabi-gcc`` ------------------------------- @@ -17,21 +16,24 @@ Obtaining ``arm-none-eabi-gcc`` Recent versions of ``arm-none-eabi-gcc`` and associated tools are included with the :ref:`Maple IDE `. -Users who wish to use ``arm-none-eabi-gcc`` in concert with a standard -Unix toolchain are referred to our :ref:`unix-toolchain` reference, -which describes how to set up such an environment. +Users who wish to use ``arm-none-eabi-gcc`` directly, along with a +standard Unix Make-based toolchain, should read the +:ref:`unix-toolchain`, which describes how to set up such an +environment. -LeafLabs mirrors some of the more recent versions of the compiler -under http://static.leaflabs.com/pub/codesourcery/\ , including -versions for OS X, win32, and 32-bit Linux. +LeafLabs maintains `mirrors +`_ for some of the more +recent versions of the compiler, including versions for OS X, Win32, +and 32-bit Linux. Compiler Flags Used by libmaple ------------------------------- This section documents the flags passed to ``arm-none-eabi-gcc`` by -the :ref:`Maple IDE ` and the default Makefile provided with -:ref:`libmaple `. The information in this section is -subject to change without notice. +the :ref:`Maple IDE ` and the default Makefile provided with the +:ref:`Unix toolchain `. The information in this +section is subject to change between :ref:`libmaple ` +releases. .. highlight:: sh @@ -40,7 +42,8 @@ The following flags are among those passed to the C compiler:: -Os -g -mcpu=cortex-m3 -mthumb -march=armv7-m -nostdlib -ffunction-sections -fdata-sections -Wl,--gc-sections -The following flags are among those passed to the C++ compiler:: +In addition to those flags just given for the C compiler, the +following flags are among those passed to the C++ compiler:: -fno-rtti -fno-exceptions -Wall @@ -52,6 +55,15 @@ The following flags are among those passed to the assembler:: .. _arm-gcc-avr-gcc: +Using the C Standard Library +---------------------------- + +By default (under both the :ref:`Maple IDE ` and the :ref:`Unix +toolchain `), ``arm-none-eabi-gcc`` is configured to +link against `newlib `_, a C standard +library intended for use with embedded applications. You are free to +include of any of its headers. + Switching from AVR-GCC ---------------------- @@ -63,8 +75,11 @@ including Arduino) for use on the Maple. .. _arm-gcc-attribute-flash: - Replacing ``PROGMEM``: You can direct the linker script provided - with libmaple to store a variable in flash by using - ``__attribute__((section (".USER_FLASH")))``, like so:: + with libmaple to store a variable in Flash (instead of RAM) by using + the libmaple macro ``__FLASH__``, like so:: - uint32 arr[] __attribute__((section (".USER_FLASH"))) = {...}; + uint32 array[] __FLASH__ = {0, 1, 2}; + Be aware, however, that if you do that, you can only store values + which are compile-time constants, and that if you attempt to change + a variable stored in Flash, your program will crash. diff --git a/source/compatibility.rst b/source/compatibility.rst index 0d6319f..eb28ad2 100644 --- a/source/compatibility.rst +++ b/source/compatibility.rst @@ -41,6 +41,8 @@ means that programs aren't much larger (or are even smaller). Header Numbering and Incompatibilities -------------------------------------- +.. FIXME generalize Maple-specific information + The numbering of headers is different; on the Maple each GPIO has a unique number: D0, D1, D2, all the way up to D37 (actually, there are :ref:`a few more `...). On the Arduino, the analog pins are diff --git a/source/gpio.rst b/source/gpio.rst index cebb402..5daf43c 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -3,6 +3,8 @@ GPIO ==== +.. FIXME generalize this maple-specific information + The Maple features 38 ready-to-use general purpose input/output (GPIO) pins for digital input/output, numbered D0 through D37. These numbers correspond to the numeric values next to each header on the Maple diff --git a/source/i2c.rst b/source/i2c.rst index b4a996b..e2a7a04 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -4,11 +4,16 @@ |i2c| ===== +.. FIXME update this documentation once you write the Wire library on +.. top of libmaple i2c. + +.. FIXME generalize Maple-specific documentation + .. note:: - The |i2c| interface is currently only available from the 'i2c' branch - of the github `libmaple `_ - repository. + The |i2c| interface is currently only available from the 'refactor' + branch of the github `libmaple + `_ repository. |i2c| is a crude and easy-to-hack serial protocol that requires only two wires/channels for communication between many devices. Every @@ -56,10 +61,8 @@ Function Reference ------------------ The function API for |i2c| is not finished! See the `source code -`_ for -now. - -.. TODO link to libmaple I2C docs once (1) finished, (2) in master +`_ +for now. SMBus ----- @@ -68,8 +71,6 @@ The STM32 microcontroller has hardware support for SMBus; we simply have not written software for it. The SMBAL line for i2c1 is on header D4 and for i2c2 is on D31. -.. TODO link to libmaple SMBus docs once (1) finished, (2) in master - .. _i2c-recommended-reading: Recommended Reading diff --git a/source/index.rst b/source/index.rst index 4369fbd..de71411 100644 --- a/source/index.rst +++ b/source/index.rst @@ -38,6 +38,7 @@ Have fun! Bootloader Troubleshooting Known Problems + Notes on GCC's ARM target .. _index-hardware: diff --git a/source/lang/api/analogread.rst b/source/lang/api/analogread.rst index 35c6fbc..7099b69 100644 --- a/source/lang/api/analogread.rst +++ b/source/lang/api/analogread.rst @@ -35,6 +35,8 @@ have to do this once, so it's usually done in :ref:`lang-setup`\ ). Parameter Discussion -------------------- +.. FIXME generalize Maple-specific information + The pin parameter is the number of the analog input pin to read from. Header pins on the Maple with ADC functionality (marked as "AIN" on the silkscreen) are: @@ -49,24 +51,25 @@ Note ---- If the analog input pin is not connected to anything, the value -returned by analogRead() will fluctuate based on a number of factors -(e.g. the values of the other analog inputs, how close your hand is to -the board, etc.) in a seemingly random way. +returned by ``analogRead()`` will fluctuate due to a number of reasons +(like the values of the other analog inputs, how close your hand is to +the board, etc.) in a "random" way. Example ------- - :: +:: + int analogPin = 3; // Potentiometer wiper (middle terminal) connected + // to analog pin 3. outside leads to ground and +3.3V. + // You may have to change this value if your board + // cannot perform ADC conversion on pin 3. - int analogPin = 3; // potentiometer wiper (middle terminal) connected - // to analog pin 3. outside leads to ground and +3.3V int val = 0; // variable to store the value read void setup() { pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input - SerialUSB.begin(); // set up usb virtual COM port } void loop() { @@ -97,23 +100,27 @@ shift ` the value of a Maple readout by 2, like so:: // be aware that you're losing a lot of precision if you do this int adc_reading = analogRead(pin) >> 2; +.. FIXME Mention Native can do analogReference(), when it's time + On the Arduino, the input range and resolution can be changed using their implementation of `analogReference() `_\ . Because of the way its hardware (as of Rev 5) was designed, it's not possible to implement analogReference on the Maple, so this function doesn't exist. If your inputs lie in a different voltage range than 0V--3.3V, -you'll need to bring them into that range before using analogRead. -Some basic tools to accomplish this are `resistor dividers -`_ and `Zener diodes +you'll need to bring them into that range before using +``analogRead()``. Some basic tools to accomplish this are `resistor +dividers `_ and `Zener +diodes `_\ -. However, opamps and other powered components can also be used if -greater precision is required. +. However, `operational amplifiers +`_ and other +powered components can also be used if greater precision is required. See also -------- -- :ref:`ADC note ` +- :ref:`ADC tutorial ` - `(Arduino) Tutorial: Analog Input Pins `_ .. include:: cc-attribution.txt diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst new file mode 100644 index 0000000..367adbb --- /dev/null +++ b/source/lang/api/board-values.rst @@ -0,0 +1,155 @@ +.. _lang-board-values: + +Board-Specific Constants +======================== + +There are a number of board-specific values: constants or variables +which are different depending on which LeafLabs board you have. + +This page lists and documents the board-specific values. You should +use these when appropriate in your own programs. This will help make +it easier to share your code with other people who have different +boards. Some example usages are given :ref:`below +`. + +.. contents:: Contents + :local: + +Constants +--------- + +- ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on + your board. + +.. _lang-board-values-but: + +- ``BOARD_BUTTON_PIN``: Pin connected to the built-in button (labeled + "BUT" on your board's silkscreen). + +.. _lang-board-values-led: + +- ``BOARD_LED_PIN``: Pin connected to the built-in LED. + +- ``BOARD_NR_GPIO_PINS``: Total number of :ref:`GPIO pins ` that + are broken out to headers. Some of these might already be connected + to external hardware (like the built-in LED and button). To find + out if a pin is in use, see :ref:`boardUsesPin() + ` (and also :ref:`boardUsedPins + `). + +.. _lang-board-values-nr-pwm-pins: + +- ``BOARD_NR_PWM_PINS``: Total *number* of GPIO pins that can be used + for :ref:`PWM `. The actual *pins* that can do PWM are in the + :ref:`boardPWMPins ` array. + +.. _lang-board-values-nr-adc-pins: + +- ``BOARD_NR_ADC_PINS``: Total number of GPIO pins that can be used + for :ref:`analog-to-digital conversion `. The actual pins that + can do ADC conversion are in the :ref:`boardADCPins + ` array. + +.. _lang-board-values-nr-used-pins: + +- ``BOARD_NR_USED_PINS``: Total number of GPIO pins that are already + connected to some external hardware (like a built-in LED) on the + board. The actual pins that that are already used are in the + :ref:`boardUsedPins ` array. To see if + a pin is already in use, use the :ref:`boardUsesPin() + ` function. + +.. _lang-board-values-usart: + +- USART (serial port) related constants: + + * ``BOARD_USART1_TX_PIN``, ``BOARD_USART2_TX_PIN``, ``BOARD_USART3_TX_PIN``: + TX pins for the 3 USARTS. + + * ``BOARD_USART1_RX_PIN``, ``BOARD_USART2_RX_PIN``, ``BOARD_USART3_RX_PIN``: + RX pins for the 3 USARTS. + + * ``BOARD_UART4_TX_PIN``, ``BOARD_UART5_TX_PIN``: TX pins for + UARTs 4 and 5 (high-density boards like Maple Native only). + + * ``BOARD_UART4_RX_PIN``, ``BOARD_UART5_RX_PIN``: RX pins for + UARTs 4 and 5 (high-density boards like Maple Native only). + + * ``BOARD_NR_USARTS``: Number of serial ports on the board. This + number includes UARTs 4 and 5 if they are available. + +.. _lang-board-values-pwm-pins: +.. _lang-board-values-adc-pins: +.. _lang-board-values-used-pins: + +Pin Arrays +---------- + +Some :ref:`arrays ` of pin numbers are available which you +can use to find out certain important information about a given pin. + +.. TODO add links to the board-specific hardware information on what +.. are in these arrays + +- ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM + ` output, using :ref:`pwmWrite() `. The total + number of these pins is :ref:`BOARD_NR_PWM_PINS + `. + +- ``boardADCPins``: Pin numbers of each pin capable of :ref:`ADC + ` conversion, using :ref:`analogRead() `. The + total number of these pins is :ref:`BOARD_NR_ADC_PINS + `. + +- ``boardUsedPins``: Pin numbers of each pin that, by default, is used + for some special purpose by the board. The total number of these + pins is :ref:`BOARD_NR_USED_PINS `. + To check if a pin is used for a special purpose, use + :ref:`boardUsesPin() `. + +.. _lang-board-values-examples: + +Examples +-------- + +:ref:`BOARD_LED_PIN ` On the Maple, the +built-in LED is connected to pin 13. On the Maple Mini, however, it +is connected to pin 33. You can write a "blinky" program that works +on all LeafLabs boards using ``BOARD_LED_PIN`` and :ref:`toggleLED() +`:: + + void setup() { + pinMode(BOARD_LED_PIN, OUTPUT); + } + + void loop() { + toggleLED(); + delay(100); + } + +:ref:`BOARD_BUTTON_PIN `: Similarly, you can +write a single program that prints a message whenever the button is +pressed which will work on all LeafLabs boards using +``BOARD_BUTTON_PIN`` and :ref:`isButtonPressed() +`:: + + void setup() { + pinMode(BOARD_BUTTON_PIN, INPUT); + } + + void loop() { + if (isButtonPressed()) { + SerialUSB.println("You pressed the button!"); + } + } + +See Also +-------- + +- :ref:`lang-boardusespin` +- :ref:`lang-isbuttonpressed` +- :ref:`lang-waitforbuttonpress` +- :ref:`lang-pinmode` +- :ref:`lang-toggleled` +- :ref:`lang-analogread` +- :ref:`lang-pwmwrite` diff --git a/source/lang/api/boardusespin.rst b/source/lang/api/boardusespin.rst new file mode 100644 index 0000000..8dc4c64 --- /dev/null +++ b/source/lang/api/boardusespin.rst @@ -0,0 +1,27 @@ +.. highlight:: cpp + +.. _lang-boardusespin: + +boardUsesPin() +============== + +Each LeafLabs board connects some pins to external hardware. The most +important examples of this are the built-in LED and button. You can +check if a board uses a particular pin using this function. + +Library Documentation +--------------------- + +.. doxygenfunction:: boardUsesPin + +See Also +-------- + +- :ref:`Board-specific values ` +- :ref:`boardUsedPins ` +- :ref:`BOARD_LED_PIN ` +- :ref:`toggleLED() ` +- :ref:`BOARD_BUTTON_PIN ` +- :ref:`isButtonPressed() ` +- :ref:`waitForButtonPress() ` + diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst index 2e968e7..c5a7c0c 100644 --- a/source/lang/api/constants.rst +++ b/source/lang/api/constants.rst @@ -293,23 +293,16 @@ exponent indicators. Some examples are given in the following table: Board-Specific Constants ------------------------ -This section documents constants whose value might change across -different LeafLabs boards. You can use these constants to help ensure -that your code will be portable across different boards. +There are several :ref:`board-specific constants ` +whose value depends on which LeafLabs board you have. If you use +them, it will help make sure that your code will work well on all +LeafLabs boards, not just the one you have. This will make it much +easier to share your code with others. -.. TODO replace "upcoming" when Mini, Native come out - -.. _lang-constants-led: - -- ``BOARD_LED_PIN``: the number of the pin which connects to the - built-in LED. On the Maple, this is pin 13, but it's not guaranteed - to be the same in upcoming boards like the Maple Mini. - -.. _lang-constants-but: - -- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the - built-in button (labeled "BUT"). On the Maple, this is pin 38, but - it's not guaranteed to be the same in other boards. +For example, the pin number connected to the board's built-in LED is +different on the different boards, but the board-specific constant +:ref:`BOARD_LED_PIN ` will always be the +correct value for each board. See Also -------- @@ -325,5 +318,6 @@ See Also - :ref:`unsigned long long ` - :ref:`float ` - :ref:`double ` +- :ref:`Board-Specific Values ` .. include:: cc-attribution.txt diff --git a/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst index c7a630d..3f086ca 100644 --- a/source/lang/api/hardwaretimer.rst +++ b/source/lang/api/hardwaretimer.rst @@ -10,6 +10,12 @@ built-in timer peripherals. More information on these peripherals (including code examples) is available in the :ref:`timers reference `. +.. FIXME update HardwareTimer documentation after redoing it in terms +.. of the new timer interface. + +.. warning:: This class has been deprecated. It is not available in + the current build. + Library Documentation --------------------- diff --git a/source/lang/api/isbuttonpressed.rst b/source/lang/api/isbuttonpressed.rst index dbff0c9..8c350b9 100644 --- a/source/lang/api/isbuttonpressed.rst +++ b/source/lang/api/isbuttonpressed.rst @@ -4,7 +4,8 @@ isButtonPressed() ================= Check whether the board's built-in button (labeled BUT on the -silkscreen) is pressed. +silkscreen) is pressed. The pin number of the built-in button is +given by the constant ``BOARD_BUTTON_PIN``. Library Documentation --------------------- @@ -14,4 +15,6 @@ Library Documentation See Also -------- +- :ref:`Board-specific values ` +- :ref:`BOARD_BUTTON_PIN ` - :ref:`lang-waitforbuttonpress` diff --git a/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst index 9d50077..cea602b 100644 --- a/source/lang/api/pwmwrite.rst +++ b/source/lang/api/pwmwrite.rst @@ -11,6 +11,8 @@ pwmWrite(), the pin will output a steady square wave with the given duty cycle. You can change the duty cycle later by calling pwmWrite() again with the same pin and a different duty. +.. FIXME board-specific information + On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 27, and 28. diff --git a/source/lang/api/toggleled.rst b/source/lang/api/toggleled.rst index 0cc20c2..54a7d64 100644 --- a/source/lang/api/toggleled.rst +++ b/source/lang/api/toggleled.rst @@ -13,5 +13,5 @@ Library Documentation See Also -------- -- :ref:`BOARD_LED_PIN ` +- :ref:`BOARD_LED_PIN ` - :ref:`togglePin() ` diff --git a/source/lang/api/waitforbuttonpress.rst b/source/lang/api/waitforbuttonpress.rst index 34c5066..a5bd45c 100644 --- a/source/lang/api/waitforbuttonpress.rst +++ b/source/lang/api/waitforbuttonpress.rst @@ -14,4 +14,6 @@ Library Documentation See Also -------- +- :ref:`Board-specific values ` +- :ref:`BOARD_BUTTON_PIN ` - :ref:`lang-isbuttonpressed` diff --git a/source/language-index.rst b/source/language-index.rst index c949988..531e72c 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -26,13 +26,13 @@ programmers familiar with the Arduino language. | | | +----------------------------------+------------------------------------+ -.. Unimplemented in libmaple or not part of current release: +.. Unimplemented or not part of current release: .. toctree:: :hidden: + lang/unimplemented/tone.rst lang/unimplemented/notone.rst lang/unimplemented/pulsein.rst lang/unimplemented/stringclass.rst lang/unimplemented/stringobject.rst - lang/unimplemented/tone.rst diff --git a/source/language.rst b/source/language.rst index d340aec..ea841f5 100644 --- a/source/language.rst +++ b/source/language.rst @@ -10,6 +10,9 @@ The Maple can be programmed in the `Wiring `_ language, which is the same language used to program the `Arduino `_ boards. +.. TODO Wiring tutorial -- just describe setup()/loop(), then link to +.. some of the the bajillion external tutorials + C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the :ref:`arduino_c_for_c_hackers`. @@ -25,6 +28,21 @@ Maple Language Reference The following table summarizes the available core language features. A more exhaustive index is available at the :ref:`language-index`. +**Looking for something else?** + +- See the :ref:`libraries` for extra built-in libraries for dealing + with different kinds of hardware. + +.. FIXME mention Maple Native supports malloc(), free(), operator +.. new(), and operator delete(), when that is a true thing to say. + +- If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + ` used to compile your programs is configured to link + against `newlib `_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. + +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | | | | | @@ -40,13 +58,13 @@ A more exhaustive index is available at the :ref:`language-index`. | |* :ref:`true ` | |* :ref:`togglePin() ` | |* :ref:`for ` | :ref:`false ` | | | | |* :ref:`toggleLED() ` | -|* :ref:`switch/case ` |* :ref:`BOARD_LED_PIN ` | | | -| | :ref:`BOARD_BUTTON_PIN `|* :ref:`isButtonPressed() ` | -|* :ref:`while ` | | | -| |* :ref:`Constants |* :ref:`waitForButtonPress() | -|* :ref:`do...while ` | ` (:ref:`integers | ` | -| | `, :ref:`floating | | -|* :ref:`break ` | point `) |**Analog I/O** | +|* :ref:`switch/case ` |* :ref:`Constants | | +| | ` (:ref:`integers |* :ref:`isButtonPressed() ` | +|* :ref:`while ` | `, :ref:`floating | | +| | point `) |* :ref:`waitForButtonPress() | +|* :ref:`do...while ` | | ` | +| |* :ref:`Board-specific values | | +|* :ref:`break ` | ` |**Analog I/O** | | | | | |* :ref:`continue ` |**Data Types** |* :ref:`analogRead() ` | | | | | @@ -76,7 +94,7 @@ A more exhaustive index is available at the :ref:`language-index`. |**Arithmetic Operators** | ` | | | | |* :ref:`delayMicroseconds() | |* :ref:`= ` |* ``unsigned long`` (4 bytes), synonym for | ` | -| (assignment operator) | :ref:`unsigned int ` | | +| (assignment) | :ref:`unsigned int ` | | | | | | |* :ref:`+ ` (addition) |* :ref:`long long ` (8 bytes) |**Math** | | | | | @@ -153,13 +171,13 @@ A more exhaustive index is available at the :ref:`language-index`. | | | | |* :ref:`++ ` | |* :ref:`Serial ` | | (increment) | | | -| | |**Looking for something else?** | +| | | | |* :ref:`- - ` | | | -| (decrement) | | See the :ref:`libraries` page for interfacing with| -| | | particular types of hardware. Maple links | -|* :ref:`+= ` | | against `newlib `_ | -| (compound add) | | and allows the use of any of its functions; see | -| | | its documentation for more details. | +| (decrement) | | | +| | | | +|* :ref:`+= ` | | | +| (compound add) | | | +| | | | |* :ref:`-= | | | | ` (compound | | | | subtract) | | | diff --git a/source/libmaple.rst b/source/libmaple.rst index 8cc39a3..9faca03 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -30,12 +30,12 @@ wrappers and code to imitate the Arduino programming library. git clone git://github.com/leaflabs/libmaple.git -**Table of contents:** +.. TODO after finishing refactor: create, style, and host a pure +.. Doxygen libmaple reference docs. This implies determining a stable +.. API. -.. toctree:: - :maxdepth: 2 +.. **Table of contents:** - Guide to using GCC's ARM target +.. .. toctree:: +.. :maxdepth: 2 -.. TODO LATER create, style, and host a pure Doxygen libmaple -.. reference docs. This implies determining a stable API. -- cgit v1.2.3 From d70af49f021da7da497b45b18c4fea73cfbd3cb7 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 6 Apr 2011 13:57:30 -0400 Subject: USART refactor. --- source/lang/api/serial.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst index 58002e3..29c70a2 100644 --- a/source/lang/api/serial.rst +++ b/source/lang/api/serial.rst @@ -12,6 +12,9 @@ devices. Introduction ------------ +.. FIXME remove Maple-specific documentation +.. FIXME Serial4, Serial5 updates for high-density devices + The Maple has three serial ports (also known as a UARTs or USARTs): ``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the pins summarized in the following table: @@ -221,7 +224,7 @@ Arduino Compatibility Note Unlike the Arduino, none of the Maple's serial ports is connected to the USB port on the Maple board (for that, use :ref:`SerialUSB `). Thus, to use these pins to communicate with your -personal computer, you will need an additional USB-to-serial adaptor. +personal computer, you will need an additional USB-to-serial adapter. .. TODO LATER port these examples over -- cgit v1.2.3 From 5d17fbe13cc6baeeb1f54c925a0c67ae60e5f23e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 8 Apr 2011 15:56:14 -0400 Subject: Adding CLOCK_SPEED_MHZ and CLOCK_SPEED_HZ as derived board-specific values. --- source/lang/api/board-values.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst index 367adbb..d6d78f6 100644 --- a/source/lang/api/board-values.rst +++ b/source/lang/api/board-values.rst @@ -18,6 +18,12 @@ boards. Some example usages are given :ref:`below Constants --------- +- ``CLOCK_SPEED_MHZ``: Clock speed of your board, in megahertz + (MHz). This is the same as ``CYCLES_PER_MICROSECOND``. + +- ``CLOCK_SPEED_HZ``: Clock speed of your board, in hertz (Hz). This + is the same as ``CLOCK_SPEED_MHZ * 1000000``. + - ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on your board. -- cgit v1.2.3 From 92ab837c45f28fe33031e0e01c769ff096bb5cb8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 8 Apr 2011 18:49:50 -0400 Subject: Documentation improvements. Simplified and clarified "flashing your own bootloader" documentation. Also made Windows 7 IDE workaround link directly to the forum post with the workaround, instead of the start of the thread. --- source/bootloader.rst | 113 ++++++++++++++++++++++++++++--------------- source/maple-ide-install.rst | 4 +- 2 files changed, 75 insertions(+), 42 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index cfbf545..917a1b7 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -4,8 +4,6 @@ Maple Bootloader(s) ===================== -.. TODO: add a section on flashing your own bootloader - The firmware which allows the Maple to be reprogrammed via a USB connection. Every Maple board comes programmed with this by default, and it is not overwritten by regular programs (it lives lower in the @@ -585,20 +583,25 @@ DFU pipe and bringing up the USB serial port. Flashing A Custom Bootloader ---------------------------- -The STM32 microprocessor on the Maple comes with a built-in hardware +.. warning:: This section is for users who want to put a fresh or + custom bootloader on their board. It's possible to make a mistake + in this process and e.g. render your Maple unable to communicate + with the IDE. Know what you're doing, and proceed with caution. + +The STM32 microprocessor on the Maple comes with a built-in serial bootloader that can be used to flash a new (software) bootloader onto -the chip. This section describes how to go about this, using a Maple -Rev 3 or higher (if you have a Maple Rev 1; you don't have a BUT -button, and won't be able to follow these directions. A workaround is -detailed in `this forum posting -`_). - -.. warning:: This section is directed at users wishing to write a - custom bootloader for the Maple, or update their bootloader to a - more recent version. It's generally not necessary to do so, and it - is possible to make a mistake and e.g. render your Maple unable to - communicate with the IDE. Know what you're doing, and proceed with - caution. +the chip. While the Maple bootloader is just a program, the built-in +serial bootloader is part of the STM32 hardware, so it's always +available. + +This means that you can **always** follow these instructions to put a +new bootloader program on your board; it **doesn't matter** if there's +already a copy of the Maple bootloader on it or not. + +This section applies to Maple Rev 3 or higher. If you have a Maple +Rev 1; you don't have a BUT button, and won't be able to follow these +directions. A workaround is detailed in `this forum posting +`_. .. highlight:: sh @@ -615,10 +618,20 @@ In order to follow these instructions, you will need: **Step 1: Obtain a bootloader binary**. The first thing you'll need to do is to compile your bootloader binary. Note that an ASCII -representation of the binary, such as the Intel .hex format, will not -suffice. For example, you can run (on a :ref:`suitably configured -system `) the following to obtain a binary of the -bootloader currently used on the Maple:: +representation of the binary, such as the Intel .hex format, won't +work. + +.. FIXME [Mini, Native] links to precompiled bootloaders + +If you just want to flash the default Maple bootloader (the one that +was installed on your Maple when it arrived), we host a `pre-compiled +copy +`_, +which works on all Maple Revs. + +To obtain the latest development version, you can run (on a +:ref:`suitably configured system `) the following to +obtain a binary of the bootloader currently used on the Maple:: $ git checkout git://github.com/leaflabs/maple-bootloader.git $ cd maple-bootloader @@ -632,15 +645,20 @@ could use another Maple, an Arduino, etc. -- anything that allows your computer to communicate with the Maple you want to reprogram over a serial interface. +.. FIXME [Maple-specific values] + If you do use an FTDI breakout board, first make sure your Maple is disconnected from an external power source, be it battery, USB, or barrel jack. Then, connect the FTDI board's TX pin to ``Serial1``\ 's RX pin (pin 8), FTDI RX to ``Serial1`` TX (pin 7), FTDI ground to Maple's GND, and its 3.3V pin to Maple's Vin (use the Maple's -silkscreen for help locating these pins). At this point, you're ready -to plug the FTDI board into your computer (via USB). +silkscreen for help locating these pins). -The ``Serial1`` pins are documented :ref:`here `. +More information on ``Serial1`` is available :ref:`here +`. + +At this point, you're ready to plug the FTDI board into your computer +(via USB). **Step 3: Put your Maple into serial bootloader mode**. Do this by pressing the RESET button, then *while RESET is held down*, pressing @@ -648,35 +666,50 @@ and holding the BUT button. Next, *making sure to keep BUT held down*, release the RESET button and wait for a few seconds before releasing BUT. -**Step 4: Obtain stm32loader.py**. The -script ``stm32loader.py`` is provided with libmaple. If you have set -up the :ref:`Unix toolchain `, it is available in -libmaple/support/stm32loader.py. Otherwise, you can download it -directly from `github +**Step 4: Get stm32loader.py**. You can download it directly from +`libmaple's github page `_ -(click the link, then save the file somewhere on your system). +(click the link, then save the file somewhere on your system). If you +have set up the :ref:`Unix toolchain `, it's the file +libmaple/support/stm32loader.py. Flashing the new Bootloader ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -We'll use ``new-boot.bin``, ``ser-port``, and ``stm32loader.py`` to -respectively refer to the absolute paths to the bootloader binary -(from Step 1), the serial port device file or COMM port (from Steps 2 -and 3), and the stm32loader.py script. +We'll use ``maple_boot.bin`` as the path to the bootloader binary from +Step 1, and ``ser-port`` as the Maple's serial port device file or COM +port. + +* On **Linux**, ``ser-port`` will probably be something like + ``/dev/ttyUSB0``, although the exact number could be different (it + could be ``/dev/ttyUSB1``, ``/dev/ttyUSB2``, etc.). + +* On **OS X**, ``ser-port`` will probably look like + ``/dev/tty.usbserialXXXX``, where ``XXXX`` is some random string of + characters. + +* On **Windows**, ``ser-port`` will be something like ``COM1``, ``COM2``, etc. .. highlight:: sh -You can run :: +To upload a bootloader binary, run this command from the Unix shell:: + + python stm32loader.py -p ser-port -evw maple_boot.bin + +Or this command from the Windows command prompt:: + + python.exe stm32loader.py -p ser-port -evw maple_boot.bin - $ python stm32loader.py -h +You can also run the following to get usage information:: -to obtain usage information. The incantation for uploading a -bootloader binary ``new-bootloader.bin`` is :: + # Unix: + python stm32loader.py -h - $ python stm32loader.py -p ser-port -evw new-boot.bin + # Windows: + python.exe stm32loader.py -h If all goes well, you'll see a bunch of output, then "Verification OK". If something goes wrong, the `forum`_ is probably your best bet -for obtaining help, with IRC (irc.freenode.net, #leafblowers) being -another option. If all else fails, you can always `contact us -directly`_! +for obtaining help, with IRC (server irc.freenode.net, channel +#leafblowers) being another option. If all else fails, you can always +`contact us directly`_! diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 92d1a96..f439abe 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -65,8 +65,8 @@ some drivers. Sorry! changes in Windows 7 mean that you won't be able to install the IDE without disabling driver signing on your computer. We're working on resolving this situation. For now, `users on the forum have - reported some workarounds - `_. + reported a workaround + `_. First, install DFU drivers (for uploading code to your Maple) using the following steps. -- cgit v1.2.3 From a338622730388e440f30a1cacd58319be13b4e68 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 11 Apr 2011 23:46:28 -0400 Subject: Merging in changes from 0.0.9-maintenance. --- source/maple-ide-install.rst | 15 ++++++++++----- source/usb.rst | 5 ++++- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index f439abe..5c79d41 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -17,7 +17,8 @@ us directly`_\ ! Download -------- -Choose the correct version for your operating system: +The current release of the Maple IDE is version 0.0.9. Choose the +correct version for your operating system: .. list-table:: :widths: 15 30 50 @@ -28,15 +29,15 @@ Choose the correct version for your operating system: - IDE Package * - Windows - Tested on 32bit Windows XP - - `maple-ide-LATEST-windowsxp32.zip `_ (about 75mb) + - `maple-ide-0.0.9-windowsxp32.zip `_ (about 75mb) * - Linux - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) - - `maple-ide-LATEST-linux32.tgz `_ (about 30mb) + - `maple-ide-0.0.9-linux32.tgz `_ (about 30mb) - `maple-ide-LATEST-linux64.tgz `_ (about 30mb) + `maple-ide-0.0.9-linux64.tgz `_ (about 30mb) * - Mac OSX - Tested on Snow Leopard 10.6 (64bit and 32bit) - - `maple-ide-LATEST-macosx-10_6.dmg `_ (about 40mb) + - `maple-ide-0.0.9-macosx-10_6.dmg `_ (about 40mb) The package bundles together a compiler, an upload utility, a software library, and a simple GUI text editor. All this software is `free and @@ -46,6 +47,10 @@ open `_; we are grateful to the `Arduino `OpenMoko `_ developers, as well as many others, who allow us to reuse their software. +**Looking for something older?** `Source archives and binaries +`_ are available +for previously-released versions. + Installation ------------ diff --git a/source/usb.rst b/source/usb.rst index f502f31..0468618 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -34,7 +34,10 @@ second problem is the use of :ref:`perpetual bootloader mode Recommended Reading ------------------- -* `USB in a NutShell `_ overview from Beyond Logic +* `USB in a Nutshell `_, an overview from Beyond Logic +* `USB made simple `_, an illustrated series of articles on USB +* The `USB 2.0 Specification `_ (`direct link `_) +* `Embedded USB - a brief tutorial `_ * `Wikipedia article on Universal Serial Bus (USB) `_ * Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ * STMicro documentation for STM32F103RB microcontroller: -- cgit v1.2.3 From c99caea9992116cccf2d145a96a3ec189ef1068f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 12 Apr 2011 01:07:59 -0400 Subject: Reverting "Rewrote Print class." This reverts commit 8bd3cebbee62e2dd7e961b149cc8bb0e980eaf88. --- source/lang/api/serial.rst | 35 +++++++++++------------------------ source/lang/api/serialusb.rst | 35 +++++++++++------------------------ 2 files changed, 22 insertions(+), 48 deletions(-) diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst index 29c70a2..fadac34 100644 --- a/source/lang/api/serial.rst +++ b/source/lang/api/serial.rst @@ -116,34 +116,25 @@ means that you can use any of these functions on any of ``Serial1``, Print the argument's digits over the USART, in decimal format. -.. cpp:function:: HardwareSerial::print(long long n) +.. cpp:function:: HardwareSerial::print(long n) Print the argument's digits over the USART, in decimal format. Negative values will be prefixed with a ``'-'`` character. -.. cpp:function:: HardwareSerial::print(unsigned long long n) +.. cpp:function:: HardwareSerial::print(unsigned long n) Print the argument's digits over the USART, in decimal format. -.. _lang-serial-print-n-base: +.. cpp:function:: HardwareSerial::print(long n, int base) -.. cpp:function:: HardwareSerial::print(int n, int base) - - Print the digits of ``n`` over the USART, in base ``base``. The - ``base`` value 2 corresponds to binary, 8 to octal, 10 to decimal, - and 16 to hexadecimal (you can also use the symbolic constants - ``BIN``, ``OCT``, ``DEC``, ``HEX``). If ``base`` is 10, negative - values will be prefixed with a ``'-'`` character (otherwise, ``n`` - will be interpreted as an unsigned quantity). - -.. cpp:function:: HardwareSerial::print(long long n, int base) - - Same behavior as the above :ref:`print(int n, int base) - `, except with 64-bit values. + Print the digits of ``n`` over the USART, in base ``base`` (which + may be between 2 and 16). The ``base`` value 2 corresponds to + binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative + values will be prefixed with a ``'-'`` character. .. cpp:function:: HardwareSerial::print(double n) - Print ``n``, accurate to 6 digits after the decimal point. + Print ``n``, accurate to 2 digits after the decimal point. .. _lang-serial-println: @@ -167,19 +158,15 @@ means that you can use any of these functions on any of ``Serial1``, Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(long long n) +.. cpp:function:: HardwareSerial::println(long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(unsigned long long n) +.. cpp:function:: HardwareSerial::println(unsigned long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(int n, int base) - - Like ``print(n, b)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(long long n, int base) +.. cpp:function:: HardwareSerial::println(long n, int base) Like ``print(n, b)``, followed by ``"\r\n"``. diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst index 4ddfa4a..ee7146e 100644 --- a/source/lang/api/serialusb.rst +++ b/source/lang/api/serialusb.rst @@ -109,35 +109,26 @@ world!")``. Print the argument's digits over the USB connection, in decimal format. -.. cpp:function:: USBSerial::print(long long n) +.. cpp:function:: USBSerial::print(long n) Print the argument's digits over the USB connection, in decimal format. Negative values will be prefixed with a ``'-'`` character. -.. cpp:function:: USBSerial::print(unsigned long long n) +.. cpp:function:: USBSerial::print(unsigned long n) Print the argument's digits over the USB connection, in decimal format. -.. _lang-serial-print-n-base: +.. cpp:function:: USBSerial::print(long n, int base) -.. cpp:function:: USBSerial::print(int n, int base) - - Print the digits of ``n`` over USB, in base ``base``. The ``base`` - value 2 corresponds to binary, 8 to octal, 10 to decimal, and 16 to - hexadecimal (you can also use the symbolic constants ``BIN``, - ``OCT``, ``DEC``, ``HEX``). If ``base`` is 10, negative values - will be prefixed with a ``'-'`` character (otherwise, ``n`` will be - interpreted as an unsigned quantity). - -.. cpp:function:: HardwareSerial::print(long long n, int base) - - Same behavior as the above :ref:`print(int n, int base) - `, except with 64-bit values. + Print the digits of ``n`` over the USB connection, in base ``base`` + (which may be between 2 and 16). The ``base`` value 2 corresponds + to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. + Negative values will be prefixed with a ``'-'`` character. .. cpp:function:: USBSerial::print(double n) - Print ``n``, accurate to 6 digits after the decimal point. + Print ``n``, accurate to 2 digits after the decimal point. .. _lang-serialusb-println: @@ -161,19 +152,15 @@ world!")``. Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: USBSerial::println(long long n) +.. cpp:function:: USBSerial::println(long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: USBSerial::println(unsigned long long n) +.. cpp:function:: USBSerial::println(unsigned long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: USBSerial::println(int n, int base) - - Like ``print(n, b)``, followed by ``"\r\n"``. - -.. cpp:function:: USBSerial::println(long long n, int base) +.. cpp:function:: USBSerial::println(long n, int base) Like ``print(n, b)``, followed by ``"\r\n"``. -- cgit v1.2.3 From 2ff79160b43e52007fc227f37a1370406092b8e9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 14 Apr 2011 13:52:32 -0400 Subject: Moving external interrupts docs to "Hardware Peripherals" index section. --- source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index.rst b/source/index.rst index de71411..1d1a5be 100644 --- a/source/index.rst +++ b/source/index.rst @@ -34,7 +34,6 @@ Have fun! Libraries Arduino Compatibility libmaple - External Interrupts Bootloader Troubleshooting Known Problems @@ -48,6 +47,7 @@ Have fun! :maxdepth: 1 adc + external-interrupts gpio i2c jtag -- cgit v1.2.3 From f2c5d9959424f5e698768d289d0129f1f7b6d891 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 14 Apr 2011 16:00:39 -0400 Subject: Unix toolchain docs improvements. Folded information in the README about the library Makefile target into docs/source/unix-toolchain.rst. Added a pointer to the JTAG HOWTO page on the wiki. Made some other miscellaneous cleanups, updates and improvements. --- source/unix-toolchain.rst | 306 +++++++++++++++++++++++++--------------------- 1 file changed, 167 insertions(+), 139 deletions(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index d49b642..a173146 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -7,20 +7,21 @@ =========================== This is a tutorial for using the Maple with a standard Unix toolchain -(make, gcc, etc.). It's not necessary to do this in order to program -the Maple; you can always :ref:`install the Maple IDE +(``make``, ``gcc``, etc.). It's not necessary to do this in order to +program the Maple; you can always :ref:`install the Maple IDE ` instead. You'll need a Maple board, a Mini-B USB cable, a functional computer, -and root access to that computer. This guide assumes you've had -success with the IDE on your machine and that you are fairly -comfortable with the Unix command line; some previous experience with -editing your shell startup script (.bashrc, .tcshrc, etc.) and using -`make `_ is recommended. For -generic installation/setup issues, the :ref:`IDE installation -` and :ref:`troubleshooting` pages may be -helpful. If all else fails, try our `forum`_, or `contact us -directly`_\ ! +and root (or Administrator) access to that computer. This guide +assumes you've had success with the IDE on your machine and that you +are fairly comfortable with the Unix command line. Some previous +experience with editing your shell startup script (.bashrc, .tcshrc, +etc.) and using `GCC `_ and `make +`_ is recommended. + +For generic installation and setup issues, see the :ref:`IDE +installation ` and :ref:`troubleshooting` pages. If +all else fails, try our `forum`_, or `contact us directly`_\ ! We currently have instructions for 32- and 64-bit Linux and OS X Snow Leopard. If you're on another Unix platform, Windows, or an earlier @@ -54,36 +55,40 @@ First I'll give the commands to run, then explain:: $ sudo aptitude install build-essential git-core wget screen dfu-util \ openocd python python-serial -You'll want to install a bunch of developer "basics" like -:command:`make`, :command:`tar`, etc. A good catch-all for these -tools is the "build-essential" meta-package on most Debian platforms: -installing this fake package will pull in dozens of useful tools -without bogging your system down too much. ``git-core`` is the name of -the git package; `Git `_ is a distributed code -versioning system we use to track changes in our source -code. :command:`wget` is a simple tool to download files over http -from the command line, and is optional (you could pull in the required -downloads using a browser). :command:`screen` is a really cool virtual -terminal program; in the context of Maple, we use it to connect to -serial port devices. - -:command:`dfu-util` is a tool from the `OpenMoko`_ project that we use -to upload programs to the Maple over USB. +You'll want to install a bunch of developer "basics" like ``make``, +``tar``, etc. A good catch-all for these tools is the +``build-essential`` meta-package on most Debian platforms: installing +this fake package will pull in dozens of useful tools without bogging +your system down too much. + +`Git `_ is a distributed code versioning system +we use to track changes in our source code; ``git-core`` is the +corresponding package. + +``wget`` is a simple tool to download files over http from the command +line; installing it is optional (you could pull in the required +downloads using a browser). + +``screen`` is a screen manager; in the context of Maple, we use it to +connect to serial port devices. + +``dfu-util`` is a tool from the `OpenMoko`_ project that we use to +upload programs to the Maple over USB. .. _OpenMoko: http://openmoko.com/ -:command:`openocd` is a `JTAG +``openocd`` is a `JTAG `_ control program used in conjunction with an ARM JTAG device to do in circuit debugging (pause/resume program execution, upload and download code, -read out register status, etc). (optional) +read out register status, etc). It's also optional. Lastly, our reset script (which sends control signals over the USB-serial connection to restart and enter the bootloader) is written -in Python and requires the `PySerial -`_ library (the ``python-serial`` -package; this could also be installed with `easy_install -`_). +in `Python `_, and requires the `PySerial +`_ library available in the +``python-serial`` package. This can also be installed with +`easy_install `_. **2. Fetch libmaple and Compiler Toolchain** :: @@ -100,10 +105,10 @@ then download and extract the ARM compiler toolchain. The :file:`arm/bin/` directory will need to be added to ``PATH``; you can check that this worked by entering ``arm-none-`` and hitting tab -to auto-complete (bash should show a bunch of results). Regardless of -where you put the toolchain, make sure to preserve its internal -directory layout, as the binaries make relative path calls and -references. +to auto-complete (your shell should show a bunch of results). +Regardless of where you put the toolchain, make sure to preserve its +internal directory layout, as the binaries make relative path calls +and references. After you're done, you'll probably want to update your shell startup script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. @@ -118,12 +123,12 @@ From the libmaple directory, :: $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules $ sudo /etc/init.d/udev restart -As a security precaution on linux, unknown USB devices can only be -accessed by the superuser. This udev script identifies the Maple based -on its vendor and product IDs, mounts it to :file:`/dev/maple`, and -grants read/write permissions to the ``plugdev`` group. After -restarting :command:`udev` you'll need to fully unplug or power cycle -any Maples connected to the computer. +As a security precaution on Linux, unknown USB devices can only be +accessed by root. This udev script identifies the Maple based on its +vendor and product IDs, mounts it to :file:`/dev/maple`, and grants +read/write permissions to the ``plugdev`` group. After restarting +``udev`` you'll need to fully unplug or power cycle any Maples +connected to the computer. **So far, so good?** @@ -140,38 +145,40 @@ stated previously, this document assumes a general level of Unix aptitude on the part of the reader; if you're uncomfortable using Terminal (or if you don't know what that means), then you should probably stick with using the `Maple IDE -`_ to develop programs. +`_ to write programs. **1. Collect and Install Tools** -You will need the following tools\ [#fmacports]_ to get started: +You will need the following tools\ [#fpackman]_ to get started: 1. `XCode `_: If you're reading this, you've probably already got this. Provides - compilers and other basic tools of the trade. It's a free download, - but requires registration (gross, we know). + compilers and other basic tools of the trade. While XCode was once + free of charge, Apple has since begun charging for it; if you'd + rather not pay, you can probably get by with just a `make + `_ binary. 2. `Git `_: All of our code is tracked by a - distributed versioning system called git. A `Mac installer + distributed versioning system called Git. A `Mac installer `_ is available. - 3. :command:`dfu-util`: A tool from `OpenMoko`_ that we use to upload - programs to the Maple over USB. If you're feeling masochistic, there - are instructions for `building dfu-util from source + 3. ``dfu-util``: A tool from `OpenMoko`_ that we use to upload + programs to the Maple over USB. If you prefer to compile from + source, OpenMoko provides instructions for `building dfu-util `_. - However, if you've got better things to do, you can steal a dfu-util - binary from a program called `Openmoko Flasher + If you're in a hurry, you can steal a dfu-util binary from a program + called `Openmoko Flasher `_. To do this, first `download Openmoko Flasher `_, then copy - the .app into your :file:`/Applications` folder (or wherever you - like). Let's pretend you saved the .app to the directory + the OpenMoko application into your :file:`/Applications` folder (or + wherever you like). Let's pretend you saved the .app to the directory :file:`/Applications/OpenMoko Flasher.app` - Then the :command:`dfu-util` binary resides in + Then the ``dfu-util`` binary resides in :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` @@ -188,8 +195,9 @@ You will need the following tools\ [#fmacports]_ to get started: .app, but you're on your own. To make sure this worked, try plugging in your Maple, making sure - it's in bootloader mode (you can do this by pressing RESET, then - quickly pressing BUT and holding it for several seconds), then + it's in :ref:`perpetual bootloader mode + ` (do this by pressing RESET, + then quickly pressing BUT and holding it for several seconds), then running :: $ dfu-util -l @@ -212,8 +220,8 @@ You will need the following tools\ [#fmacports]_ to get started: $ python setup.py build $ sudo python setup.py install - The package is also available via :command:`easy_install`, so if - you're comfortable using that, you could also install it with :: + The package is also available via ``easy_install``, so if you're + comfortable using that, you could also install it with :: $ easy_install pyserial @@ -288,20 +296,20 @@ Woo! It worked. The ``dec`` field at the end gives the total program size in bytes. The long listing of object files above the ``Final Size`` helps to identify bloated code. As you write larger projects, you may find that they use too much space. If that happens, the -file-by-file listing will help you track down the fatties porking up -your program. +file-by-file listing will help you track down the culprits. .. _toolchain-upload: Upload a program ---------------- -Ok, let's blow away the little example program and upload the -interactive test session to your Maple. This will let you interact -textually with the Maple via USB-serial. If you're on Linux, then -before executing :command:`make install`, you'll want to have the udev -rules setup :ref:`as described above `. Plug in your Maple -using the mini-b USB cable; then run :: +Let's blow away the little example program and upload the interactive +test session to your Maple. This will let you interact with the Maple +over a :ref:`USB serial port `. If you're on Linux, then before +executing ``make install``, you'll want to have the udev rules setup +:ref:`as described above `. + +Plug in your Maple using the Mini-B USB cable; then run :: $ cd ~/libmaple $ cp examples/test-session.cpp main.cpp @@ -312,91 +320,106 @@ using the mini-b USB cable; then run :: A number of things can go wrong at this stage. Simple debugging steps include using :ref:`perpetual bootloader mode `, restarting the Maple a couple -times, :command:`make clean`, etc. If nothing works, the `forum`_ is -your friend. +times, ``make clean``, etc. If nothing works, the `forum`_ is your +friend. .. _toolchain-serialusb: -Communicate over USB-serial interface +Communicate over USB-Serial interface ------------------------------------- -Okay, now that we've flashed the interactive test session to the -Maple, let's test it out. The device for the maple should look -something like :file:`/dev/ttyACMXXX` on Linux or -:file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly -different name on your system. To open up a session, run :: +Now let's try out the interactive test session. The serial port +device file should look something like :file:`/dev/ttyACMXXX` on Linux +or :file:`/dev/tty.usbmodemXXX` on OS X, but ``XXX`` will vary +depending on your system. Try using one of these to find out which it +is:: + + # Linux + $ ls /dev/ttyACM* + + # OS X + $ ls /dev/tty.usbmodem* + +To open up a session, run :: $ screen /dev/ttyXXX -If the interactive test program built and uploaded correctly, you -should be able to connect without any errors reported by -:command:`screen`. Type ``h`` or hit the space bar to get a response; -there are a number of commands which demonstrate Maple peripheral -features. As of October 2010, the HardwareSerial library is blocking, -so using any commands which would write to the USART Serial ports will -cause the program to hang. To exit the screen session, type :kbd:`C-a -C-\\` (control-a, followed by control-backslash) on Mac, or :kbd:`C-a -k` (control-a k) on Linux, and type ``y`` when prompted if you're -sure. +If the interactive test program built and uploaded correctly, +``screen`` won't report any errors, and will present you an empty +terminal. Your board is now waiting for you to send it a command. +Type ``h`` to print a list of commands which demonstrate various +features; type any command's letter to run it. + +To exit the screen session, type :kbd:`C-a C-\\` (control-a, followed +by control-backslash) on Mac, or :kbd:`C-a k` (control-a k) on Linux, +and type ``y`` when prompted if you're sure. .. note:: - Using :command:`screen` in this way sometimes messes up your - terminal session on OS X. If your shell starts acting up after you - exit screen, you should be able to fix it with :: + Using ``screen`` sometimes messes up your terminal session on OS X. + If your shell starts acting funny after you exit ``screen``, you + should be able to fix it with :: $ reset && clear + If that doesn't work, just close the Terminal window and open up a + new one. + .. _toolchain-projects: Starting your own projects -------------------------- -.. TODO fix the build-targets.mk mess, note the "library" target - So everything worked, and you want to start your own project? Great! -It's easy. Just set the environment variable ``LIB_MAPLE_HOME`` in -your shell startup script to point to the libmaple repository you -cloned (this tutorial assumes you put it in :file:`~/libmaple`). For -example, if you use bash as your shell, just put this line in your -:file:`~/.bashrc` or :file:`~/.bash_profile`:: - - export LIB_MAPLE_HOME=~/libmaple - -Now, in order to start your own projects, just grab a copy of the -:file:`Makefile` and skeleton :file:`main.cpp` we provided in the -libmaple repository, and you're good to go:: - - $ cd - $ mkdir my-awesome-project - $ cp ~/libmaple/Makefile ~/libmaple/build-targets.mk my-awesome-project - $ cp ~/libmaple/main.cpp.example my-awesome-project/main.cpp - -(TEMPORARY: The file :file:`build-targets.mk` is where the rule to -build the object file for :file:`main.cpp` lives. If you have multiple -source files, you'll probably need to look at it and edit as -appropriate. We're sorry about that and will update the Makefile -structure later to remove this pain point.) Then hack away! You can -:command:`make`, :command:`make clean`, and :command:`make install` -from your new directory :file:`my-awesome-project` just like you did -in the libmaple repository. - -.. note:: - - We update the libmaple repository fairly frequently with bugfixes - and other improvements. In order get access to these in your local - copy of the repository, you should periodically update it with:: - - $ cd $LIB_MAPLE_HOME - $ git pull - - The `commits page - `_ for the - github repository is a good place to watch for bleeding-edge - updates; our `blog `_ is the place to - watch for major releases. We keep releases of libmaple and the - Maple IDE in lockstep, so any IDE updates will have corresponding - library updates. +There are two ways to go about it. + +If your project is small, all you have to do is replace +:file:`~/libmaple/main.cpp` with your own code, and you're free to use +``make`` and ``make install`` in the same way you did when you first +:ref:`uploaded a program `. + +If you have a more complicated project, with its own Makefile and +multiple source files, or if you're using an IDE that creates its own +Makefile, you'll probably want to load libmaple from an archive (a +build-time library, not a DLL). + +To create an archive, use the ``library`` Makefile target:: + + $ cd ~/libmaple + $ make library + +This will produce a build-time library in the file +:file:`~/libmaple/build/libmaple.a`. To use it, make sure that you +link against that library, and that the libmaple sources are in your +include path. + +At a minimum, your include path should contain the directories +:file:`~/libmaple/libmaple` and :file:`~/libmaple/wirish/`. If you +want to use one of the officially supported :ref:`libraries +`, those live under :file:`~/libmaple/libraries/`. The +main include file for the Wirish library is +:file:`~/libmaple/wirish/wirish.h`. + +Getting Updates +--------------- + +We update libmaple fairly frequently with bugfixes and other +improvements. In order get access to these in your local copy of +the repository, you should periodically update it with:: + + $ cd ~/libmaple + $ git pull + +We keep releases of libmaple and the Maple IDE in lockstep, so any +IDE updates will have corresponding library updates. Our `blog +`_ is the place to watch for major +releases; an `RSS feed `_ is +available. + +You can sign up for a free `Github `_ +account and `watch libmaple +`_ to receive +notifications about bleeding-edge development. .. _toolchain-openocd: @@ -405,20 +428,25 @@ Debug with OpenOCD TODO. For now see `this great guide `_ from fun-tech.se, and -the ``jtag`` Makefile target. +the ``jtag`` Makefile target. There is also a `JTAG How-To +`_ page on +our `wiki `_ which you may find useful. .. _toolchain-exuberantly: Go forth exuberantly! --------------------- -Let us know what you come up with! Use #leaflabs on Twitter, post in -the `forum`_, track us down in the real world, whatever. We love -projects! +Let us know what you come up with! Use #leaflabs on `Twitter +`_, post in the `forum`_, join the the +#leafblowers IRC channel on `freenode +`_, whatever. We love projects! .. rubric:: Footnotes -.. [#fmacports] Some of these software packages might be available on - `MacPorts `_. The author had some bad +.. [#fpackman] Some of these software packages might be available on + `MacPorts `_ or `Homebrew + `_. The author had some bad experiences with MacPorts a few years ago, though, and hasn't - touched it since. Of course, your mileage may vary. + touched a package manager on OS X since. Of course, your mileage + may vary. -- cgit v1.2.3 From deed4a2f0a96dc2ea80a278ac1a9ff9c72ce788a Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 25 Apr 2011 16:07:38 -0400 Subject: 0.0.10 documentation checkpoint. Merging in the standalone refactor docs, etc. The individual libmaple API pages are going to need to get redone. --- Doxyfile | 7 +- source/_static/img/libmaple-screenshot-small.png | Bin 38023 -> 0 bytes source/adc.rst | 7 +- source/arduino-compatibility.rst | 270 +++++++++++++++ source/arm-gcc.rst | 2 +- source/bootloader.rst | 4 +- source/compatibility.rst | 270 --------------- source/errata.rst | 140 -------- source/gpio.rst | 2 +- source/hardware/maple.rst | 200 ++++++++++- source/i2c.rst | 27 +- source/index.rst | 22 +- source/lang/cpp/arithmetic.rst | 5 +- source/language-index.rst | 3 + source/language.rst | 77 +++-- source/libmaple.rst | 64 ++-- source/libmaple/api/adc.rst | 12 + source/libmaple/api/bitband.rst | 12 + source/libmaple/api/bkp.rst | 12 + source/libmaple/api/dac.rst | 12 + source/libmaple/api/delay.rst | 12 + source/libmaple/api/dma.rst | 12 + source/libmaple/api/exti.rst | 12 + source/libmaple/api/flash.rst | 12 + source/libmaple/api/fsmc.rst | 12 + source/libmaple/api/gpio.rst | 12 + source/libmaple/api/i2c.rst | 12 + source/libmaple/api/iwdg.rst | 12 + source/libmaple/api/libmaple.rst | 12 + source/libmaple/api/libmaple_types.rst | 12 + source/libmaple/api/nvic.rst | 12 + source/libmaple/api/pwr.rst | 12 + source/libmaple/api/rcc.rst | 12 + source/libmaple/api/ring_buffer.rst | 12 + source/libmaple/api/scb.rst | 12 + source/libmaple/api/spi.rst | 12 + source/libmaple/api/stm32.rst | 12 + source/libmaple/api/systick.rst | 12 + source/libmaple/api/timer.rst | 12 + source/libmaple/api/usart.rst | 12 + source/libmaple/api/util.rst | 12 + source/libmaple/apis.rst | 14 + source/libmaple/coding-standard.rst | 412 +++++++++++++++++++++++ source/libmaple/contributing.rst | 113 +++++++ source/libmaple/overview.rst | 342 +++++++++++++++++++ source/maple-ide-install.rst | 4 +- source/pwm.rst | 2 +- source/specs.rst | 29 -- source/troubleshooting.rst | 14 +- source/unix-toolchain.rst | 22 +- source/usb.rst | 2 +- 51 files changed, 1762 insertions(+), 592 deletions(-) delete mode 100644 source/_static/img/libmaple-screenshot-small.png create mode 100644 source/arduino-compatibility.rst delete mode 100644 source/compatibility.rst delete mode 100644 source/errata.rst create mode 100644 source/libmaple/api/adc.rst create mode 100644 source/libmaple/api/bitband.rst create mode 100644 source/libmaple/api/bkp.rst create mode 100644 source/libmaple/api/dac.rst create mode 100644 source/libmaple/api/delay.rst create mode 100644 source/libmaple/api/dma.rst create mode 100644 source/libmaple/api/exti.rst create mode 100644 source/libmaple/api/flash.rst create mode 100644 source/libmaple/api/fsmc.rst create mode 100644 source/libmaple/api/gpio.rst create mode 100644 source/libmaple/api/i2c.rst create mode 100644 source/libmaple/api/iwdg.rst create mode 100644 source/libmaple/api/libmaple.rst create mode 100644 source/libmaple/api/libmaple_types.rst create mode 100644 source/libmaple/api/nvic.rst create mode 100644 source/libmaple/api/pwr.rst create mode 100644 source/libmaple/api/rcc.rst create mode 100644 source/libmaple/api/ring_buffer.rst create mode 100644 source/libmaple/api/scb.rst create mode 100644 source/libmaple/api/spi.rst create mode 100644 source/libmaple/api/stm32.rst create mode 100644 source/libmaple/api/systick.rst create mode 100644 source/libmaple/api/timer.rst create mode 100644 source/libmaple/api/usart.rst create mode 100644 source/libmaple/api/util.rst create mode 100644 source/libmaple/apis.rst create mode 100644 source/libmaple/coding-standard.rst create mode 100644 source/libmaple/contributing.rst create mode 100644 source/libmaple/overview.rst delete mode 100644 source/specs.rst diff --git a/Doxyfile b/Doxyfile index 9bf02fc..5fbb079 100644 --- a/Doxyfile +++ b/Doxyfile @@ -608,7 +608,7 @@ INPUT_ENCODING = UTF-8 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 -FILE_PATTERNS = *.h +FILE_PATTERNS = *.h *.c # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. @@ -1372,7 +1372,10 @@ INCLUDE_FILE_PATTERNS = # instead of the = operator. PREDEFINED = __attribute__()= \ - __cplusplus + __cplusplus \ + STM32_MEDIUM_DENSITY + STM32_HIGH_DENSITY + STM32_XL_DENSITY # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/source/_static/img/libmaple-screenshot-small.png b/source/_static/img/libmaple-screenshot-small.png deleted file mode 100644 index f2be783..0000000 Binary files a/source/_static/img/libmaple-screenshot-small.png and /dev/null differ diff --git a/source/adc.rst b/source/adc.rst index 6bbbac2..b943808 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -71,11 +71,10 @@ Recommended Reading ------------------- * `Wikipedia article on Analog-to-digital converter `_ + * `Arduino Analog Input Tutorial `_ -* STMicro documentation for STM32F103RB microcontroller: - * `All `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) +* STMicro documentation: + * `Application Note on ADC Modes (pdf) `_ * `Application Note on ADC Oversampling (pdf) `_ diff --git a/source/arduino-compatibility.rst b/source/arduino-compatibility.rst new file mode 100644 index 0000000..e6852a0 --- /dev/null +++ b/source/arduino-compatibility.rst @@ -0,0 +1,270 @@ +.. highlight:: cpp + +.. _arduino-compatibility: + +============================= + Maple-Arduino Compatibility +============================= + +.. contents:: Contents + :local: + +Overview +-------- + +The biggest difference between the Maple and most Arduino boards is +that the Maple uses a 32-bit ARM Cortex-M3 architecture chip, while +the Arduinos have 8-bit Atmel AVR chips. The different instruction set +means that machine code (which makes up executable binary program) is +incompatible between the two, and a different compiler (actually just +a different version of `gcc `_) is required. + +The compiler for the regular Arduino IDE is the popular `avr-gcc +`_ package; the compiler for the +Maple version of the IDE is CodeSourcery's edition of gcc for the ARM +EABI target (:command:`arm-non-eabi-gcc`). A (preliminary) reference +on :ref:`using arm-none-eabi-gcc ` is available. + +The bitwidth of the processor means that the Maple can process 32-bit +operations (like adding two 32-bit integers) in a single instruction, +while an Arduino processor would have to split up large operations +into several smaller ones. In a lot of cases 8-bit operations are +plenty (integers 0-255, single characters of text, etc.), but if +you're dealing with higher resolution data, the speed up could be +significant. + +A trade-off is that code could be larger as well; program instructions +and memory locations can be up to 32 bits each. However, removal of +extra instructions and fancy packing together of simple instructions +means that programs aren't much larger (or are even smaller). + +Header Numbering and Incompatibilities +-------------------------------------- + +.. FIXME [Maple-specific values] + +The numbering of headers is different; on the Maple each GPIO has a +unique number: 0, 1, 2, all the way up to 37 (actually, there are +:ref:`a few more `...). On the Arduino, the analog pins are +numbered separately (A0-A5) from the digital pins (D0\ -D13). + +The incompatible hardware differences are: + +* :ref:`I2C ` **port**: on most Arduinos, the |i2c| port is Analog + Input 4 (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 + is D5 (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 + (SDA). + + It should be possible to skywire, sacrificing signal quality (due to + increased capacitance). Alternatively, |i2c| can be bit-banged + reasonably well in software. This peripheral could potentially be + rerouted internally, but we haven't looked into it. + +* :ref:`PWM ` **on D10**: all the other standard Arduino PWM + headers have PWM functionality on the Maple (D2,D3,D6,D9,D11), but + not D10. + +* **No External Voltage Reference**: The Arduino has an AREF pin which + allows the use of an external ADC voltage reference; the Maple has + an extra GPIO pin (D14) with PWM capability in this spot, and does + not allow an external voltage reference to be configured. + +* **EEPROM**: the Maple does not have any internal EEPROM. This + functionality can be emulated with regular persistent flash memory, + or with an external EEPROM chip. + +* **ISP Programming**: the Maple does not use an ISP/ICSP bus for + debugging; it uses :ref:`JTAG `. + + +Software Language/Library Changes +--------------------------------- + +With :ref:`a few exceptions `, the entire +Wiring/Arduino language is supported. However, there are some subtle +differences, most of which are improvements: + +* **32-bit integers**: many standard functions either expect or return + full 32-bit (4 byte) integer values instead of the regular 16-bit (2 + byte) Arduino values. + +* **64-bit doubles**: The :ref:`double ` type is a full + double-precision floating point type on the Maple; it is a + single-precision floating point value on the Arduino. + +* :ref:`pinMode() ` **types**: any :ref:`GPIO ` + (including analog pins) can be configured into one of the following + modes with a single call to ``pinMode()``: ``OUTPUT``, + ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``, + ``INPUT_PULLDOWN``. Additionally, the PWM pins (labeled "PWM" on the + silkscreen) can be configured in ``PWM`` and ``PWM_OPEN_DRAIN`` + modes, and the analog input pins (labeled "AIN") can be configured + in ``INPUT_ANALOG`` mode. See the :ref:`GPIO documentation ` + for more information. + +* :ref:`Serial port ` **syntax**: like the `Arduino Mega + `_, the Maple has + multiple :ref:`USART ports `. By default, ``Serial`` + is not mapped to any of them. Use ``Serial1`` through ``Serial3`` + instead. + +* **16-bit** :ref:`PWM `: Arduino boards support 8-bit PWM, which + means that calls to :ref:`analogWrite() ` take + values between 0 (always off) and 255 (always on). The Maple + supports 16-bit PWM, so the corresponding values should be between 0 + (always off) and 65535 (always on). + +* **12-bit** :ref:`ADC `: Arduino boards support 10-bit ADC, which + means that calls to :ref:`analogRead() ` will + return values between 0 and 1023. The Maple supports 12-bit ADC, so + the same call will instead return values between 0 and 4095. + +Shield and Device Compatibility +------------------------------- + +.. list-table:: + :header-rows: 1 + + * - Shield/Device + - Compatible? + - Notes + + * - Ethernet shield + - Yes! + - Tested; no library yet + + * - WiFi Shield + - Yes! + - Tested; preliminary library support + + * - MIDI shield + - Yes! + - Tested; no library yet + + * - XBee shield + - Unknown + - + + * - Bluetooth shield + - Unknown + - Some Bluetooth <-> UART boards have been tested and are known + to work. + + * - Cellular shield + - Unknown + - + +Library Porting Status +---------------------- + +The state of currently ported Arduino libraries is the +:ref:`libraries`. + +.. TODO Update as libraries are ported. + +.. list-table:: + :header-rows: 1 + + + * - Library + - Ported? + - Notes + + * - Wire + - Preliminary + - In progress; see :ref:`library reference `. + + * - LiquidCrystal + - **Yes** + - :ref:`Included since IDE 0.0.7 ` + + * - Ethernet + - Not yet + - Planned + + * - EEPROM + - (Unsupported) third-party emulation + - The Maple doesn't have EEPROM; it uses flash instead. There is + an `EEPROM emulation library + `_ by + `x893 `_, but we haven't tested it. + + * - Firmata + - Not yet + - Planned + + * - Matrix + - Not yet + - Planned + + * - Servo + - **Yes** + - :ref:`Included since IDE 0.0.9 ` + + * - SoftwareSerial + - Not yet + - Planned + + * - Sprite + - Not yet + - Planned + + * - Stepper + - Not yet + - Planned + +Sketch and Library Porting HOWTO +-------------------------------- + +In addition to the suggestions in this section, you may find many of +the individual :ref:`language reference ` pages useful. As +appropriate, these have "Arduino Compatibility" sections; one good +example is the :ref:`analogWrite() ` +function. + +- Check the hardware and header differences above, and see if your + project or shield needs to be modified (eg, add 3.3V level + converters or reroute PWM to header D10). + +- Check for ported library functionality. We intend to port all of the + core and popular libraries (like Wire, Ethernet, and the LCD screen + driver), but this task is not yet finished. (:ref:`Patches are + welcome! `). + +- Check for peripheral conflicts; changing the configuration of timers + and bus speeds for a feature on one header may impact all the + features on that hardware "port". For example, changing the timer + prescaler to do long PWM pulses could impact |i2c| communications on + nearby headers. + +- Rewrite any low-level code. This could potentially be very + difficult, but hopefully you've used the Arduino libraries to + abstract away the registers and other hardware-specific + details. Your sketch probably doesn't have any low-level code; a + library which wraps a particular peripheral very well may. Some + help is available in the :ref:`arm-gcc` reference. + +- Redeclare variable sizes if necessary: generics like ``int`` will + probably work unless you depend on side-effects like rollover. + +- Check every ``pinMode()``: the Maple has more modes for GPIO + pins. For example, make sure to set analog pins to ``INPUT_ANALOG`` + before reading and PWM pins to ``PWM`` before writing. The full set + of pin modes is documented in the :ref:`lang-pinmode` reference. + +- Modify PWM writes: ``pinMode()`` must be set to ``PWM``, the + frequency of the PWM pulse configured, and the duty cycle written + with up to 16-bit resolution. + +- Modify ADC reads: :ref:`lang-analogread` takes the full pin number + (not 0-5) and returns a full 12-bit reading. The ADC pin must have + its ``pinMode()`` set to ``INPUT_ANALOG``. + +- Possibly convert all Serial-over-USB communications to use + :ref:`lang-serialusb` instead of a USART :ref:`serial port + `. The Maple has a dedicated USB port which is not + connected to the USART TX/RX pins in any way. + +- Check timing: Maple clock cycles are just 13.9 nanoseconds, though + the peripheral bus speeds (which limit GPIO output) are clocked + slower. diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 7ecb5d4..e97bb2f 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -5,7 +5,7 @@ GCC for Maple ============= This document provides notes on using of ``arm-none-eabi-gcc``, the -`CodeSourcery `_ version of the GNU `GCC +`CodeSourcery `_ version of the GNU `GCC `_ compilers used for the Maple boards. It is not intended as a reference manual for GCC; such manuals are available `elsewhere `_. diff --git a/source/bootloader.rst b/source/bootloader.rst index 917a1b7..85b2674 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -13,7 +13,7 @@ Flash memory and only runs when the chip is reset). git clone git://github.com/leaflabs/maple-bootloader.git -**Visit the github development project**: http://github.com/leaflabs/maple-bootloader +**Visit the github development project**: https://github.com/leaflabs/maple-bootloader .. contents:: Contents :local: @@ -34,7 +34,7 @@ likely only interesting to a few. If you just want to get the rough idea, skim this article. If you want to start hacking on the bootloader, get in touch with us to get even more info on how this all works. And finally, you can always `check out the code at github -`_! +`_! Arduino ------- diff --git a/source/compatibility.rst b/source/compatibility.rst deleted file mode 100644 index eb28ad2..0000000 --- a/source/compatibility.rst +++ /dev/null @@ -1,270 +0,0 @@ -.. highlight:: cpp - -.. _compatibility: - -============================= - Maple-Arduino Compatibility -============================= - -.. contents:: Contents - :local: - -Overview --------- - -The biggest difference between the Maple and most Arduino boards is -that the Maple uses a 32-bit ARM Cortex-M3 architecture chip, while -the Arduinos have 8-bit Atmel AVR chips. The different instruction set -means that machine code (which makes up executable binary program) is -incompatible between the two, and a different compiler (actually just -a different version of `gcc `_) is required. - -The compiler for the regular Arduino IDE is the popular `avr-gcc -`_ package; the compiler for the -Maple version of the IDE is CodeSourcery's edition of gcc for the ARM -EABI target (:command:`arm-non-eabi-gcc`). A (preliminary) reference -on :ref:`using arm-none-eabi-gcc ` is available. - -The bitwidth of the processor means that the Maple can process 32-bit -operations (like adding two 32-bit integers) in a single instruction, -while an Arduino processor would have to split up large operations -into several smaller ones. In a lot of cases 8-bit operations are -plenty (integers 0-255, single characters of text, etc.), but if -you're dealing with higher resolution data, the speed up could be -significant. - -A trade-off is that code could be larger as well; program instructions -and memory locations can be up to 32 bits each. However, removal of -extra instructions and fancy packing together of simple instructions -means that programs aren't much larger (or are even smaller). - -Header Numbering and Incompatibilities --------------------------------------- - -.. FIXME generalize Maple-specific information - -The numbering of headers is different; on the Maple each GPIO has a -unique number: D0, D1, D2, all the way up to D37 (actually, there are -:ref:`a few more `...). On the Arduino, the analog pins are -numbered separately (A0-A5) from the digital pins (D0\ -D13). - -The incompatible hardware differences are: - -* **I2C port**: on most Arduinos, the |i2c| port is Analog Input 4 - (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5 - (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 (SDA). - - It should be possible to skywire, sacrificing signal quality (due to - increased capacitance). Alternatively, |i2c| can be bit-banged - reasonably well in software. This peripheral could potentially be - rerouted internally, but we haven't looked into it. - -* :ref:`PWM ` **on D10**: all the other standard Arduino PWM - headers have PWM functionality on the Maple (D2,D3,D6,D9,D11), but - not D10. We did our best! It may be possible to reroute this - peripheral internally using low level configuration, but we haven't - looked in to it. - -* **No External Voltage Reference**: The Arduino has an AREF pin which - allows the use of an external ADC voltage reference; the Maple has - an extra GPIO pin (D14) with PWM capability in this spot, and does - not allow an external voltage reference to be configured. - -* **EEPROM**: the Maple does not have any internal EEPROM. This - functionality can be emulated with regular persistent flash memory, - or with an external EEPROM chip. - -* **ISP Programming**: the Maple does not use an ISP/ICSP bus for - debugging; it uses :ref:`JTAG `. - - -Software Language/Library Changes ---------------------------------- - -With :ref:`a few exceptions `, the entire -Wiring/Arduino language is supported. However, there are some subtle -differences, most of which are improvements: - -* **32-bit integers**: many standard functions either expect or return - full 32-bit (4 byte) integer values instead of the regular 16-bit (2 - byte) Arduino values. - -* **64-bit doubles**: The :ref:`double ` type is a full - double-precision floating point type on the Maple; it is a - single-precision floating point value on the Arduino. - -* :ref:`pinMode() ` **types**: any :ref:`GPIO ` - (including analog pins) can be configured into one of the following - modes with a single call to ``pinMode()``: ``OUTPUT``, - ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``, - ``INPUT_PULLDOWN``. Additionally, the PWM pins (labeled "PWM" on the - Maple's silkscreen) can be configured in ``PWM`` and - ``PWM_OPEN_DRAIN`` modes, and the analog input pins (labeled "AIN") - can be configured in ``INPUT_ANALOG`` mode. See the :ref:`GPIO - documentation ` for more information. - -* :ref:`Serial port ` **syntax**: like the `Arduino Mega - `_, the Maple has - multiple :ref:`USART ports `. By default, ``Serial`` - is not mapped to any of them, use ``Serial1`` through ``Serial3`` - instead. - -* **16-bit** :ref:`PWM `: Arduino boards support 8-bit PWM, which - means that calls to :ref:`analogWrite() ` take - values between 0 (always off) and 255 (always on). The Maple - supports 16-bit PWM, so the corresponding values should be between 0 - (always off) and 65535 (always on). - -* **12-bit** :ref:`ADC `: Arduino boards support 10-bit ADC, which - means that calls to :ref:`analogRead() ` will - return values between 0 and 1023. The Maple supports 12-bit ADC, so - the same call will instead return values between 0 and 4095. - -Shield and Device Compatibility -------------------------------- - -.. list-table:: - :header-rows: 1 - - * - Shield/Device - - Compatible? - - Notes - - * - Ethernet shield - - Yes! - - Tested; no library yet - - * - WiFi Shield - - Yes! - - Tested; preliminary library support - - * - MIDI shield - - Yes! - - Tested; no library yet - - * - XBee shield - - Unknown - - - - * - Bluetooth shield - - Unknown - - Some Bluetooth <-> UART boards have been tested and are known - to work. - - * - Cellular shield - - Unknown - - - -Library Porting Status ----------------------- - -The state of currently ported Arduino libraries is the -:ref:`libraries`. - -.. TODO Update as libraries are ported. - -.. list-table:: - :header-rows: 1 - - - * - Library - - Ported? - - Notes - - * - Wire - - Preliminary - - In progress; see :ref:`library reference `. - - * - LiquidCrystal - - **Yes** - - :ref:`Included since IDE 0.0.7 ` - - * - Ethernet - - Not yet - - Planned - - * - EEPROM - - (Unsupported) third-party emulation - - The Maple doesn't have EEPROM; it uses flash instead. There is - an `EEPROM emulation library - `_ by - `x893 `_, but we haven't tested it. - - * - Firmata - - Not yet - - Planned - - * - Matrix - - Not yet - - Planned - - * - Servo - - **Yes** - - :ref:`Included since IDE 0.0.9 ` - - * - SoftwareSerial - - Not yet - - Planned - - * - Sprite - - Not yet - - Planned - - * - Stepper - - Not yet - - Planned - -Sketch and Library Porting HOWTO --------------------------------- - -In addition to the suggestions in this section, you may find many of -the individual :ref:`language reference ` pages useful. As -appropriate, these have "Arduino Compatibility" sections; one good -example is the :ref:`analogWrite() ` -function. - -- Check the hardware and header differences above, and see if your - project or shield needs to be modified (eg, add 3.3V level - converters or reroute PWM to header D10). - -- Check for ported library functionality. We intend to port all of the - core and popular libraries (like Wire, Ethernet, and the LCD screen - driver), but this task is not yet finished. (Patches are welcome!) - -- Check for peripheral conflicts; changing the configuration of timers - and bus speeds for a feature on one header may impact all the - features on that hardware "port". For example, changing the timer - prescaler to do long PWM pulses could impact |i2c| communications on - nearby headers. - -- Rewrite any low-level code. This could potentially be very - difficult, but hopefully you've used the Arduino libraries to - abstract away the registers and other hardware-specific - details. Your sketch probably doesn't have any low-level code; a - library which wraps a particular peripheral very well may. Some - help is available in the :ref:`arm-gcc` reference. - -- Redeclare variable sizes if necessary: generics like ``int`` will - probably work unless you depend on side-effects like rollover. - -- Check every ``pinMode()``: the Maple has more modes for GPIO - pins. For example, make sure to set analog pins to ``INPUT_ANALOG`` - before reading and PWM pins to ``PWM`` before writing. The full set - of pin modes is documented in the :ref:`lang-pinmode` reference. - -- Modify PWM writes: ``pinMode()`` must be set to ``PWM``, the - frequency of the PWM pulse configured, and the duty cycle written - with up to 16-bit resolution. - -- Modify ADC reads: :ref:`lang-analogread` takes the full pin number - (not 0-5) and returns a full 12-bit reading. The ADC pin must have - its ``pinMode()`` set to ``INPUT_ANALOG``. - -- Possibly convert all Serial-over-USB communications to use - :ref:`lang-serialusb` instead of a USART :ref:`serial port - `. The Maple has a dedicated USB port which is not - connected to the USART TX/RX pins in any way. - -- Check timing: Maple clock cycles are just 13.9 nanoseconds, though - the peripheral bus speeds (which limit GPIO output) are clocked - slower. diff --git a/source/errata.rst b/source/errata.rst deleted file mode 100644 index 657abd9..0000000 --- a/source/errata.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. _errata: - -======== - Errata -======== - -This page is a collection of known issues and warnings for each -revision of the Maple board. The failure modes aren't design errors, -but are easy ways to break or damage your board permanently. For a -list of differences between the Maple and Arduinos, see the -:ref:`compatibility reference `. - -The errata are grouped by Maple version ("Rev"). Rev 5 is currently -on sale. If you are unsure which version you own, the :ref:`Maple -hardware page ` has pictures and -descriptions of each version. - -.. contents:: Contents - :local: - -Maple Rev 5 ------------ - -Known issues: - -* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the - corresponding "AIN" is missing from its silkscreen. - -* **GPIO 39-43 not configured**: this is really more of a software - "TODO" item. Some of the JTAG header pins are numbered 39-43. These - STM32 pins are indeed fully functional :ref:`GPIO ` when a - :ref:`JTAG ` device is not connected, but we have not enabled - them in software and thus they can not be accessed with the regular - :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. - -Potential failure modes: - -* **High voltage on non-tolerant pins**: not all header pins are 5V - compatible; so e.g. connecting certain serial devices in the wrong - way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table - ` details which pins are 5V-tolerant. - -Maple Rev 3 ------------ - -Known issues: - -* **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 - have questionable RESET and BUT buttons. - - What seems to have happened is that the flux remover we used to - clean the boards before shipping eroded the plastic internals, which - resulted in intermittent functionality. All buttons on all shipped - boards did function in testing, but some may have been unreliable in - regular use. - - If you have this problem, we will be happy to ship you new buttons - if you think you can re-solder them yourself, or you can ship us - your board and we will swap out that part. - - For reference, the button part number is KMR211GLFS and the flux - remover we used is "Precision Electronics Cleaner" from RadioShack, - which is "Safe on most plastics" and contains Dipropylene glycol - monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol - methyl ether acetate (really?), and carbon dioxide. - -* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on - USART2 (:ref:`Serial2 `), have resistors in-line - between the STM32 and the headers. These resistors increase the - impedance of the lines for ADC reads and affect the open drain GPIO - functionality of the pins. - - These resistors were accidentally copied over from older Arduino USB - designs, where they appear to protect the USB-Serial converter from - TTL voltage on the headers. - -* **GPIO 39-43 not configured**: this is really more of a software - "TODO" item. Some of the JTAG header pins are numbered 39-43. These - STM32 pins are indeed fully functional :ref:`GPIO ` when the a - :ref:`JTAG ` device is not connected, but we have not enabled - them in software and thus they can not be accessed with the regular - :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. - -* **Silkscreen Errors**: the silkscreen on the bottom indicated PWM - functionality on pin 25 and listen the external header GND pin as - number 38 (actually 38 is connected to the BUT button). We manually - sharpied over both of these mistakes. - -* **PWM Marketing Mistake**: We originally sold the Maple advertising - 22 channels of 16-bit hardware PWM; actually the Maple only has 15. - -Potential failure modes: - -* **TTL voltage on non-tolerant pins**: not all header pins are 5V - compatible; connecting certain serial devices in the wrong way could - over voltage the pins. The :ref:`Pin-Mapping Mega Table - ` details which pins are 5V-tolerant. - -Maple Rev 1 ------------ - -Known issues: - -* **ADC noise**: generally very high, in particular when the USB port - is being used for communications (including keep-alive pings when - connected to a computer). - - This issue was resolved in Rev 3 with a 4-layer design and a - geometrically isolated ADC V\ :sub:`ref` plane. - -* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on - USART2 (:ref:`Serial2 `), have resistors in-line - between the STM32 and the headers. These resistors increase the - impedance of the lines for ADC reads and affect the open drain GPIO - functionality of the pins. - - These resistors were accidentally copied over from older Arduino USB - designs, where they appear to protect the USB-Serial converter from - TTL voltage on the headers. - -* **Silkscreen Differences**: the pin numbering scheme on Rev 1 is - different from Rev 3, and thus Rev 3 software is difficult to use - with Rev 1 boards. Notably, the analog input bank is labeled A0-A4 - on Rev 1 but 15-20 on Rev 3, and the extra header bank does not have - a pinout table on the bottom. - -* **No BUT Button**: the BUT button, useful for serial bootloading, - was only added in Rev 3. As a workaround, you can directly short the - appropriate MCU pin to Vcc; see `this forum posting - `_. - -* **PWM Marketing Mistake**: We originally sold the Maple advertising - 22 channels of 16-bit hardware PWM; actually the Maple only has 15. - -Potential failure modes: - -* **TTL voltage on non-tolerant pins**: not all header pins are 5v - compatible; connecting certain serial devices in the wrong way could - over voltage the pins. The :ref:`Pin-Mapping Mega Table - ` details which pins are 5V-tolerant. diff --git a/source/gpio.rst b/source/gpio.rst index 5daf43c..0f9f4df 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -3,7 +3,7 @@ GPIO ==== -.. FIXME generalize this maple-specific information +.. FIXME [Maple-specific values] The Maple features 38 ready-to-use general purpose input/output (GPIO) pins for digital input/output, numbered D0 through D37. These numbers diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 874ee82..44a5238 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -8,6 +8,30 @@ Maple .. contents:: Contents :local: +Technical Specifications +------------------------ + + * MCU: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor + * Clock Speed: **72 MHz** + * Operating Voltage: 3.3V + * Input Voltage (recommended): 3V-12V + * 39 Digital I/O Pins (:ref:`GPIO `) + * 16 Analog Input Pins + * 12-bit **ADC** resolution (:ref:`ADC `) + * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) + * Dedicated **USB** port for programming and communications (:ref:`USB`) + * External **JTAG** interface (:ref:`USB `) + * **128 Flash** and **20KB SRAM** + * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) + * Integrated **SPI** (:ref:`SPI`) + * Integrated **I2C** (:ref:`I2C`) + * 7 Channels of Direct Memory Access (**DMA**) + * 3 **USART** divices (:ref:`USART `) + * Four 4-channel **timers** (:ref:`Timers `) + * Supplies up to 800mA @ 3.3v + * Support for low power and sleep modes (<500uA) + * Dimensions are 2.05″x2.1″ + .. _maple-hardware-identify-rev: Identifying your Rev @@ -16,17 +40,22 @@ Identifying your Rev We went through three versions ("Revs") of the Maple hardware: Rev 1, Rev 3, and Rev 5 [#frev2_4]_; Rev 5, the final design, is currently on sale. The following sections will help you to help you identify your -Rev. Known issues are listed in the :ref:`errata `. +Rev. Known issues are listed in the :ref:`errata `. -Rev 1 +Rev 5 ^^^^^ -A small number of Maple Rev 1 boards went on sale in late 2009. They -have a light red silkscreen and a single pixelated leaf as a logo. +These boards went on sale in November 2010. They have white buttons, +and "r5" in small print near the "LeafLabs Maple" text next to the +"infinity leaf" logo. The Maple Rev 5 repositioned the double header +on the right hand side to better fit 0.1 inch pitch breadboard. This +necessitated the removal of pins 21 and 22 from the double header; +they are still available, but don't have any headers installed on +them. -.. figure:: /_static/img/maple_rev1.png +.. figure:: /_static/img/maple_rev5.png :align: center - :alt: Maple Rev 1 + :alt: Maple Rev 5 Rev 3 ^^^^^ @@ -40,20 +69,15 @@ It also includes a built-in LiPo battery charger. :align: center :alt: Maple Rev 3 -Rev 5 +Rev 1 ^^^^^ -These boards went on sale in November 2010. They have white buttons, -and "r5" in small print near the "LeafLabs Maple" text next to the -"infinity leaf" logo. The Maple Rev 5 repositioned the double header -on the right hand side to better fit 0.1 inch pitch breadboard. This -necessitated the removal of pins 21 and 22 from the double header; -they are still available, but don't have any headers installed on -them. +A small number of Maple Rev 1 boards went on sale in late 2009. They +have a light red silkscreen and a single pixelated leaf as a logo. -.. figure:: /_static/img/maple_rev5.png +.. figure:: /_static/img/maple_rev1.png :align: center - :alt: Maple Rev 5 + :alt: Maple Rev 1 .. _hardware-maple-powering: @@ -99,8 +123,150 @@ at the command line with :: $ git clone git://github.com/leaflabs/maple.git +.. _maple-errata: + +Errata +------ + +This section lists known issues and warnings for each revision of the +Maple board. The failure modes aren't design errors, but are easy ways +to break or damage your board permanently. For a list of differences +between the Maple and Arduinos, see the :ref:`Arduino Compatibility +reference `. + +The errata are grouped by Maple version ("Rev"). + +Maple Rev 5 +^^^^^^^^^^^ + +Known issues: + +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the + corresponding "AIN" is missing from its silkscreen. + +* **GPIO 39-43 not configured**: this is really more of a software + "TODO" item. Some of the JTAG header pins are numbered 39-43. These + STM32 pins are indeed fully functional :ref:`GPIO ` when a + :ref:`JTAG ` device is not connected, but we have not enabled + them in software and thus they can not be accessed with the regular + :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. + +Potential failure modes: + +* **High voltage on non-tolerant pins**: not all header pins are 5V + compatible; so e.g. connecting certain serial devices in the wrong + way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table + ` details which pins are 5V-tolerant. + +Maple Rev 3 +^^^^^^^^^^^ + +Known issues: + +* **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 + have questionable RESET and BUT buttons. + + What seems to have happened is that the flux remover we used to + clean the boards before shipping eroded the plastic internals, which + resulted in intermittent functionality. All buttons on all shipped + boards did function in testing, but some may have been unreliable in + regular use. + + If you have this problem, we will be happy to ship you new buttons + if you think you can re-solder them yourself, or you can ship us + your board and we will swap out that part. + + For reference, the button part number is KMR211GLFS and the flux + remover we used is "Precision Electronics Cleaner" from RadioShack, + which is "Safe on most plastics" and contains Dipropylene glycol + monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol + methyl ether acetate (really?), and carbon dioxide. + +* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on + USART2 (:ref:`Serial2 `), have resistors in-line + between the STM32 and the headers. These resistors increase the + impedance of the lines for ADC reads and affect the open drain GPIO + functionality of the pins. + + These resistors were accidentally copied over from older Arduino USB + designs, where they appear to protect the USB-Serial converter from + TTL voltage on the headers. + +* **GPIO 39-43 not configured**: this is really more of a software + "TODO" item. Some of the JTAG header pins are numbered 39-43. These + STM32 pins are indeed fully functional :ref:`GPIO ` when the a + :ref:`JTAG ` device is not connected, but we have not enabled + them in software and thus they can not be accessed with the regular + :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. + +* **Silkscreen Errors**: the silkscreen on the bottom indicated PWM + functionality on pin 25 and listen the external header GND pin as + number 38 (actually 38 is connected to the BUT button). We manually + sharpied over both of these mistakes. + +* **PWM Marketing Mistake**: We originally sold the Maple advertising + 22 channels of 16-bit hardware PWM; actually the Maple only has 15. + +Potential failure modes: + +* **TTL voltage on non-tolerant pins**: not all header pins are 5V + compatible; connecting certain serial devices in the wrong way could + over voltage the pins. The :ref:`Pin-Mapping Mega Table + ` details which pins are 5V-tolerant. + +Maple Rev 1 +^^^^^^^^^^^ + +Known issues: + +* **ADC noise**: generally very high, in particular when the USB port + is being used for communications (including keep-alive pings when + connected to a computer). + + This issue was resolved in Rev 3 with a 4-layer design and a + geometrically isolated ADC V\ :sub:`ref` plane. + +* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on + USART2 (:ref:`Serial2 `), have resistors in-line + between the STM32 and the headers. These resistors increase the + impedance of the lines for ADC reads and affect the open drain GPIO + functionality of the pins. + + These resistors were accidentally copied over from older Arduino USB + designs, where they appear to protect the USB-Serial converter from + TTL voltage on the headers. + +* **Silkscreen Differences**: the pin numbering scheme on Rev 1 is + different from Rev 3, and thus Rev 3 software is difficult to use + with Rev 1 boards. Notably, the analog input bank is labeled A0-A4 + on Rev 1 but 15-20 on Rev 3, and the extra header bank does not have + a pinout table on the bottom. + +* **No BUT Button**: the BUT button, useful for serial bootloading, + was only added in Rev 3. As a workaround, you can directly short the + appropriate MCU pin to Vcc; see `this forum posting + `_. + +* **PWM Marketing Mistake**: We originally sold the Maple advertising + 22 channels of 16-bit hardware PWM; actually the Maple only has 15. + +Potential failure modes: + +* **TTL voltage on non-tolerant pins**: not all header pins are 5v + compatible; connecting certain serial devices in the wrong way could + over voltage the pins. The :ref:`Pin-Mapping Mega Table + ` details which pins are 5V-tolerant. + +Recommended Reading +------------------- + +* STMicro documentation for STM32F103RB microcontroller: + + * `Datasheet `_ (pdf) + * `Reference Manual `_ (pdf) + * `Programming Manual `_ (assembly language and register reference) + .. rubric:: Footnotes .. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal testing. - diff --git a/source/i2c.rst b/source/i2c.rst index e2a7a04..15190a8 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -1,20 +1,8 @@ .. _i2c: -===== |i2c| ===== -.. FIXME update this documentation once you write the Wire library on -.. top of libmaple i2c. - -.. FIXME generalize Maple-specific documentation - -.. note:: - - The |i2c| interface is currently only available from the 'refactor' - branch of the github `libmaple - `_ repository. - |i2c| is a crude and easy-to-hack serial protocol that requires only two wires/channels for communication between many devices. Every message passed on the bus is between a *master* (who initiates the @@ -26,6 +14,8 @@ Higher level functionality, such as reading a particular register value, is achieved by writing to set the memory location then reading to pull out the data. +.. FIXME [Maple-specific values] + Note that the master/slave designation is on a message-by-message basis. The Maple can act as both a master (messages initiated by user code) and slave device (responding to requests via configurable @@ -37,8 +27,8 @@ interrupt handlers) at the same time. Hardware/Circuit Design ----------------------- -The Maple has two |i2c| ports. Port 1 (i2c1) has SDA on header D9 and -SCL on D5; Port 2 (i2c2) has SDA on D30 and SCL on D29. +The Maple has two |i2c| ports. Port 1 (I2C1) has SDA on header D9 and +SCL on D5; Port 2 (I2C2) has SDA on D30 and SCL on D29. The Maple reliably communicates with up to a 400kHz clock speed; this doesn't translate into a 400kbps data rate except in extreme cases @@ -60,16 +50,15 @@ oscilloscope to debug any issues. Function Reference ------------------ -The function API for |i2c| is not finished! See the `source code -`_ -for now. +Currently, only low-level support in :ref:`libmaple-i2c` exists. A +Wiring-style library is planned for a future release. SMBus ----- The STM32 microcontroller has hardware support for SMBus; we simply -have not written software for it. The SMBAL line for i2c1 is on header -D4 and for i2c2 is on D31. +have not written software for it. The SMBAL line for I2C1 is on header +D4 and for I2C2 is on D31. .. _i2c-recommended-reading: diff --git a/source/index.rst b/source/index.rst index 1d1a5be..9db5ff0 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,11 +3,13 @@ Maple Documentation Contents ============================ +.. FIXME [Maple-specific values] errata page links to Maple + Welcome! This is the Maple documentation index. If you just bought a Maple, you probably want to head to the :ref:`quickstart `. If you're having problems, check out the -:ref:`troubleshooting ` and :ref:`known problems -` pages. +:ref:`troubleshooting ` :ref:`known problems +` pages. Have fun! @@ -32,12 +34,12 @@ Have fun! Language Libraries - Arduino Compatibility + Arduino Compatibility libmaple Bootloader Troubleshooting - Known Problems Notes on GCC's ARM target + Complete Language Index .. _index-hardware: @@ -73,15 +75,3 @@ Have fun! .. hardware/maple-mini.rst .. hardware/maple-native.rst - -.. _index-reference: - -**Reference:** - -.. toctree:: - :maxdepth: 1 - - Technical Specifications - Complete Language Index - - diff --git a/source/lang/cpp/arithmetic.rst b/source/lang/cpp/arithmetic.rst index 7e8c3fc..26e2811 100644 --- a/source/lang/cpp/arithmetic.rst +++ b/source/lang/cpp/arithmetic.rst @@ -117,11 +117,8 @@ See Also -------- - The individual sizes (in bits) of various available types are - defined in `libmaple_types.h - `_\ - . + defined in :ref:`libmaple_types.h `. - :ref:`sizeof `\ () - .. include:: cc-attribution.txt diff --git a/source/language-index.rst b/source/language-index.rst index 531e72c..a064b3e 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -10,6 +10,9 @@ API references for documented libmaple functionality. The "C++ for Maple" pages are intended as a minimal reference/refresher for programmers familiar with the Arduino language. +**Looking for something else?** The low-level :ref:`libmaple library +interfaces ` are documented separately. + .. _index-language-index-cpp: .. _index-language-index-api: diff --git a/source/language.rst b/source/language.rst index ea841f5..111a1f1 100644 --- a/source/language.rst +++ b/source/language.rst @@ -28,14 +28,14 @@ Maple Language Reference The following table summarizes the available core language features. A more exhaustive index is available at the :ref:`language-index`. +.. FIXME mention Maple Native supports malloc(), free(), operator +.. new(), and operator delete(), when that is a true thing to say. + **Looking for something else?** - See the :ref:`libraries` for extra built-in libraries for dealing with different kinds of hardware. -.. FIXME mention Maple Native supports malloc(), free(), operator -.. new(), and operator delete(), when that is a true thing to say. - - If you're looking for something from the C standard library (like ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler ` used to compile your programs is configured to link @@ -43,6 +43,9 @@ A more exhaustive index is available at the :ref:`language-index`. use of any of its header files. However, dynamic memory allocation (``malloc()``, etc.) is not available. +- If you're looking for low-level details, see the :ref:`libmaple + ` reference page. + +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | | | | | @@ -273,7 +276,7 @@ Unimplemented Arduino Features ------------------------------ The following Wiring/Arduino features are currently unimplemented on -the Maple. However, they will be present in future versions: +the Maple. - `tone() `_ - `noTone() `_ @@ -299,16 +302,18 @@ programming ideas and C++. Note for C/C++ Hackers ---------------------- -This is a note for programmers comfortable with C or C++ (although, -you C programmers should remember that `C++ is not a superset of C -`_) who -want a better understanding of the differences between C++ and the -Wiring language. The good news is that the differences are relatively -few; Wiring is just a thin wrapper around C++. +This is a note for programmers comfortable with C or C++ who want a +better understanding of the differences between C++ and the Wiring +language. -Some potentially better news is that the Maple can be programmed using -a :ref:`standard Unix toolchain `, so if you'd rather -stick with :command:`gcc`, :command:`make`, and friends, you can. +The good news is that the differences are relatively few; Wiring is +just a thin wrapper around C++. Some potentially better news is that +the Maple can be programmed using a :ref:`standard Unix toolchain +`, so if you'd rather stick with :command:`gcc`, +:command:`make`, and friends, you can. If you're using the Unix +toolchain and want to skip past the Wiring conveniences and get +straight to registers, you are encouraged to move on to the +:ref:`libmaple` documentation. A *sketch* is the IDE's notion of a project; it consists of one or more files written in the Wiring language, which is mostly the same as @@ -334,9 +339,9 @@ work. As of |today|, Maple only has 20 KB RAM, anyway, so it's doubtful that static allocation is not what you want. The Wiring language also does not require you to define your own -``main`` method (in fact, it forbids you from doing so). Instead, you -are required to define two functions, ``setup`` and ``loop``, with -type signatures :: +``main`` method (in fact, we currently forbid you from doing so). +Instead, you are required to define two functions, ``setup`` and +``loop``, with type signatures :: void setup(void); void loop(void); @@ -351,26 +356,33 @@ parses the result to produce a list of all functions defined in the global scope. (We borrow this stage from the Arduino IDE, which in turn borrows it from Wiring. It uses regular expressions to parse C++, which is, of course, `Bad and Wrong -`_. An -upcoming rewrite of the IDE performs this preprocessing step -correctly, using a real parser. Until then, you have our apologies.) -The order in which the individual sketch files are concatenated is not -defined; it is unwise to write code that depends on a particular -ordering. +`_. In the +future, we'll do this correctly, using a better parser. Until then, +you have our apologies.) The order in which the individual sketch +files are concatenated is not defined; it is unwise to write code that +depends on a particular ordering. The concatenated sketch files are then appended onto a file which includes `WProgram.h -`_ +`_ (which includes the wirish and libmaple libraries, and declares ``setup()`` and ``loop()``), and then provides declarations for all the function definitions found in the previous step. At this point, -we have a file that is a valid C++ translation unit, but lacks a -``main()`` method. The final step of compilation provides this -method, which behaves roughly like:: +we have a file that is a valid C++ translation unit, but lacks +``main()``. The final step of compilation provides ``main()``, which +behaves roughly like:: int main(void) { + // Call libmaple's built-in initialization routines + init(); + + // Perform the user's initialization setup(); - while (true) loop(); + + // Call user loop() forever. + while (true) { + loop(); + } } (The truth is a little bit more complicated, but not by much). @@ -441,20 +453,19 @@ Which could plausibly be turned into the final source file :: } int main() { + init(); setup(); while (true) loop(); } -(Recall that it's legal C++ for a function to be declared multiple -times, as long as it's defined exactly once). - - Recommended Reading ------------------- * `newlib Documentation `_ -* STMicro documentation for STM32F103RB microcontroller: - * `Datasheet `_ (pdf) +* :ref:`libmaple Documentation ` + +* ST documentation: + * `Reference Manual `_ (pdf) * `Programming Manual `_ (assembly language and register reference) diff --git a/source/libmaple.rst b/source/libmaple.rst index 9faca03..375e821 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -5,37 +5,35 @@ ``libmaple`` ============ -.. image:: /_static/img/libmaple-screenshot-small.png - :align: center - :alt: libmaple screenshot - -`LeafLabs libmaple `_ is the low level library we -have developed for for the ARM Cortex-M3 chips manufactured by -STMicroelectronics used in the Maple boards (the `STM32F103x`_ -series). We found the generic peripheral libraries too painful to -build on top of, and reimplemented the functionality we needed in a -simpler (and less general) form. - -.. _libmaple-libmaple: http://github.com/leaflabs/libmaple -.. _STM32F103x: http://www.st.com/stonline/stappl/productcatalog/app?path=/pages/stcom/PcStComPartNumberSearch.searchPartNumber&search=stm32f103 - -This library is transparently included in the `Maple IDE -`_, but we develop it separately -using good old Unix command line tools and release it for advanced -users who might chafe at the "sketch" programming model of the -IDE. Included are some examples, a Makefile, and the compatibility -wrappers and code to imitate the Arduino programming library. - -**Check out the latest source**:: - - git clone git://github.com/leaflabs/libmaple.git - -.. TODO after finishing refactor: create, style, and host a pure -.. Doxygen libmaple reference docs. This implies determining a stable -.. API. - -.. **Table of contents:** - -.. .. toctree:: -.. :maxdepth: 2 +LeafLabs' libmaple (`source code on Github +`_) is the library we have +developed for the `STM32 `_ line of ARM Cortex M3 +microcontrollers. Its high-level interfaces are :ref:`largely +compatible ` with the AVR libraries written for +the `Arduino `_ and `Wiring +`_ development boards. + +libmaple is split into two pieces: a lower level layer written in pure +C, which we call *libmaple proper* (in the `libmaple/ +`_ +directory of the source repository), and the Wiring-style C++ API +written on top of it, called *Wirish* (in `wirish/ +`_). + +libmaple is bundled with the :ref:`Maple IDE `. However, we +develop it separately, and :ref:`release it standalone +` for advanced users who might chafe at the "sketch" +programming model of the IDE. + +As always, :ref:`patches are welcome `. + +**Contents:** + +.. toctree:: + :maxdepth: 1 + + libmaple/overview + libmaple/apis + libmaple/contributing + libmaple/coding-standard diff --git a/source/libmaple/api/adc.rst b/source/libmaple/api/adc.rst new file mode 100644 index 0000000..8817055 --- /dev/null +++ b/source/libmaple/api/adc.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-adc: + +``adc.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: adc.h diff --git a/source/libmaple/api/bitband.rst b/source/libmaple/api/bitband.rst new file mode 100644 index 0000000..fd57944 --- /dev/null +++ b/source/libmaple/api/bitband.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-bitband: + +``bitband.h`` +============= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: bitband.h diff --git a/source/libmaple/api/bkp.rst b/source/libmaple/api/bkp.rst new file mode 100644 index 0000000..9a697c7 --- /dev/null +++ b/source/libmaple/api/bkp.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-bkp: + +``bkp.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: bkp.h diff --git a/source/libmaple/api/dac.rst b/source/libmaple/api/dac.rst new file mode 100644 index 0000000..038753b --- /dev/null +++ b/source/libmaple/api/dac.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-dac: + +``dac.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: dac.h diff --git a/source/libmaple/api/delay.rst b/source/libmaple/api/delay.rst new file mode 100644 index 0000000..a0d013a --- /dev/null +++ b/source/libmaple/api/delay.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-delay: + +``delay.h`` +=========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: delay.h diff --git a/source/libmaple/api/dma.rst b/source/libmaple/api/dma.rst new file mode 100644 index 0000000..1512d0c --- /dev/null +++ b/source/libmaple/api/dma.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-dma: + +``dma.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: dma.h diff --git a/source/libmaple/api/exti.rst b/source/libmaple/api/exti.rst new file mode 100644 index 0000000..2909aa7 --- /dev/null +++ b/source/libmaple/api/exti.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-exti: + +``exti.h`` +========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: exti.h diff --git a/source/libmaple/api/flash.rst b/source/libmaple/api/flash.rst new file mode 100644 index 0000000..6f2f9d3 --- /dev/null +++ b/source/libmaple/api/flash.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-flash: + +``flash.h`` +=========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: flash.h diff --git a/source/libmaple/api/fsmc.rst b/source/libmaple/api/fsmc.rst new file mode 100644 index 0000000..cecfc99 --- /dev/null +++ b/source/libmaple/api/fsmc.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-fsmc: + +``fsmc.h`` +========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: fsmc.h diff --git a/source/libmaple/api/gpio.rst b/source/libmaple/api/gpio.rst new file mode 100644 index 0000000..2cfec23 --- /dev/null +++ b/source/libmaple/api/gpio.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-gpio: + +``gpio.h`` +========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: gpio.h diff --git a/source/libmaple/api/i2c.rst b/source/libmaple/api/i2c.rst new file mode 100644 index 0000000..14dd304 --- /dev/null +++ b/source/libmaple/api/i2c.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-i2c: + +``i2c.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: i2c.h diff --git a/source/libmaple/api/iwdg.rst b/source/libmaple/api/iwdg.rst new file mode 100644 index 0000000..3911ece --- /dev/null +++ b/source/libmaple/api/iwdg.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-iwdg: + +``iwdg.h`` +========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: iwdg.h diff --git a/source/libmaple/api/libmaple.rst b/source/libmaple/api/libmaple.rst new file mode 100644 index 0000000..d4f28f0 --- /dev/null +++ b/source/libmaple/api/libmaple.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-libmaple: + +``libmaple.h`` +============== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: libmaple.h diff --git a/source/libmaple/api/libmaple_types.rst b/source/libmaple/api/libmaple_types.rst new file mode 100644 index 0000000..bbea2c1 --- /dev/null +++ b/source/libmaple/api/libmaple_types.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-libmaple_types: + +``libmaple_types.h`` +==================== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: libmaple_types.h diff --git a/source/libmaple/api/nvic.rst b/source/libmaple/api/nvic.rst new file mode 100644 index 0000000..b94dc31 --- /dev/null +++ b/source/libmaple/api/nvic.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-nvic: + +``nvic.h`` +========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: nvic.h diff --git a/source/libmaple/api/pwr.rst b/source/libmaple/api/pwr.rst new file mode 100644 index 0000000..82e4864 --- /dev/null +++ b/source/libmaple/api/pwr.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-pwr: + +``pwr.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: pwr.h diff --git a/source/libmaple/api/rcc.rst b/source/libmaple/api/rcc.rst new file mode 100644 index 0000000..81dc604 --- /dev/null +++ b/source/libmaple/api/rcc.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-rcc: + +``rcc.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: rcc.h diff --git a/source/libmaple/api/ring_buffer.rst b/source/libmaple/api/ring_buffer.rst new file mode 100644 index 0000000..a014fa4 --- /dev/null +++ b/source/libmaple/api/ring_buffer.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-ring_buffer: + +``ring_buffer.h`` +================= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: ring_buffer.h diff --git a/source/libmaple/api/scb.rst b/source/libmaple/api/scb.rst new file mode 100644 index 0000000..78cc7eb --- /dev/null +++ b/source/libmaple/api/scb.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-scb: + +``scb.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: scb.h diff --git a/source/libmaple/api/spi.rst b/source/libmaple/api/spi.rst new file mode 100644 index 0000000..b0c7e86 --- /dev/null +++ b/source/libmaple/api/spi.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-spi: + +``spi.h`` +========= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: spi.h diff --git a/source/libmaple/api/stm32.rst b/source/libmaple/api/stm32.rst new file mode 100644 index 0000000..2784540 --- /dev/null +++ b/source/libmaple/api/stm32.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-stm32: + +``stm32.h`` +=========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: stm32.h diff --git a/source/libmaple/api/systick.rst b/source/libmaple/api/systick.rst new file mode 100644 index 0000000..5ec906c --- /dev/null +++ b/source/libmaple/api/systick.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-systick: + +``systick.h`` +============= + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: systick.h diff --git a/source/libmaple/api/timer.rst b/source/libmaple/api/timer.rst new file mode 100644 index 0000000..3acbf4f --- /dev/null +++ b/source/libmaple/api/timer.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-timer: + +``timer.h`` +=========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: timer.h diff --git a/source/libmaple/api/usart.rst b/source/libmaple/api/usart.rst new file mode 100644 index 0000000..26e6b9c --- /dev/null +++ b/source/libmaple/api/usart.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-usart: + +``usart.h`` +=========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: usart.h diff --git a/source/libmaple/api/util.rst b/source/libmaple/api/util.rst new file mode 100644 index 0000000..50ffe76 --- /dev/null +++ b/source/libmaple/api/util.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _libmaple-util: + +``util.h`` +========== + +[Stub] support. + +Library Documentation +--------------------- + +.. doxygenfile:: util.h diff --git a/source/libmaple/apis.rst b/source/libmaple/apis.rst new file mode 100644 index 0000000..f493406 --- /dev/null +++ b/source/libmaple/apis.rst @@ -0,0 +1,14 @@ +.. _libmaple-apis: + +APIs +==== + +This is the master index for libmaple proper's APIs. + +**Contents** + +.. toctree:: + :maxdepth: 1 + :glob: + + api/* diff --git a/source/libmaple/coding-standard.rst b/source/libmaple/coding-standard.rst new file mode 100644 index 0000000..23d20f8 --- /dev/null +++ b/source/libmaple/coding-standard.rst @@ -0,0 +1,412 @@ +.. _libmaple-coding-standard: + +Coding Standard +=============== + +This page documents the coding standard for :ref:`libmaple`. It's +intended as a guide for how you should structure any code you would +like included into the LeafLabs releases of libmaple. + +LeafLabs team members are required to follow these when producing new +code. Community contributors to libmaple are strongly encouraged to +do so; following these rules will greatly increase the probability +that your patches will be folded in. + +In general, follow this guide unless there's a very good reason not +to. Laziness doesn't count as a good reason. Most, if not all, of +these decisions are entirely arbitrary, but it's important for +readability that we be consistent. (If you notice an inconsistency, +you should fix it). + +Note that the file ``.dir-locals.el`` in the libmaple root directory +already ensures that many of these standards are followed by default +in Emacs (but not on Windows, where it would need to be named +``_dir_locals.el``, and no way, man). There's also some elisp +scattered about this file which will provide you additional help. + +Vim customizations to do the same thing would be nice! + +.. contents:: Contents + :local: + +License +------- + +.. highlight:: scheme + +Put an MIT license at the beginning of the file (look at any of our +source files for an example). Copyright should go either to you or to +LeafLabs, LLC. + +Emacs: if you don't like seeing the license, you should use elide-head +(which will hide it for you). You can use the following:: + + (require 'elide-head) + (setq programming-mode-hooks '(c-mode-hook c++-mode-hook)) + (add-to-list 'elide-head-headers-to-hide + '("The MIT License" . "DEALINGS IN\n [*] THE SOFTWARE")) + (add-to-list 'elide-head-headers-to-hide + '("The MIT License" . "DEALINGS IN THE\n...SOFTWARE")) + (dolist (hook programming-mode-hooks) + (add-hook hook (lambda () (elide-head)))) + +Whitespace +---------- + +- 4 space indents (set in ``.dir-locals.el``). + +- Unix newlines. Some exceptions are currently grandfathered in; these + will go away in time. + +- No tab characters (set in ``.dir-locals.el``). + +- No trailing whitespace. For help getting this (and no tab + characters) done automatically in Emacs, you can use + `code-fascism.el `_. + +- Files end in exactly one newline. The presence of a newline at EOF + is already done by ``c-require-final-newline`` in recent versions of + Emacs. + +- Exactly two newlines separate source paragraphs (you do separate + your code into paragraphs, don't you?). + +- The first line in a function is non-blank. + +.. highlight:: cpp + +- Exactly one space after ``if``, ``else``, ``for``, and ``while``, + before the following ``{`` or ``(``. One space before ``else``, + after the preceding ``}``. For example:: + + // This is good; we like this: + if (foo) { + while (quux) { + bar(); + } + } else { + baz(); + } + + // THIS IS BAD! DON'T DO THIS: + if(foo){ + while(quux){ + bar(); + } + }else{ + baz(); + } + +- Exactly one space in between binary arithmetic, logical, and + comparison operators and their operands. Examples:: + + // This is good: + int x = a + b * (c - d); + if (x != 0 && a > 7) { + SerialUSB.println(x); + } + + // THIS IS BAD! + int x = a+b*(c-d); + if (x!=0 && a>7) { + SerialUSB.println(x); + } + + // This is good: + uint32 adc_data = ADC1_BASE->DR; + SerialUSB.println(adc_data); + + // THIS IS BAD! + uint32 adc_data = ADC1_BASE -> DR; + SerialUSB . println(adc_data); + +- No space between a unary operator and its operand. Examples:: + + // Good: + x++; + + // BAD! + x ++; + + // Good: + y = -x; + + // BAD! + y = - x; + +- If you need to break up a long line: + + * Prefer to break up long expressions after a binary operator. Example:: + + // Good: + if (some_really_long_conditional_wow_this_really_goes_on_forever || + maybe_something_else_could_happen_too) { + ... + } + + // BAD! + if (some_really_long_conditional_wow_this_really_goes_on_forever + || maybe_something_else_could_happen_too) { + ... + } + + * When breaking up a function's arguments over multiple lines, align + the arguments on subsequent lines with the first argument. + Example:: + + // Good: + return_type value_i_got = function_with_a_really_long_name(argument1, + argument2, + argument3); + + // BAD! + return_type value_i_got = function_with_a_really_long_name(argument1, + argument2, + argument3); + + // BAD! + return_type value_i_got = function_with_a_really_long_name(argument1, + argument2, + argument3); + +- In function invocations, no space in between the function name and + the opening parenthesis. Example:: + + // Good: + SerialUSB.println("Hello, world!"); + + // BAD! + SerialUSB.println ("Hello, world!"); + +- Don't indent C code within a conditionally-compiled ``extern "C"`` + block. Example:: + + // Good: + #ifdef __cplusplus + extern "C"{ + #endif + + void some_c_function(void); + + #ifdef __cplusplus + } // extern "C" + #endif + + // BAD! + #ifdef __cplusplus + extern "C"{ + #endif + + void some_c_function(void); + + #ifdef __cplusplus + } // extern "C" + #endif + + Emacs does the "bad" behavior by default, which can be very + annoying. You can turn this off with :: + + (defun c-mode-inextern-lang-hook () + (setcdr (assq 'inextern-lang c-offsets-alist) '-)) + (add-hook 'c-mode-hook c-mode-inextern-lang-hook) + +Comments +-------- + +.. highlight:: c++ + +- Multi-line comments are pretty flexible. Any of these is fine:: + + /* Comment starts here. + * Continued lines have a '*' before them. + * The comment can end after the last line. + */ + + /* Comment starts here. + * The comment can end on the same line. */ + + /* + * You can also place a newline after the opening "/*". + */ + +- Doxygen comments are multi-line comments that begin with ``/**`` + instead. + +- Single-line comments are up to you. + +Braces +------ + +- Mostly `1TBS + `_. The + only difference is that the opening brace of a function's definition + occurs exactly one space character after the closing parenthesis in + that function's parameter list. Example:: + + void func(void) { + ... + } + +Naming conventions +------------------ + +We'll handle the usual casing/underscore debate as follows. + +- First, ``Dont_Mix_Like_This``, because ``It_Looks_Really_Ugly``, ok? + [There's been some debate about this, and some exceptions are + already grandfathered in, so in order to settle it, let's call this + a "recommendation" instead of "requirement".] + +- Variables: Use underscores to separate words in C identifiers:: + + int some_example_name; + + User-facing C++ variables should be camel cased + (``thisIsAnExample``, ``boardPWMPins``, etc.), for consistency with + the Arduino style. It's probably a good idea for you to case + non-user facing C++ variables in the C style; this will help + disambiguate what's part of the Wirish API and what's not. + +- Classes: Pascal case. So ``ThisIsAClassName``, but ``thisIsNot``, + ``this_is_not``, and ``Dont_You_DareTryANYTHING_STUPID``. + +- Functions: C functions are all lowercase, and words are separated by + underscores. C++ method names are camel cased. + +- Structs: Usually like variables (``adc_dev``, ``adc_reg_map``, + etc.), but it's not crucial. Don't feel obliged to put ``_t`` at + the end of the type name; we don't. + +- Macros and constants: all caps, separated by underscores. C++ + variables with the ``const`` qualifier generally aren't considered + "constants" for the purposes of this rule; i.e., they are cased + according to the rules for variables. We make an exception for + ``PIN_MAP``, because it's the central Wirish data structure. + +- foo.h gets ``#ifdef``\ 'ed to ``_FOO_H_``. + +- Acronyms: The case of letters in an acronym is determined by the + case of the first letter in the acronym, which is determined by + following the above rules. Examples:: + + // Good: + void usb_func() { ... } + void frob_usb_disc() { ... } + class SomethingUSB { + void usbInit(); + void initUSB(); + }; + + // BAD: + class BadUsb { ... }; // say "GoodUSB" instead + void swizzle_USB_disc() { ... } // say "swizzle_usb_disc" instead + +Documentation +------------- + +- Doxygen comments on every user-facing function and type. + Additionally, individually document the fields and enumerator values + of nontrivial user-facing structs and enums. See any register map + type's definition for an example. + +- For libmaple proper, you don't need comments for each register bit + definition, since that's just repeating information better obtained + by reading ST RM0008. + +- Doxygen comments generally only belong on types, functions, + etc. that are part of the public user-facing API. This generally + means that if there's ReST documentation for it under libmaple's + ``docs/source/``, it needs Doxygen comments, and that ReST should + use Breathe to pull that Doxygen comment out. (For more information + on this, see libmaple file ``docs/README``). + + There are some exceptions to this rule since Breathe isn't totally + mature yet and Sphinx's C++ domain is still in flux. In these + cases, document the code "manually" in ReST. + + This should be avoided if at all possible, since it creates a + maintenance burden of documenting things in two places at once, and + makes it easier for documentation to go stale. + + If you do have to document something manually, put a comment in the + source file informing future maintainers about it, so they'll pay + extra attention when making changes. + +- When adding peripheral support, it would be nice if you put + longer-form comments into the libmaple ``notes/`` directory, with a + comment in the corresponding .h file referring to it. See the + :ref:`dac.h ` source for an example. + + This lets us keep the source files relatively free of "introductory" + material, while allowing new readers a convenient starting point. + These longer-form notes also have a habit of turning into official, + user-facing documentation. + +- **For libmaple proper**, the convention is to document any + user-facing function at the point where it is defined. In + particular, this means you should document an externally-linked + function defined in a .c file in that .c file, not in the header + file where it is declared to the user. + + **For Wirish**, the convention is to put the documentation in the + header file where the function is declared. + +General Formatting +------------------ + +.. highlight:: scheme + +- Keep it 80-column clean. + + Emacs users: this means that the largest column number is 79. You + should turn on column number mode to help you out:: + + (column-number-mode 1) + + You can get more help from `lineker-mode + `_. Just put + lineker.el somewhere in your load-path, and:: + + (require 'lineker) + (dolist (hook '(c-mode-hook c++-mode-hook)) + (add-hook hook (lambda () (lineker-mode 1)))) + +.. highlight:: cpp + +Language Features +----------------- + +In libmaple proper, aim for C99 compatibility. Some GCC extensions +are OK, but `don't get crazy `_. + +Explicitly approved GCC extensions: + + * `asm volatile `_ + + * `Nested functions `_ + +In Wirish, generally be very conservative when using C++ features that +aren't part of C. We are forced to use C++ for Arduino compatibility +(and the general Arduino style of conflating objects and libraries), +but it's an angry beast, and we don't want to provoke it. **The +mantra is "C with classes"**. + +Explicitly approved C++ features: + + * Initializers that aren't constant; e.g. the ``gpio_dev*`` values + in a ``PIN_MAP``. + + * Default arguments: e.g., the timeout argument in + :ref:`lang-waitforbuttonpress`. + +Explicitly forbidden C++ features: + + * Templates + +Conditionally allowed C++ features: + + * Operator overloading: Never allowed when it's just for style. + Probably fine when you're implementing a class that models a + mathematical structure, and you'd like to implement + e.g. ``operator+()``. + diff --git a/source/libmaple/contributing.rst b/source/libmaple/contributing.rst new file mode 100644 index 0000000..724605b --- /dev/null +++ b/source/libmaple/contributing.rst @@ -0,0 +1,113 @@ +.. _libmaple-contributing: + +Contributing to libmaple +======================== + +First of all, thanks! Community contributions are what makes open +source great. + +If your patch is minor (you've found a typo, you've added a new +function, etc.), feel free to just make a `forum post +`_ describing your changes. + +If your changes are larger (you wrote a new library, you added support +for a new peripheral, etc.), we'd prefer you submit a pull request on +Github or send us a nicely-formatted patch via email. + +.. contents:: Contents + :local: + +.. _libmaple-faq-patches-preparing: + +Preparing Your Patch +-------------------- + +Before submitting a patch, please make sure it complies with the +:ref:`coding standard `. Consistent style throughout +the source tree is an important implementation objective for us, and a +patch that doesn't comply with the coding standard we've set forth is +likely to be sent back until it follows the standard. + +We would prefer if you release each new file you submit under the `MIT +license `_. See +e.g. `bkp.h +`_ +for an example, and the coding standard for more details. Code +released under the `Lesser GPL +`_ may be accepted for +Wirish, but will almost certainly be rejected for libmaple proper. We +will not accept patches released under the `GPL +`_. + +**We're not against the GPL**! It just doesn't suit our purposes for +libmaple. If you're interested in a GPLed library for ST +microcontrollers, check out `libopenstm32 +`_. +Also note that :ref:`libraries ` released under the GPL are +fine, we just don't want any core libmaple or Wirish code to be GPLed. + +.. _libmaple-faq-patches-github: + +Submitting Via Github Pull Request (Preferred) +---------------------------------------------- + +The most convenient way for you to contribute patches is to submit a +pull request on `Github `_. Github provides +excellent code review interfaces, which will make it easy for us at +LeafLabs to communicate with you (and each other) about your patch. +It also makes it easy for us to merge your patch into the libmaple +source tree when the time comes. + +The steps to submit a pull request are as follows: + +1. If you don't already have one, get a `Github account + `_ (free). + +2. Fork libmaple, then clone your fork to the computer you code on. + Github provides detailed instructions on `forking and cloning a + repository `_. + +3. Push your commits to your Github libmaple fork (see instructions + linked in Step 2 for a step-by-step walkthrough on how to do this). + +4. `Submit a pull request `_ to + the LeafLabs version of libmaple. + +.. _libmaple-faq-patches-email: + +Submitting Via Email +-------------------- + +If you're unfamiliar with Git or would prefer not to use Github, you +can always send us a patch via email at info@leaflabs.com. We'd love +it if you used the `Linux kernel patch format +`_, but please at least include +the following information in your email: + +1. How you generated your patch (arguments to ``diff``, etc.) + +2. What git branch/commit or libmaple version your patch applies to + +3. A one-line summary of your changes, along with any other details + you think we should know. + +4. A sign-off line certifying your `developer certificate of origin + `_. + +That said, we'd really prefer a pull request. If you'd like to learn +more about Git, we recommend the following resources: + +* `The Git Community Book `_: A + collaboratively edited book on Git. + +* `Pro Git `_: despite its title, this is a + fairly beginner-friendly source of information. + +* `Understanding Git Conceptually + `_: a good, + introductory tutorial on Git's fundamental concepts. + +* `Git for Computer Scientists + `_: if + you're comfortable with directed acyclic graphs, this resource + explains Git's functionality in graph-theoretic terms. diff --git a/source/libmaple/overview.rst b/source/libmaple/overview.rst new file mode 100644 index 0000000..9bce564 --- /dev/null +++ b/source/libmaple/overview.rst @@ -0,0 +1,342 @@ +.. highlight:: c + +.. _libmaple-overview: + +Overview +======== + +This page is a general overview of the low-level aspects of libmaple +proper. It provides a general perspective of the library's goals and +design. Examples are given from the libmaple sources. + +.. contents:: Contents + :local: + +Design Goals +------------ + +The central goal of the libmaple project is to provide a pleasant, +consistent set of interfaces for dealing with the various peripherals +on the STM32 line. + +Let's start with the basics. If you're interested in low-level details +on the STM32, then you're going to spend a lot of quality time wading +through `ST RM0008 +`_. +RM0008 is the single most important tool in your toolbox. It is the +authoritative documentation for the capabilities and low-level +programming interfaces of ST's line of ARM Cortex M3 microcontrollers. + +Perhaps you haven't read it in detail, but maybe you've at least +thumbed through a few of the sections, trying to gain some +understanding of what's going on. If you've done that (and if you +haven't, just take our word for it), then you know that underneath the +covers, *everything* is controlled by messing with bits in the +seemingly endless collections of registers specific to every +peripheral. The `USARTs `_ have +data registers; (some of the) the `timers +`_ have capture/compare +registers, the `GPIOs `_ have +output data registers, etc. + +For the most part, Wirish does everything it can to hide this truth +from you. That's because when you really just want to get your robot +to fly, your LEDs to blink, or your `FM synthesizer +`_ to, well, `synthesize +`_, you probably couldn't care +less about messing with registers. + +That's fine! In fact, it's our explicit goal for Wirish to be good +enough that most people never need to know libmaple proper even +exists. We want to make programming our boards as easy as possible, +after all. But the day may come when you want to add a library for an +as-yet unsupported peripheral, or you want to do something we didn't +anticipate, or you'd like to squeeze a little more speed out of a +critical section in your program. Or maybe you're just curious! + +If anything in the above paragraph describes you, then you'll find +that you need a way to translate your knowledge of RM0008 into +software. We imagine (if you're anything like us) you want to spend +the least amount of time you possibly can doing that +translation. Ideally, once you've finished your design, you want some +way to start reading and writing code right away, without having to +bushwhack your way through a thicket of clunky APIs. + +The central abstractions we've chosen to accomplish the above goals +are *register maps* and *devices*. Register maps are just structs +which encapsulate the layout of the IO-mapped memory regions +corresponding to a peripheral's registers. Devices encapsulate a +peripheral's register map as well as any other necessary information +needed to operate on it. Peripheral support routines generally +operate on devices rather than register maps. + +Devices +------- + +At the highest level, you'll be dealing with *devices*, where a +"device" is a general term for any particular piece of hardware you +might encounter. So, for example, an analog to digital converter is a +device. So is a USART. So is a GPIO port. In this section, we'll +consider some hypothetical "xxx" device. + +The first thing you need to know is that the header file for dealing +with xxx devices is, naturally enough, called ``xxx.h``. So if you +want to interface with the :ref:`ADCs `, just ``#include +"adc.h"``. + +Inside of ``xxx.h``, there will be a declaration for a ``struct +xxx_dev`` type. This type encapsulates all of the information we keep +track of for that xxx. So, for example, in ``adc.h``, there's a +``struct adc_dev``:: + + /** ADC device type. */ + typedef struct adc_dev { + adc_reg_map *regs; /**< Register map */ + rcc_clk_id clk_id; /**< RCC clock information */ + } adc_dev; + +The ADCs aren't particularly complicated. All we keep track of for an +ADC device is a pointer to its register map (which keeps track of all +of its registers' bits; see :ref:`below ` +for more details), and an identifying piece of information which tells +the RCC (reset and clock control) interface how to turn the ADC on and +reset its registers to their default values. + +The timers on the STM32 line are more involved than the ADCs, so a +``timer_dev`` has to keep track of a bit more information:: + + /** Timer device type */ + typedef struct timer_dev { + timer_reg_map_union regs; + rcc_clk_id clk_id; + timer_type type; + voidFuncPtr handlers[]; + } timer_dev; + +However, as you can see, both ADC and timer devices are named +according to a single scheme, and store similar information. + +``xxx.h`` will also declare pointers to the actual devices you need to +deal with, called ``XXX1``, ``XXX2``, etc. (or just ``XXX``, if +there's only one) [#fgpio]_. For instance, on the Maple's +microcontroller (the STM32F103RBT6), there are two ADCs. +Consequently, in ``adc.h``, there are declarations for dealing with +ADC devices one and two:: + + extern const adc_dev *ADC1; + extern const adc_dev *ADC2; + +In general, each device needs to be initialized before it can be used. +libmaple provides this initialization routine for each peripheral +``xxx``; its name is ``xxx_init()``. These initialization routines +turn on the clock to a device, and restore its register values to +their default settings. Here are a few examples:: + + /* From dma.h */ + void dma_init(dma_dev *dev); + + /* From gpio.h */ + void gpio_init(gpio_dev *dev); + void gpio_init_all(void); + +Note that, sometimes, there will be an additional initialization +routine for all available peripherals of a certain kind. + +Many peripherals also need additional configuration before they can be +used. These functions are usually called something along the lines of +``xxx_enable()``, and often take additional arguments which specify a +particular configuration for the peripheral. Some examples:: + + /* From usart.h */ + void usart_enable(usart_dev *dev); + + /* From i2c.h */ + void i2c_master_enable(i2c_dev *dev, uint32 flags); + +After you've initialized, and potentially enabled, your peripheral, it +is now time to begin using it. The file ``xxx.h`` contains other +convenience functions for dealing with xxx devices. For instance, +here are a few from ``adc.h``:: + + void adc_set_sample_rate(const adc_dev *dev, adc_smp_rate smp_rate); + uint32 adc_read(const adc_dev *dev, uint8 channel); + +We aim to enable libmaple's users to interact with peripherals through +devices as much as possible, rather than having to break the +abstraction and consider individual registers. However, there will +always be a need for low-level access. To allow for that, libmaple +provides *register maps* as a consistent set of names and abstractions +for dealing with registers and their bits. + +.. _libmaple-overview-regmaps: + +Register Maps +------------- + +A *register map* is just a C struct which names and provides access to +a peripheral's registers. These registers are usually mapped to +contiguous regions of memory (though at times unusable or reserved +regions exist between a peripheral's registers). Here's an example +register map, from ``dac.h`` (``__io`` is just libmaple's way of +saying ``volatile`` when referring to register values):: + + /** DAC register map. */ + typedef struct dac_reg_map { + __io uint32 CR; /**< Control register */ + __io uint32 SWTRIGR; /**< Software trigger register */ + __io uint32 DHR12R1; /**< Channel 1 12-bit right-aligned data + holding register */ + __io uint32 DHR12L1; /**< Channel 1 12-bit left-aligned data + holding register */ + __io uint32 DHR8R1; /**< Channel 1 8-bit left-aligned data + holding register */ + __io uint32 DHR12R2; /**< Channel 2 12-bit right-aligned data + holding register */ + __io uint32 DHR12L2; /**< Channel 2 12-bit left-aligned data + holding register */ + __io uint32 DHR8R2; /**< Channel 2 8-bit left-aligned data + holding register */ + __io uint32 DHR12RD; /**< Dual DAC 12-bit right-aligned data + holding register */ + __io uint32 DHR12LD; /**< Dual DAC 12-bit left-aligned data + holding register */ + __io uint32 DHR8RD; /**< Dual DAC 8-bit left-aligned data holding + register */ + __io uint32 DOR1; /**< Channel 1 data output register */ + __io uint32 DOR2; /**< Channel 2 data output register */ + } dac_reg_map; + + +There are two things to notice here. First, if RM0008 names a +register ``DAC_FOO``, then ``dac_reg_map`` has a field named ``FOO``. +So, the Channel 1 12-bit right-aligned data register (RM0008: +DAC_DHR12R1) is the ``DHR12R1`` field in a ``dac_reg_map``. Second, +if RM0008 describes a register as "Foo bar register", the +documentation for the corresponding field has the same description. +This consistency makes it easy to search for a particular register, +and, if you see one used in a source file, to feel sure about what's +going on just based on its name. + +So let's say you've included ``xxx.h``, and you want to mess with some +particular register. What's the name of the ``xxx_reg_map`` variable +you want? That depends on if there's more than one xxx or not. If +there's only one xxx, then libmaple guarantees there will be a +``#define`` that looks like like this:: + + #define XXX_BASE ((xxx_reg_map*)0xDEADBEEF) + +That is, you're guaranteed there will be a pointer to the (only) +``xxx_reg_map`` you want, and it will be called +``XXX_BASE``. (``0xDEADBEEF`` is the register map's *base address*, or +the fixed location in memory where the register map begins). Here's a +concrete example from ``dac.h``:: + + #define DAC_BASE ((dac_reg_map*)0x40007400) + +How can you use these? This is perhaps best explained by example. + +* In order to write 2048 to the channel 1 12-bit left-aligned data + holding register (RM0008: DAC_DHR12L1), you could write:: + + DAC_BASE->DHR12L1 = 2048; + +* In order to read the DAC control register, you could write:: + + uint32 cr = DAC_BASE->CR; + +The microcontroller takes care of converting reads and writes from a +register's IO-mapped memory regions into reads and writes to the +corresponding hardware registers. + +That covers the case where there's a single xxx peripheral. If +there's more than one (say, if there are *n*), then ``xxx.h`` provides +the following:: + + #define XXX1_BASE ((xxx_reg_map*)0xDEADBEEF) + #define XXX2_BASE ((xxx_reg_map*)0xF00DF00D) + ... + #define XXXn_BASE ((xxx_reg_map*)0x13AF1AB5) + +Here's a concrete example from ``adc.h``:: + + /** ADC1 register map base pointer. */ + #define ADC1_BASE ((adc_reg_map*)0x40012400) + /** ADC2 register map base pointer. */ + #define ADC2_BASE ((adc_reg_map*)0x40012800) + /** ADC3 register map base pointer. */ + #define ADC3_BASE ((adc_reg_map*)0x40013C00) + +In order to read from the ADC1's regular data register (where the +results of ADC conversion are stored), you might write:: + + uint32 converted_result = ADC1->DR; + +Register Bit Definitions +------------------------ + +In ``xxx.h``, there will also be a variety of #defines for dealing +with interesting bits in the xxx registers, called *register bit +definitions*. These are named according to the scheme +``XXX_REG_FIELD``, where "``REG``" refers to the register, and +"``FIELD``" refers to the bit or bits in ``REG`` that are special. + +.. TODO image of the bit layout of a DMA_CCR register + +Again, this is probably best explained by example. Each Direct Memory +Access (DMA) controller's register map has a certain number of channel +configuration registers (RM0008: DMA_CCRx). In each of these channel +configuration registers, bit 14 is called the ``MEM2MEM`` bit, and +bits 13 and 12 are the priority level (``PL``) bits. Here are the +register bit definitions for those fields:: + + /* From dma.h */ + + #define DMA_CCR_MEM2MEM_BIT 14 + #define DMA_CCR_MEM2MEM BIT(DMA_CCR_MEM2MEM_BIT) + #define DMA_CCR_PL (0x3 << 12) + #define DMA_CCR_PL_LOW (0x0 << 12) + #define DMA_CCR_PL_MEDIUM (0x1 << 12) + #define DMA_CCR_PL_HIGH (0x2 << 12) + #define DMA_CCR_PL_VERY_HIGH (0x3 << 12) + +Thus, to check if the ``MEM2MEM`` bit is set in DMA controller 1's +channel configuration register 2 (RM0008: DMA_CCR2), you can write:: + + if (DMA1_BASE->CCR2 & DMA_CCR_MEM2MEM) { + /* MEM2MEM is set */ + } + +Certain register values occupy multiple bits. For example, the +priority level (PL) of a DMA channel is determined by bits 13 and 12 +of the corresponding channel configuration register. As shown above, +libmaple provides several register bit definitions for masking out the +individual PL bits and determining their meaning. For example, to +check the priority level of a DMA transfer, you can write:: + + switch (DMA1_BASE->CCR2 & DMA_CCR_PL) { + case DMA_CCR_PL_LOW: + /* handle low priority case */ + case DMA_CCR_PL_MEDIUM: + /* handle medium priority case */ + case DMA_CCR_PL_HIGH: + /* handle high priority case */ + case DMA_CCR_PL_VERY_HIGH: + /* handle very high priority case */ + } + +Of course, before doing that, you should check to make sure there's +not already a device-level function for performing the same task! + +What Next? +---------- + +After you've read this page, you can proceed to the :ref:`libmaple API +listing `. From there, you can read documentation and +follow links to the current source code for those files on `libmaple's +Github page `_. + +.. rubric:: Footnotes + +.. [#fgpio] For consistency with RM0008, GPIO ports are given letters + instead of numbers (``GPIOA`` and ``GPIOB`` instead of + ``GPIO1`` and ``GPIO2``, etc.). diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 5c79d41..beba54d 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -41,9 +41,9 @@ correct version for your operating system: The package bundles together a compiler, an upload utility, a software library, and a simple GUI text editor. All this software is `free and -open `_; we are grateful to the `Arduino +open `_; we are grateful to the `Arduino `_, `CodeSourcery -`_, `GNU `_, and +`_, `GNU `_, and `OpenMoko `_ developers, as well as many others, who allow us to reuse their software. diff --git a/source/pwm.rst b/source/pwm.rst index 1a8f4df..1144d55 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -26,7 +26,7 @@ documentation ` for more information. Note that unlike the Arduino, the Maple does not have PWM functionality on pin D10; all other pins are :ref:`compatible -`. +`. The following table shows which timer can generate which PWM outputs. See the :ref:`pin mapping table ` to diff --git a/source/specs.rst b/source/specs.rst deleted file mode 100644 index 4972a83..0000000 --- a/source/specs.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _specs: - -.. _specs-Technical-Specifications: - -================================ -Maple's Technical Specifications -================================ - - * STM32 F103RB: a **32-bit** ARM Cortex M3 microprocessor - * Clock Speed: **72 MHz** - * Operating Voltage: 3.3V - * Input Voltage (recommended): 3.0V-12V - * 39 Digital I/O Pins (:ref:`GPIO `) - * 16 Analog Input Pins - * 12-bit **ADC** resolution (:ref:`ADC `) - * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) - * Dedicated **USB** port for programming and communications (:ref:`USB`) - * External **JTAG** interface (:ref:`USB `) - * **128 Flash** and **20KB SRAM** - * 64 Channel nested vector interrupt handler (including external interrupt on GPIO’s) - * Integrated **SPI** (:ref:`SPI`) - * Integrated **I2C** (:ref:`I2C`) - * 7 Channels of Direct Memory Access (DMA) - * 3 **USART** divices (:ref:`USART `) - * Four 4-channel Timers (:ref:`Timers `) - * Supplies up to 800mA @ 3.3v - * Support for low power and sleep modes (<500uA) - * Dimensions are 2.05″x2.1″ - diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 9146ebe..2151171 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -40,17 +40,17 @@ My 5v peripheral doesn't work! (I2C, SPI, USART, etc) ----------------------------------------------------- Yup, the Maple is a 3.3v board. You may need to use a level -converter. See the :ref:`compatibility `, :ref:`GPIO -`, or other :ref:`hardware specific documentation -` for more information. +converter. See the :ref:`Arduino Compatibility +`, :ref:`GPIO `, or other :ref:`hardware +specific documentation ` for more information. The reset and D38/serial buttons don't seem to work reliably! ------------------------------------------------------------- -A few rev3 boards shipped in May-June 2010 may have had unreliable -buttons; see the :ref:`errata page ` for details. `We're -happy to replace these for you `_\ ! - +A few Maple Rev3 boards shipped in May-June 2010 may have had +unreliable buttons; see the :ref:`errata page ` for +details. `We're happy to replace these for you +`_\ ! .. _troubleshooting-ide-install: diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index a173146..8b81e75 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -9,7 +9,9 @@ This is a tutorial for using the Maple with a standard Unix toolchain (``make``, ``gcc``, etc.). It's not necessary to do this in order to program the Maple; you can always :ref:`install the Maple IDE -` instead. +` instead. This document is intended for users who +are comfortable using C or C++ and would like to use :ref:`libmaple` +directly. You'll need a Maple board, a Mini-B USB cable, a functional computer, and root (or Administrator) access to that computer. This guide @@ -100,7 +102,7 @@ in `Python `_, and requires the `PySerial $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up This step is fairly straightforward: do a git clone of the `libmaple -repository `_ to some directory, +repository `_ to some directory, then download and extract the ARM compiler toolchain. The :file:`arm/bin/` directory will need to be added to ``PATH``; you @@ -169,9 +171,9 @@ You will need the following tools\ [#fpackman]_ to get started: `_. If you're in a hurry, you can steal a dfu-util binary from a program - called `Openmoko Flasher - `_. To - do this, first `download Openmoko Flasher + called `OpenMoko Flasher + `_. To + do this, first `download OpenMoko Flasher `_, then copy the OpenMoko application into your :file:`/Applications` folder (or wherever you like). Let's pretend you saved the .app to the directory @@ -292,11 +294,11 @@ If it all works out, you should end up seeing something like this:: 21824 200 552 22576 5830 build/maple.out Flash build -Woo! It worked. The ``dec`` field at the end gives the total program -size in bytes. The long listing of object files above the ``Final -Size`` helps to identify bloated code. As you write larger projects, -you may find that they use too much space. If that happens, the -file-by-file listing will help you track down the culprits. +The ``dec`` field at the end gives the total program size in +bytes. The long listing of object files above the ``Final Size`` helps +to identify bloated code. As you write larger projects, you may find +that they use too much space. If that happens, the file-by-file +listing will help you track down the culprits. .. _toolchain-upload: diff --git a/source/usb.rst b/source/usb.rst index 0468618..f040034 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -34,7 +34,7 @@ second problem is the use of :ref:`perpetual bootloader mode Recommended Reading ------------------- -* `USB in a Nutshell `_, an overview from Beyond Logic +* `USB in a Nutshell `_, an overview from Beyond Logic * `USB made simple `_, an illustrated series of articles on USB * The `USB 2.0 Specification `_ (`direct link `_) * `Embedded USB - a brief tutorial `_ -- cgit v1.2.3 From ff0706b87a806451fe0f3a48e5dab8d83cf3e6d9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 25 Apr 2011 18:13:47 -0400 Subject: Docs tweaks. Blocking fixes for 0.0.10; other changes. --- source/conf.py | 2 +- source/lang/api/serial.rst | 8 ++++---- source/libs/servo.rst | 2 ++ 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/source/conf.py b/source/conf.py index f232b7c..baadccb 100644 --- a/source/conf.py +++ b/source/conf.py @@ -59,7 +59,7 @@ copyright = u'2010, LeafLabs, LLC' # The short X.Y version. version = '0.0' # The full version, including alpha/beta/rc tags. -release = '0.0.9' +release = '0.0.10' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst index fadac34..417063d 100644 --- a/source/lang/api/serial.rst +++ b/source/lang/api/serial.rst @@ -12,8 +12,8 @@ devices. Introduction ------------ -.. FIXME remove Maple-specific documentation -.. FIXME Serial4, Serial5 updates for high-density devices +.. FIXME [Maple-specific values] +.. FIXME [0.0.10] Serial4, Serial5 updates for high-density devices The Maple has three serial ports (also known as a UARTs or USARTs): ``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the @@ -90,7 +90,7 @@ means that you can use any of these functions on any of ``Serial1``, .. cpp:function:: HardwareSerial::flush() - Removes the contents of the Serial's associated USART RX FIFO. + Throw away the contents of the serial port's receiver (RX) buffer. That is, clears any buffered characters, so that the next character read is guaranteed to be new. @@ -213,7 +213,7 @@ the USB port on the Maple board (for that, use :ref:`SerialUSB `). Thus, to use these pins to communicate with your personal computer, you will need an additional USB-to-serial adapter. -.. TODO LATER port these examples over +.. FIXME [0.1.0] port these examples over .. Examples .. -------- diff --git a/source/libs/servo.rst b/source/libs/servo.rst index f92fd91..475f7dd 100644 --- a/source/libs/servo.rst +++ b/source/libs/servo.rst @@ -6,6 +6,8 @@ Servo ======= +.. FIXME [0.0.10] this is out of date + This documents the Servo library for controlling RC servomotors. It is implemented as a thin layer over the built-in :ref:`timer peripherals `. -- cgit v1.2.3 From 1b12488ce8b7c69968709b0c1c17975e519b0f5e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 25 Apr 2011 21:23:00 -0400 Subject: Better debug port support. - gpio.h: afio_mapr_swj_config() renamed afio_cfg_debug_ports() - [new] wirish_debug.h: disableDebugPorts(), enableDebugPorts() - Maple, Maple Native, and Maple RET6 PIN_MAPs are now larger by 5, have mappings for the extra JTAG/SW pins. Documentation was updated appropriately. --- source/hardware/maple.rst | 83 +++++++++++------------------------ source/jtag.rst | 37 +++++++++------- source/lang/api/board-values.rst | 22 +++++++++- source/lang/api/disabledebugports.rst | 31 +++++++++++++ source/lang/api/enabledebugports.rst | 31 +++++++++++++ 5 files changed, 129 insertions(+), 75 deletions(-) create mode 100644 source/lang/api/disabledebugports.rst create mode 100644 source/lang/api/enabledebugports.rst diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 44a5238..1fa4f3f 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -40,7 +40,7 @@ Identifying your Rev We went through three versions ("Revs") of the Maple hardware: Rev 1, Rev 3, and Rev 5 [#frev2_4]_; Rev 5, the final design, is currently on sale. The following sections will help you to help you identify your -Rev. Known issues are listed in the :ref:`errata `. +Rev. Rev 5 ^^^^^ @@ -123,46 +123,38 @@ at the command line with :: $ git clone git://github.com/leaflabs/maple.git -.. _maple-errata: +.. _maple-failure-modes: -Errata ------- - -This section lists known issues and warnings for each revision of the -Maple board. The failure modes aren't design errors, but are easy ways -to break or damage your board permanently. For a list of differences -between the Maple and Arduinos, see the :ref:`Arduino Compatibility -reference `. - -The errata are grouped by Maple version ("Rev"). - -Maple Rev 5 -^^^^^^^^^^^ - -Known issues: +Failure Modes +------------- -* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the - corresponding "AIN" is missing from its silkscreen. - -* **GPIO 39-43 not configured**: this is really more of a software - "TODO" item. Some of the JTAG header pins are numbered 39-43. These - STM32 pins are indeed fully functional :ref:`GPIO ` when a - :ref:`JTAG ` device is not connected, but we have not enabled - them in software and thus they can not be accessed with the regular - :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. - -Potential failure modes: +The following known failure modes apply to all Maple versions. The +failure modes aren't design errors, but are easy ways to break or +damage your board permanently. * **High voltage on non-tolerant pins**: not all header pins are 5V compatible; so e.g. connecting certain serial devices in the wrong way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table ` details which pins are 5V-tolerant. -Maple Rev 3 -^^^^^^^^^^^ +Errata +------ + +This section lists known issues and warnings for each revision of the +Maple board. +Rev 5 +^^^^^ Known issues: +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on + boards sold in during Fall 2010, the corresponding "AIN" is missing + from its silkscreen. This mistake was fixed in later manufacturing + runs. + +Rev 3 +^^^^^ + * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 have questionable RESET and BUT buttons. @@ -180,7 +172,7 @@ Known issues: remover we used is "Precision Electronics Cleaner" from RadioShack, which is "Safe on most plastics" and contains Dipropylene glycol monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol - methyl ether acetate (really?), and carbon dioxide. + methyl ether acetate, and carbon dioxide. * **Resistors on pins 0 and 1**: these header pins, which are RX/TX on USART2 (:ref:`Serial2 `), have resistors in-line @@ -192,13 +184,6 @@ Known issues: designs, where they appear to protect the USB-Serial converter from TTL voltage on the headers. -* **GPIO 39-43 not configured**: this is really more of a software - "TODO" item. Some of the JTAG header pins are numbered 39-43. These - STM32 pins are indeed fully functional :ref:`GPIO ` when the a - :ref:`JTAG ` device is not connected, but we have not enabled - them in software and thus they can not be accessed with the regular - :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. - * **Silkscreen Errors**: the silkscreen on the bottom indicated PWM functionality on pin 25 and listen the external header GND pin as number 38 (actually 38 is connected to the BUT button). We manually @@ -207,17 +192,8 @@ Known issues: * **PWM Marketing Mistake**: We originally sold the Maple advertising 22 channels of 16-bit hardware PWM; actually the Maple only has 15. -Potential failure modes: - -* **TTL voltage on non-tolerant pins**: not all header pins are 5V - compatible; connecting certain serial devices in the wrong way could - over voltage the pins. The :ref:`Pin-Mapping Mega Table - ` details which pins are 5V-tolerant. - -Maple Rev 1 -^^^^^^^^^^^ - -Known issues: +Rev 1 +^^^^^ * **ADC noise**: generally very high, in particular when the USB port is being used for communications (including keep-alive pings when @@ -248,14 +224,7 @@ Known issues: `_. * **PWM Marketing Mistake**: We originally sold the Maple advertising - 22 channels of 16-bit hardware PWM; actually the Maple only has 15. - -Potential failure modes: - -* **TTL voltage on non-tolerant pins**: not all header pins are 5v - compatible; connecting certain serial devices in the wrong way could - over voltage the pins. The :ref:`Pin-Mapping Mega Table - ` details which pins are 5V-tolerant. + 22 channels of 16-bit hardware PWM; the correct number is 15. Recommended Reading ------------------- diff --git a/source/jtag.rst b/source/jtag.rst index 858021e..cc6d34a 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -1,11 +1,12 @@ +.. highlight:: cpp + .. _jtag: ====== JTAG ====== -.. TODO update adapter schematic, add information on using it with our -.. devices. +.. FIXME update adapter schematic, add better information JTAG is an interface for low-level debugging of digital devices. It gives instruction by instruction control over the microprocessor and @@ -37,32 +38,36 @@ Wiring Diagram to connect a standard 20-pin ARM JTAG device to the 8-pin JTAG port on the Maple. -The Maple has holes for a 8-pin JTAG header but that header is not -soldered on by default. If you know ahead of time that you'll be -needing it, and you order `straight from LeafLabs -`_, add a comment to your order and we can -probably solder one on for no charge. Otherwise, you can simply -attach standard 0.1" pitch male header pins (either the exact 4x2 -block or two 4-pin pieces of breakaway straight header). For a one-off -usage hack, the header can be jammed in the holes and twisted to -ensure electrical contact. +The Maple has holes for a 8-pin JTAG header, but that header is not +soldered on. To use JTAG, simply solder on standard 0.1" pitch male +header pins (either the exact 4 by 2 block, or two 4-pin pieces of +straight breakaway header). Compatible Devices ------------------ We have had good experience with the `Olimex ARM-USB-OCD `_ device, which costs -about 55 euro plus shipping (as of November 2010). +about €55 plus shipping (as of April 2011). + +Function Reference +------------------ + +You can disable or enable the JTAG and Serial Wire debugging ports in +software using the ``disableDebugPorts()`` and ``enableDebugPorts()`` +functions. + +* :ref:`lang-disabledebugports` +* :ref:`lang-enabledebugports` Recommended Reading ------------------- * `Wikipedia Article on Joint Test Action Group (JTAG) `_ -* `STM32/gdb/OpenOCD HOWTO `_ +* `STM32, GDB, OpenOCD How To `_ * STMicro documentation for STM32F103RB microcontroller: * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) -* There's a `thread on JTAG - `_ in our `forum`_ - which you may find useful. +* `LeafLabs Wiki JTAG How To `_ +* `Forum thread on JTAG `_ diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst index d6d78f6..e274163 100644 --- a/source/lang/api/board-values.rst +++ b/source/lang/api/board-values.rst @@ -84,8 +84,25 @@ Constants * ``BOARD_NR_USARTS``: Number of serial ports on the board. This number includes UARTs 4 and 5 if they are available. +.. _lang-board-values-debug: + +- Debug (JTAG, SW-Debug) related constants: ``BOARD_JTMS_SWDIO_PIN``, + ``BOARD_JTCK_SWCLK_PIN``, ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``, + and ``BOARD_NJTRST_PIN``. + + These constants are the pin numbers for :ref:`GPIOs ` used by + the :ref:`jtag` and Serial-Wire Debug peripherals. Except for the + Maple Mini, these pins are usually reserved for special purposes by + default (i.e., they are in :ref:`boardUsedPins + `). However, they can be used as + ordinary GPIOs if you call the :ref:`lang-disabledebugports` + function. (Be careful with this on the Maple, as writing to + ``BOARD_NJTRST_PIN`` may cause your board to reset!). + .. _lang-board-values-pwm-pins: + .. _lang-board-values-adc-pins: + .. _lang-board-values-used-pins: Pin Arrays @@ -94,8 +111,7 @@ Pin Arrays Some :ref:`arrays ` of pin numbers are available which you can use to find out certain important information about a given pin. -.. TODO add links to the board-specific hardware information on what -.. are in these arrays +.. TODO [0.1.0] links to board-specific hardware information - ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM ` output, using :ref:`pwmWrite() `. The total @@ -159,3 +175,5 @@ See Also - :ref:`lang-toggleled` - :ref:`lang-analogread` - :ref:`lang-pwmwrite` +- :ref:`lang-enabledebugports` +- :ref:`lang-disabledebugports` diff --git a/source/lang/api/disabledebugports.rst b/source/lang/api/disabledebugports.rst new file mode 100644 index 0000000..43ac337 --- /dev/null +++ b/source/lang/api/disabledebugports.rst @@ -0,0 +1,31 @@ +.. highlight:: cpp + +.. _lang-disabledebugports: + +disableDebugPorts() +=================== + +Used to disable the JTAG and Serial Wire debugging ports. + +Library Documentation +--------------------- + +.. doxygenfunction:: disableDebugPorts + +Example +------- + + :: + + void setup() { + disableDebugPorts(); + } + + void loop() { + // Now you can use the debug port pins as ordinary pins + } + +See Also +-------- + +* :ref:`lang-enabledebugports` diff --git a/source/lang/api/enabledebugports.rst b/source/lang/api/enabledebugports.rst new file mode 100644 index 0000000..bee2b0a --- /dev/null +++ b/source/lang/api/enabledebugports.rst @@ -0,0 +1,31 @@ +.. highlight:: cpp + +.. _lang-enabledebugports: + +enableDebugPorts() +================== + +Used to enable the JTAG and Serial Wire debugging ports. + +Library Documentation +--------------------- + +.. doxygenfunction:: enableDebugPorts + +Example +------- + + :: + + void setup() { + enableDebugPorts(); + // Now you can debug using JTAG and SW-Debug + } + + void loop() { + } + +See Also +-------- + +* :ref:`lang-disabledebugports` -- cgit v1.2.3 From 5606a05e2992043387a9cf995365db7e1dc83cff Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 26 Apr 2011 03:27:10 -0400 Subject: 0.0.10 Documentation checkpoint. The vast majority of the Maple-specific values have been pulled out of the higher-level overview pages and replaced with refs into documents under /docs/source/hardware/. Much of the work that's left to be done in this regard is labeled with versioned TODO and FIXME comments. Suggestions from StephenFromNYC and gbulmer were incorporated from this forum thread: http://forums.leaflabs.com/topic.php?id=703 --- source/adc.rst | 65 ++++---- source/arduino-cc-attribution.txt | 9 ++ source/bootloader.rst | 7 +- source/external-interrupts.rst | 119 ++++---------- source/gpio.rst | 114 +++++--------- source/hardware/maple-ret6.rst | 276 +++++++++++++++++++++++++++++++++ source/hardware/maple.rst | 210 ++++++++++++++++++++++--- source/i2c.rst | 40 ++--- source/index.rst | 12 +- source/jtag.rst | 26 +++- source/lang/api/abs.rst | 3 +- source/lang/api/analogread.rst | 65 ++++---- source/lang/api/analogwrite.rst | 23 ++- source/lang/api/attachinterrupt.rst | 57 +++---- source/lang/api/bit.rst | 12 +- source/lang/api/bitclear.rst | 13 +- source/lang/api/bitread.rst | 11 +- source/lang/api/bitset.rst | 9 +- source/lang/api/bitwrite.rst | 7 +- source/lang/api/board-values.rst | 5 +- source/lang/api/cc-attribution.txt | 9 -- source/lang/api/constants.rst | 2 +- source/lang/api/constrain.rst | 5 +- source/lang/api/cos.rst | 6 +- source/lang/api/delay.rst | 6 +- source/lang/api/delaymicroseconds.rst | 11 +- source/lang/api/detachinterrupt.rst | 8 +- source/lang/api/digitalread.rst | 39 ++--- source/lang/api/digitalwrite.rst | 39 ++--- source/lang/api/hardwaretimer.rst | 95 +++++++++++- source/lang/api/highbyte.rst | 6 +- source/lang/api/loop.rst | 3 +- source/lang/api/lowbyte.rst | 2 +- source/lang/api/map.rst | 2 +- source/lang/api/max.rst | 5 +- source/lang/api/micros.rst | 2 +- source/lang/api/millis.rst | 2 +- source/lang/api/min.rst | 3 +- source/lang/api/pinmode.rst | 8 +- source/lang/api/pow.rst | 5 +- source/lang/api/pwmwrite.rst | 14 +- source/lang/api/random.rst | 6 +- source/lang/api/randomseed.rst | 2 +- source/lang/api/serial.rst | 50 ++---- source/lang/api/setup.rst | 2 +- source/lang/api/sin.rst | 3 +- source/lang/api/sq.rst | 3 +- source/lang/api/tan.rst | 3 +- source/lang/api/volatile.rst | 8 +- source/lang/cc-attribution.txt | 9 +- source/lang/cpp/arithmetic.rst | 2 +- source/lang/cpp/array.rst | 6 +- source/lang/cpp/assignment.rst | 2 +- source/lang/cpp/bitshift.rst | 3 +- source/lang/cpp/bitwisemath.rst | 3 +- source/lang/cpp/boolean.rst | 3 +- source/lang/cpp/booleanvariables.rst | 6 +- source/lang/cpp/break.rst | 5 +- source/lang/cpp/byte.rst | 3 +- source/lang/cpp/bytecast.rst | 8 +- source/lang/cpp/char.rst | 10 +- source/lang/cpp/charcast.rst | 6 +- source/lang/cpp/comments.rst | 5 +- source/lang/cpp/comparison.rst | 3 +- source/lang/cpp/compoundarithmetic.rst | 3 +- source/lang/cpp/compoundbitwise.rst | 1 - source/lang/cpp/const.rst | 6 +- source/lang/cpp/continue.rst | 4 +- source/lang/cpp/curly-braces.rst | 5 +- source/lang/cpp/define.rst | 6 +- source/lang/cpp/double.rst | 4 +- source/lang/cpp/doublecast.rst | 2 +- source/lang/cpp/dowhile.rst | 3 +- source/lang/cpp/float.rst | 2 +- source/lang/cpp/floatcast.rst | 2 +- source/lang/cpp/for.rst | 4 +- source/lang/cpp/goto.rst | 3 +- source/lang/cpp/if.rst | 2 +- source/lang/cpp/include.rst | 4 +- source/lang/cpp/increment.rst | 2 +- source/lang/cpp/intcast.rst | 5 +- source/lang/cpp/longcast.rst | 2 +- source/lang/cpp/longlong.rst | 2 +- source/lang/cpp/modulo.rst | 2 +- source/lang/cpp/pointer.rst | 2 +- source/lang/cpp/return.rst | 3 +- source/lang/cpp/scope.rst | 2 +- source/lang/cpp/semicolon.rst | 5 +- source/lang/cpp/sizeof.rst | 2 +- source/lang/cpp/sqrt.rst | 3 +- source/lang/cpp/static.rst | 3 +- source/lang/cpp/string.rst | 3 +- source/lang/cpp/switchcase.rst | 4 +- source/lang/cpp/unsignedchar.rst | 5 +- source/lang/cpp/unsignedint.rst | 2 +- source/lang/cpp/unsignedlonglong.rst | 2 +- source/lang/cpp/variables.rst | 3 +- source/lang/cpp/void.rst | 4 +- source/lang/cpp/while.rst | 2 +- source/lang/unimplemented/notone.rst | 17 +- source/lang/unimplemented/tone.rst | 27 +--- source/language-index.rst | 17 +- source/language.rst | 65 ++++---- source/libmaple/api/systick.rst | 8 + source/libraries.rst | 176 ++++----------------- source/libs/servo.rst | 59 ++++++- source/libs/wire.rst | 104 +++++++++++++ source/maple-quickstart.rst | 14 +- source/pwm.rst | 31 +--- source/spi.rst | 10 +- source/timers.rst | 206 +++++++----------------- source/troubleshooting.rst | 4 - source/usart.rst | 19 ++- source/usb.rst | 54 +++---- 114 files changed, 1307 insertions(+), 1119 deletions(-) create mode 100644 source/arduino-cc-attribution.txt create mode 100644 source/hardware/maple-ret6.rst delete mode 100644 source/lang/api/cc-attribution.txt create mode 100644 source/libs/wire.rst diff --git a/source/adc.rst b/source/adc.rst index b943808..af613cc 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -6,23 +6,12 @@ Analog-Digital Conversion is the process of reading a physical voltage as a number. The Maple has a large number of pins which are capable of -taking 12-bit ADC measurements, which means that voltages from ground -to +3.3v are read as numbers from 0 to 4095; this corresponds to a +taking 12-bit ADC measurements, which means that voltages from 0 to +3.3V are read as numbers from 0 to 4095. This corresponds to a theoretical sensitivity of just under 1 millivolt. In reality, a -number of factors introduce noise and bias into this reading and a +number of factors introduce noise and bias into this reading, and a number of techniques must be used to get good precision and accuracy. -.. compound:: - - The header pins with ADC functionality (marked as "AIN" on the - silkscreen) are: - - D0, D1, D2, D3, D10, D11, D12, D13, D15, D16, D17, D18, D19, D20, D27, D28 - - Note that pins 3, 27, and 28 are not marked AIN on the silkscreen - for Maple revisions through Rev 5, however, they **do work** as - analog input pins. - .. contents:: Contents :local: @@ -31,13 +20,15 @@ number of techniques must be used to get good precision and accuracy. Noise and Bias -------------- +.. FIXME [0.0.10, Maple-specific] + The biggest issues with analog-digital conversion are noise and bias. With the Maple, we have tried to isolate the ADC pins and traces from -strong noise sources but there are always trade--offs between noise, +strong noise sources, but there are always trade--offs between noise, additional functionality, cost, and package size. The 6 ADC pins in a bank (D15--D20) generally have the least -noise and should be used for fine measurements. If the input voltage +noise, and should be used for fine measurements. If the input voltage changes relatively slowly, a number of samples can be taken in succession and averaged together, or the same voltage can even be sampled by multiple ADC pins at the same time. @@ -47,34 +38,40 @@ voltages that the sample is being compared against. In the case of the Maple, the high reference is |vcc| and the low reference is ground. This means that noise or fluctuations on either |vcc| or ground will affect the measurement. It also means that the voltage you are trying -to sample must be between ground and 3.3V. In the case of a variable -reading, it is best if the voltage varies over the entire range of -0--3.3V; otherwise, only a fraction of the sensitivity is being -leveraged. Resistor dividers and constant voltage diodes are basic -tools which can help bring a given voltage signal into the appropriate -range; opamps and other powered components can also be used. +to sample must be between ground and 3.3V. + +.. _adc-range: + +In the case of a variable reading, it is best if the voltage varies +over the entire range of 0--3.3V; otherwise, only a fraction of the +sensitivity is being leveraged. Some basic tools to accomplish this +are `resistor dividers +`_ and `Zener diodes +`_\ +. However, `operational amplifiers +`_ and other +powered components can also be used if greater precision is required. .. _adc-function-reference: Function Reference ------------------ -.. doxygenfunction:: analogRead - -.. doxygenfunction:: pinMode - -.. doxygenenum:: WiringPinMode +* :ref:`lang-analogread` +* :ref:`lang-pinmode` .. _adc-recommended-reading: Recommended Reading ------------------- -* `Wikipedia article on Analog-to-digital converter `_ - -* `Arduino Analog Input Tutorial `_ - -* STMicro documentation: +* `Wikipedia: Analog-to-Digital Converter + `_ +* `Arduino Analog Input Tutorial + `_ +* ST documentation: - * `Application Note on ADC Modes (pdf) `_ - * `Application Note on ADC Oversampling (pdf) `_ + * `Application Note on ADC Modes + `_ (PDF) + * `Application Note on ADC Oversampling + `_ (PDF) diff --git a/source/arduino-cc-attribution.txt b/source/arduino-cc-attribution.txt new file mode 100644 index 0000000..ad1c1e0 --- /dev/null +++ b/source/arduino-cc-attribution.txt @@ -0,0 +1,9 @@ +.. Included in all relevant files in order to satisfy the Arduino +.. CC Attribution-ShareAlike 3.0 License + +.. admonition:: License and Attribution + + Portions of this page were adapted from the `Arduino Reference + Documentation `_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License `_. diff --git a/source/bootloader.rst b/source/bootloader.rst index 85b2674..ec4fe73 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -1,8 +1,9 @@ .. highlight:: sh -===================== - Maple Bootloader(s) -===================== +.. _bootloader: + +Maple Bootloader(s) +=================== The firmware which allows the Maple to be reprogrammed via a USB connection. Every Maple board comes programmed with this by default, diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index b2cbbb1..ac065a4 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -6,73 +6,42 @@ External Interrupts =================== External interrupts can be used to trigger routines to run in response -to changes in voltage on a pin. Each GPIO pin on the Maple can be used -to detect transitions such as when the voltage goes from low to high, -or from high to low. This technique can be used to avoid unnecessary -polling of the state of a pin. +to changes in voltage on a pin. Each :ref:`GPIO pin ` can be +used to detect transitions, such as when the voltage goes from +:ref:`LOW ` to :ref:`HIGH `, +or from ``HIGH`` to ``LOW``. This can be used to avoid checking for +changes on a pin "manually" by waiting in a loop until the pin +changes. .. _contents: Contents :local: - Overview -------- External interrupts are often used to detect when events happen -outside of the microcontroller. These can be used to tell the Maple -when events happen, such as when a sensor has data ready to be read, -or when a button has been pushed. When such an event happens, an -interrupt is raised and the Maple can react to it with a preset -*interrupt handler*. - -Every GPIO pin on the Maple can be used as an external interrupt, -subject to certain constraints; there can be a maximum of 16 different -external interrupts set up at a time on the Maple. This is because the -external interrupt lines on the STM32 are multiplexed between GPIO -ports. In effect, this means that every pin on the Maple maps to a -certain EXTI line, and within that EXTI line, only one of the pins -that maps to it can be used as an external interrupt at a time. - -The following table shows which pins can be used on which lines. - -.. list-table:: - :widths: 1 1 - :header-rows: 1 - - * - EXTI Line - - Maple pins - * - EXTI0 - - 2, 15, 27 - * - EXTI1 - - 3, 16, 28 - * - EXTI2 - - 1, 17, 25 - * - EXTI3 - - 0, 18 - * - EXTI4 - - 10, 19 - * - EXTI5 - - 4, 13, 20 - * - EXTI6 - - 5, 12, 35 - * - EXTI7 - - 9, 11, 36 - * - EXTI8 - - 6, 14, 37 - * - EXTI9 - - 7, 25, 28 - * - EXTI10 - - 8, 26, 29 - * - EXTI11 - - 30 - * - EXTI12 - - 31 - * - EXTI13 - - 21, 32 - * - EXTI14 - - 22, 33 - * - EXTI15 - - 23, 34 +outside of the microcontroller. These can be used to tell Maple when +events happen, such as when a sensor has data ready to be read, or +when a button has been pushed. When such an event happens, an +interrupt is raised, and the Maple can react to it with a preset +*interrupt handler*, which is a function that gets called whenever the +event occurs. + +.. _external-interrupts-exti-line: + +Every GPIO pin can generate an external interrupt, subject to certain +constraints. There can be a maximum of 16 different external +interrupts set up at a time. This is because the external interrupt +lines on the STM32 are shared between GPIO ports. In effect, this +means that every pin on the Maple connects to what is called an *EXTI +line*, and within an EXTI line, only one of the pins that connects to +it can be used to detect external interrupts at a time. + +The EXTI Line Pin Map for your board lists which pins connect to which +EXTI lines: + +* :ref:`Maple ` +* :ref:`Maple RET6 Edition ` .. note:: @@ -80,40 +49,16 @@ The following table shows which pins can be used on which lines. desired pin to an input mode (e.g ``INPUT`` or ``INPUT_FLOATING``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``). - Function Reference ------------------ - :ref:`attachInterrupt() ` - :ref:`detachInterrupt() ` -Code example ------------- - -Blink the LED on every transition:: - - int pin = 13; - volatile int state = LOW; - - void setup() { - pinMode(pin, OUTPUT); - pinMode(0, INPUT_FLOATING); - attachInterrupt(0, blink, CHANGE); - } - - void loop() { - digitalWrite(pin, state); - } - - void blink() { - state = !state; - } - - Recommended Reading ------------------- -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) +* ST manual `RM0008 + `_ + (PDF), Chapter 9, "General-purpose and alternate-function I/Os", and + Chapter 10, "Interrupts and Events". diff --git a/source/gpio.rst b/source/gpio.rst index 0f9f4df..74be3d4 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -3,86 +3,54 @@ GPIO ==== -.. FIXME [Maple-specific values] +Each LeafLabs board comes with ready-to-use General Purpose +Input/Output (GPIO) pins, which are numbered starting from zero. +These numbers are listed on your board's silkscreen, next to where the +pin is broken out to a header. Many pins may additionally be used for +special features or peripheral functions. -The Maple features 38 ready-to-use general purpose input/output (GPIO) -pins for digital input/output, numbered D0 through D37. These numbers -correspond to the numeric values next to each header on the Maple -silkscreen. +.. contents:: Contents + :local: -Many of these pins may additionally be used for special features or -peripheral functions. This page documents those capabilities, by pin. +.. _gpio-pin-maps: -The current and voltage limitations have been copied over from the -STM32 datasheet (see the :ref:`Recommended Reading -` for a link). In particular, a number of -GPIO pins are 5V tolerant (which means that applying 5 volts to a pin -and reading it as input or allowing it to drain to ground will not -damage that pin), while some are not. +Pin Maps +-------- -.. contents:: Contents - :local: +The hardware documentation for your board lists each pin's +capabilities, by pin number: + +.. TODO [0.1.0] Uncomment Mini and Native GPIO links + +* :ref:`Maple ` +* :ref:`Maple RET6 Edition ` -.. _pin-mapping-mega-table: - -Pin Mapping Mega Table ----------------------- - -This table shows the available functionality on every GPIO pin, by -peripheral type. The "STM32" column refers to the port and number that -the header is connected to on the microcontroller. The "5V?" column -documents whether or not the pin is 5 volt tolerant (see above). - -.. TODO silkscreen pictures which let you know what each abbreviation -.. means, with links to the relevant documentation. - -.. csv-table:: - :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" - - "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" - "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" - "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" - "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" - "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" - "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" - "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" - "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" - "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" - "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" - "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" - "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" - "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" - "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" - "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" - "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" - "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" - "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" - "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" - "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" - "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" - "D21", "PC13", "-", "-", "-", "-", "-", "No" - "D22", "PC14", "-", "-", "-", "-", "-", "No" - "D23", "PC15", "-", "-", "-", "-", "-", "No" - "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" - "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" - "D26", "PC10", "-", "-", "-", "-", "-", "Yes" - "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" - "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" - "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" - "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" - "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBAL", "USART3_CK", "SPI2_NSS", "Yes" - "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" - "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" - "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" - "D35", "PC6", "-", "-", "-", "-", "-", "Yes" - "D36", "PC7", "-", "-", "-", "-", "-", "Yes" - "D37", "PC8", "-", "-", "-", "-", "-", "Yes" +.. * :ref:`Maple Mini ` +.. * :ref:`Maple Native ` + +The current and voltage limitations were determined using the STM32 +datasheets. In particular, only some GPIO pins are **5V tolerant**, +which means that applying 5 volts to a pin and reading it as input or +allowing it to drain to ground will not damage that pin. Connecting a +voltage higher than 3.3V to a non-5V tolerant pin may damage your +board. .. _gpio-modes: GPIO Modes ---------- +Each of the GPIO pins on a Maple board may be configured using +pinMode() to behave in a number of ways: as a digital output pin, +or as an analog input pin, etc., depending on the particular pin. + +A ``WiringPinMode`` value specifies the complete set of possible +configurations; not every pin can have all of these modes. For +example, on the Maple, pin 15 may have mode ``INPUT_ANALOG``, but not +``PWM``. See your :ref:`board's pin maps ` and its +silkscreen for more information on what functionality is available on +each pin. + .. doxygenenum:: WiringPinMode Function Reference @@ -105,7 +73,11 @@ Function Reference Recommended Reading ------------------- -STMicro documentation for STM32F103RB microcontroller: +* ST Documentation for the STM32F103 series of microcontrollers: - * `Datasheet `_ (pdf) * `Reference Manual `_ (pdf) + + * `Programming Manual + `_ + (PDF; assembly language and register reference) + diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst new file mode 100644 index 0000000..06dcaff --- /dev/null +++ b/source/hardware/maple-ret6.rst @@ -0,0 +1,276 @@ +.. highlight:: sh + +.. _maple-ret6: + +Maple RET6 Edition +================== + +.. contents:: Contents + :local: + +Technical Specifications +------------------------ + + * MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor + * Clock Speed: **72 MHz** + * Operating Voltage: 3.3V + * Input Voltage (recommended): 3V-12V + * 39 Digital I/O Pins (:ref:`GPIO `) + * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC `) + * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) + * Dedicated **USB** port for programming and communications (:ref:`USB`) + * External **JTAG** interface (:ref:`JTAG `) + * **512KB Flash** and **64KB SRAM** + * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) + * Integrated **SPI** (:ref:`SPI `) + * Integrated **I2C** (:ref:`I2C `) + * 12 Channels of Direct Memory Access (**DMA**) + * 3 **USART** and 2 **UART** devices (:ref:`USART `) + * Six 4-channel and two basic **timers** (:ref:`Timers `) + * Supplies up to 800mA @ 3.3v + * Support for low power and sleep modes (<500uA) + * Dimensions are 2.05″x2.1″ + +.. _maple-ret6-powering: + +Powering the Maple RET6 Edition +------------------------------- + +The Maple RET6 Edition's power source is determined by the header to +the left of the "LeafLabs" label on the silkscreen. The RET6 Edition +can be powered from the barrel jack connector, USB, or a LiPo battery. +We ship the RET6 Edition with a jumper on the USB selector. In order +to power it off of an alternative source, unplug the board, then move +the jumper to the desired selector before reconnecting power. + +You can also power the Maple via the pin labeled "Vin" on the lower +header. However, don't do this while simultaneously powering the +board from another source, or you could damage the it. + +Using the Built-in Battery Charger +---------------------------------- + +The RET6 Edition has a built-in LiPo battery charger. In order to use +it, put a jumper across the CHRG header on the power selection header +and across the USB, or EXT selectors, depending on whether you're +charging the battery via USB cable or barrel jack connector. The LED +labeled CHRG will light up while the battery is being charged. When +the battery is finished charging, the LED labeled DONE will also light +up. + +.. _maple-ret6-gpios: + +GPIO Information +---------------- + +The RET6 Edition features 38 ready-to-use general purpose input/output +(GPIO) pins for digital input/output, numbered ``D0`` through ``D37``. +These numbers correspond to the numeric values next to each header on +the Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are +available through use in combination with the +:ref:`lang-disabledebugports` function; see the :ref:`board-specific +debug pin constants ` for more information. + +.. TODO [0.1.0] silkscreen pictures which expand abbreviations + +.. _maple-ret6-pin-map-master: + +Master Pin Map +^^^^^^^^^^^^^^ + +.. TODO [0.0.10] Update from base Maple information + +This table shows the available functionality on every GPIO pin, by +peripheral type. The "STM32" column refers to the port and number that +the header is connected to on the microcontroller. The "5V?" column +documents whether or not the pin is 5 volt tolerant. + +.. csv-table:: + :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" + + "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" + "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" + "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" + "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" + "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" + "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" + "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" + "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" + "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" + "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" + "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" + "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" + "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" + "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" + "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" + "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" + "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" + "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" + "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" + "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" + "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" + "D21", "PC13", "-", "-", "-", "-", "-", "No" + "D22", "PC14", "-", "-", "-", "-", "-", "No" + "D23", "PC15", "-", "-", "-", "-", "-", "No" + "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" + "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" + "D26", "PC10", "-", "-", "-", "-", "-", "Yes" + "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" + "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" + "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" + "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" + "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes" + "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" + "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" + "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" + "D35", "PC6", "-", "-", "-", "-", "-", "Yes" + "D36", "PC7", "-", "-", "-", "-", "-", "Yes" + "D37", "PC8", "-", "-", "-", "-", "-", "Yes" + +.. TODO [0.0.10] Another table for the JTAG pins + +Timer Pin Map +^^^^^^^^^^^^^ + +.. TODO [0.0.10] Add Timer 5,6,7,8 information + +The following table shows what pins are associated with a particular +timer's capture/compare channels. + +.. csv-table:: + :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4 + :delim: | + + 1 | D6 | D7 | D8 | - + 2 | D2 | D3 | D1 | D0 + 3 | D12 | D11 | D27 | D28 + 4 | D5 | D9 | D14 | D24 + +.. _maple-ret6-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +` on the Maple RET6 Edition. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - 2, 15, 27 + * - EXTI1 + - 3, 16, 28 + * - EXTI2 + - 1, 17, 25 + * - EXTI3 + - 0, 18 + * - EXTI4 + - 10, 19 + * - EXTI5 + - 4, 13, 20 + * - EXTI6 + - 5, 12, 35 + * - EXTI7 + - 9, 11, 36 + * - EXTI8 + - 6, 14, 37 + * - EXTI9 + - 7, 25, 28 + * - EXTI10 + - 8, 26, 29 + * - EXTI11 + - 30 + * - EXTI12 + - 31 + * - EXTI13 + - 21, 32 + * - EXTI14 + - 22, 33 + * - EXTI15 + - 23, 34 + +.. _maple-ret6-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +.. FIXME [0.0.10] UART4 and UART5 information + +The Maple RET6 Edition has three serial ports (also known as a UARTs +or USARTs): ``Serial1``, ``Serial2``, and ``Serial3``. They +communicate using the pins summarized in the following table: + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | 7 | 8 | 6 | - | - + ``Serial2`` | 1 | 0 | 10 | 2 | 3 + ``Serial3`` | 29 | 30 | 31 | 32 | 33 + +Board-Specific Values +--------------------- + +.. TODO [0.0.10] + +Stub. + +Hardware Design Files +--------------------- + +The hardware schematics and board layout files are available in the +`Maple Github repository `_. Other +than the processor used, the design files for the Maple RET6 edition +are identical to the Maple Rev 5, which are in the ``maple-r5`` +subdirectory of the Maple repository. A schematic for a JTAG adapter +suitable for use with Maple is available in the ``jtagadapter`` +directory. + +From the Github repository main page, you can download the entire +repository by clicking the "Download" button. If you are familiar +with `git `_, you can also clone the repository +at the command line with :: + + $ git clone git://github.com/leaflabs/maple.git + +.. _maple-ret6-failure-modes: + +Failure Modes +------------- + +The following known failure modes apply to all Maple boards. The +failure modes aren't design errors, but are easy ways to break or +damage your board permanently. + +* **High voltage on non-tolerant pins**: not all header pins are 5V + compatible; so e.g. connecting certain serial devices in the wrong + way could over-voltage the pins. The :ref:`pin-mapping master table + ` details which pins are 5V-tolerant. + +Errata +------ + +This section lists known issues and warnings for the Maple RET6 Edition. + +* **DAC, UART4, UART5 GPIOs unavailable**: Pins related to the digital + to analog converter (DAC) and UARTs 4 and 5 are not broken out to + headers. The RET6 Edition's hardware layout is identical to that of + the Maple Rev 5, which wasn't designed for use with these + STM32F103RET6-only peripherals. + +Recommended Reading +------------------- + +* STMicro documentation for STM32F103RE microcontroller: + + * `Datasheet + `_ (PDF) + * `Reference Manual + `_ (PDF) + * `Programming Manual + `_ + (PDF; assembly language and register reference) diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 1fa4f3f..44848a7 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -1,6 +1,6 @@ .. highlight:: sh -.. _hardware-maple: +.. _maple: Maple ===== @@ -16,15 +16,14 @@ Technical Specifications * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V * 39 Digital I/O Pins (:ref:`GPIO `) - * 16 Analog Input Pins - * 12-bit **ADC** resolution (:ref:`ADC `) + * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC `) * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) - * Dedicated **USB** port for programming and communications (:ref:`USB`) - * External **JTAG** interface (:ref:`USB `) - * **128 Flash** and **20KB SRAM** + * Dedicated **USB** port for programming and communications (:ref:`USB `) + * External **JTAG** interface (:ref:`JTAG `) + * **128KB Flash** and **20KB SRAM** * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) - * Integrated **SPI** (:ref:`SPI`) - * Integrated **I2C** (:ref:`I2C`) + * Integrated **SPI** (:ref:`SPI `) + * Integrated **I2C** (:ref:`I2C `) * 7 Channels of Direct Memory Access (**DMA**) * 3 **USART** divices (:ref:`USART `) * Four 4-channel **timers** (:ref:`Timers `) @@ -32,7 +31,7 @@ Technical Specifications * Support for low power and sleep modes (<500uA) * Dimensions are 2.05″x2.1″ -.. _maple-hardware-identify-rev: +.. _maple-identify-rev: Identifying your Rev -------------------- @@ -79,7 +78,7 @@ have a light red silkscreen and a single pixelated leaf as a logo. :align: center :alt: Maple Rev 1 -.. _hardware-maple-powering: +.. _maple-powering: Powering the Maple ------------------ @@ -106,17 +105,174 @@ connector. The LED labeled CHRG will light up while the battery is being charged. When the battery is finished charging, the LED labeled DONE will also light up. +.. _maple-gpios: + +GPIO Information +---------------- + +The Maple features 38 ready-to-use general purpose input/output (GPIO) +pins for digital input/output, numbered ``D0`` through ``D37``. These +numbers correspond to the numeric values next to each header on the +Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are +available through use in combination with the +:ref:`lang-disabledebugports` function; see the :ref:`board-specific +debug pin constants ` for more information. + +.. TODO [0.1.0] silkscreen pictures which expand abbreviations + +.. _maple-pin-map-master: + +Master Pin Map +^^^^^^^^^^^^^^ + +This table shows the available functionality on every GPIO pin, by +peripheral type. The "STM32" column refers to the port and number that +the header is connected to on the microcontroller. The "5V?" column +documents whether or not the pin is 5 volt tolerant. + +.. csv-table:: + :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" + + "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" + "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" + "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" + "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" + "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" + "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" + "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" + "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" + "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" + "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" + "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" + "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" + "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" + "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" + "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" + "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" + "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" + "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" + "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" + "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" + "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" + "D21", "PC13", "-", "-", "-", "-", "-", "No" + "D22", "PC14", "-", "-", "-", "-", "-", "No" + "D23", "PC15", "-", "-", "-", "-", "-", "No" + "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" + "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" + "D26", "PC10", "-", "-", "-", "-", "-", "Yes" + "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" + "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" + "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" + "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" + "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes" + "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" + "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" + "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" + "D35", "PC6", "-", "-", "-", "-", "-", "Yes" + "D36", "PC7", "-", "-", "-", "-", "-", "Yes" + "D37", "PC8", "-", "-", "-", "-", "-", "Yes" + +.. TODO [0.0.10] JTAG pins + +Timer Pin Map +^^^^^^^^^^^^^ + +The following table shows what pins are associated with a particular +timer's capture/compare channels. + +.. csv-table:: + :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4 + :delim: | + + 1 | D6 | D7 | D8 | - + 2 | D2 | D3 | D1 | D0 + 3 | D12 | D11 | D27 | D28 + 4 | D5 | D9 | D14 | D24 + +.. _maple-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +` on the Maple. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - 2, 15, 27 + * - EXTI1 + - 3, 16, 28 + * - EXTI2 + - 1, 17, 25 + * - EXTI3 + - 0, 18 + * - EXTI4 + - 10, 19 + * - EXTI5 + - 4, 13, 20 + * - EXTI6 + - 5, 12, 35 + * - EXTI7 + - 9, 11, 36 + * - EXTI8 + - 6, 14, 37 + * - EXTI9 + - 7, 25, 28 + * - EXTI10 + - 8, 26, 29 + * - EXTI11 + - 30 + * - EXTI12 + - 31 + * - EXTI13 + - 21, 32 + * - EXTI14 + - 22, 33 + * - EXTI15 + - 23, 34 + +.. _maple-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +.. FIXME [0.0.10] UART4, UART5 + +The Maple has three serial ports (also known as a UARTs or USARTs): +``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the +pins summarized in the following table: + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | 7 | 8 | 6 | - | - + ``Serial2`` | 1 | 0 | 10 | 2 | 3 + ``Serial3`` | 29 | 30 | 31 | 32 | 33 + +Board-Specific Values +--------------------- + +.. TODO [0.0.10] + +Stub. + Hardware Design Files --------------------- The hardware schematics and board layout files are available in the -`Maple github repository `_. The +`Maple Github repository `_. The design files for Rev 1, Rev 3, and Rev 5 are respectively in the ``maple-r1``, ``maple-r3``, and ``maple-r5`` subdirectories. A schematic for a JTAG adapter suitable for use with Maple is available in the ``jtagadapter`` directory. -From the github repository main page, you can download the entire +From the Github repository main page, you can download the entire repository by clicking the "Download" button. If you are familiar with `git `_, you can also clone the repository at the command line with :: @@ -128,14 +284,14 @@ at the command line with :: Failure Modes ------------- -The following known failure modes apply to all Maple versions. The -failure modes aren't design errors, but are easy ways to break or -damage your board permanently. +The following are known failure modes. The failure modes aren't +design errors, but are easy ways to break or damage your board +permanently. * **High voltage on non-tolerant pins**: not all header pins are 5V compatible; so e.g. connecting certain serial devices in the wrong - way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table - ` details which pins are 5V-tolerant. + way could over-voltage the pins. The :ref:`pin-mapping master table + ` details which pins are 5V-tolerant. Errata ------ @@ -145,16 +301,18 @@ Maple board. Rev 5 ^^^^^ -Known issues: -* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on - boards sold in during Fall 2010, the corresponding "AIN" is missing +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on Rev + 5s manufactured during Fall 2010, the corresponding "AIN" is missing from its silkscreen. This mistake was fixed in later manufacturing runs. Rev 3 ^^^^^ +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the + corresponding "AIN" is missing from the Rev 3 silkscreen. + * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 have questionable RESET and BUT buttons. @@ -231,9 +389,15 @@ Recommended Reading * STMicro documentation for STM32F103RB microcontroller: - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (assembly language and register reference) + * `Datasheet + `_ + (PDF) + * `Reference Manual + `_ + (PDF) + * `Programming Manual + `_ + (PDF; assembly language and register reference) .. rubric:: Footnotes diff --git a/source/i2c.rst b/source/i2c.rst index 15190a8..e3d68c0 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -14,10 +14,8 @@ Higher level functionality, such as reading a particular register value, is achieved by writing to set the memory location then reading to pull out the data. -.. FIXME [Maple-specific values] - Note that the master/slave designation is on a message-by-message -basis. The Maple can act as both a master (messages initiated by user +basis. Maple can act as both a master (messages initiated by user code) and slave device (responding to requests via configurable interrupt handlers) at the same time. @@ -27,15 +25,15 @@ interrupt handlers) at the same time. Hardware/Circuit Design ----------------------- -The Maple has two |i2c| ports. Port 1 (I2C1) has SDA on header D9 and -SCL on D5; Port 2 (I2C2) has SDA on D30 and SCL on D29. +.. FIXME [0.0.10 add links to board-specific values] -The Maple reliably communicates with up to a 400kHz clock speed; this -doesn't translate into a 400kbps data rate except in extreme cases -because of addressing and protocol overhead. We have tested clock -speeds up to a megahertz and have had mixed results; in theory it -could be possible to achieve even higher rates, but signal quality -degrades rapidly and the bus becomes unreliable. +Maple boards have two |i2c| ports. Maples reliably communicate with +up to a 400kHz clock speed; this doesn't translate into a 400kbps data +rate except in extreme cases because of addressing and protocol +overhead. We have tested clock speeds up to a megahertz and have had +mixed results; in theory it could be possible to achieve even higher +rates, but signal quality degrades rapidly, and the bus becomes +unreliable. Proper wiring and pull-up resistor selection are essential when incorporating |i2c| into a circuit, especially with data rates above @@ -56,22 +54,16 @@ Wiring-style library is planned for a future release. SMBus ----- -The STM32 microcontroller has hardware support for SMBus; we simply -have not written software for it. The SMBAL line for I2C1 is on header -D4 and for I2C2 is on D31. +The STM32 microcontroller has hardware support for SMBus, but software +for it is not yet implemented. .. _i2c-recommended-reading: Recommended Reading ------------------- -* `i2c-bus.org `_ -* `Wikipedia Article on i2c `_ -* `Arduino i2c/TWI reference `_ -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Application Note on Advanced I2C Usage - `_ - (pdf) +* `I2C Bus `_ +* `Wikipedia: I2C `_ +* `Arduino I2C/TWI reference `_ +* ST `Application Note on Advanced I2C Usage + `_ (PDF) diff --git a/source/index.rst b/source/index.rst index 9db5ff0..8c7ac84 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,15 +1,12 @@ .. _index: -Maple Documentation Contents +LeafLabs Documentation Index ============================ -.. FIXME [Maple-specific values] errata page links to Maple - Welcome! This is the Maple documentation index. If you just bought a -Maple, you probably want to head to the :ref:`quickstart +Maple board, you probably want to head to the :ref:`quickstart `. If you're having problems, check out the -:ref:`troubleshooting ` :ref:`known problems -` pages. +:ref:`troubleshooting ` page. Have fun! @@ -59,7 +56,7 @@ Have fun! usb usart -.. _index-schematics: +.. _index-boards: **Board Hardware Documentation:** @@ -67,6 +64,7 @@ Have fun! :maxdepth: 1 hardware/maple.rst + hardware/maple-ret6.rst .. TODO write/include these upon Mini and Native release diff --git a/source/jtag.rst b/source/jtag.rst index cc6d34a..4151a53 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -6,7 +6,7 @@ JTAG ====== -.. FIXME update adapter schematic, add better information +.. FIXME [0.1.0] Updated adapter schematic, better information JTAG is an interface for low-level debugging of digital devices. It gives instruction by instruction control over the microprocessor and @@ -63,11 +63,21 @@ functions. Recommended Reading ------------------- -* `Wikipedia Article on Joint Test Action Group (JTAG) `_ -* `STM32, GDB, OpenOCD How To `_ -* STMicro documentation for STM32F103RB microcontroller: +* `Wikipedia Article on Joint Test Action Group (JTAG) + `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) -* `LeafLabs Wiki JTAG How To `_ -* `Forum thread on JTAG `_ +* `STM32, GDB, OpenOCD How To + `_ + +* `LeafLabs Wiki JTAG How To + `_ + +* `LeafLabs forum thread on JTAG + `_ + +* ST documentation: + + * Reference Manual `RM0008 + `_ + (PDF), Chapter 31, "Debug support", and Chapter 9, + "General-purpose and alternate function I/Os". diff --git a/source/lang/api/abs.rst b/source/lang/api/abs.rst index 0cc6c23..d9f1ca3 100644 --- a/source/lang/api/abs.rst +++ b/source/lang/api/abs.rst @@ -45,5 +45,4 @@ Arduino Compatibility Maple's implementation of ``abs()`` is compatible with Arduino. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/analogread.rst b/source/lang/api/analogread.rst index 7099b69..6665a94 100644 --- a/source/lang/api/analogread.rst +++ b/source/lang/api/analogread.rst @@ -20,32 +20,33 @@ Library Documentation Discussion ---------- -Reads the value from the specified analog pin. The Maple board -contains a 16-channel, 12-bit analog to digital converter. This means -that it will map input voltages between 0 and 3.3 volts into integer -values between 0 and 4095. This yields a resolution between readings -of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors +Reads the value from the specified analog pin. The Maple boards +contain 16-channel, 12-bit analog to digital converters. This means +that a converter will map input voltages between 0 and 3.3 volts into +integer values between 0 and 4095. However, a number of factors interfere with getting full accuracy and precision. For more information, see :ref:`adc`. Before calling analogRead() on a pin, that pin must first be -configured for analog input, using :ref:`lang-pinMode` (you only -have to do this once, so it's usually done in :ref:`lang-setup`\ ). +configured for analog input, using :ref:`lang-pinMode`. You only have +to do this once, so it's usually done in :ref:`lang-setup`\ . Parameter Discussion -------------------- -.. FIXME generalize Maple-specific information - The pin parameter is the number of the analog input pin to read from. -Header pins on the Maple with ADC functionality (marked as "AIN" on -the silkscreen) are: - - 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 - -Note that pins 3, 27, and 28 are not marked AIN on the silkscreen -for Maple revisions through Rev 5, however, they **do work** as -analog input pins. +The pins which support analog to digital conversion have ``AIN`` +listed underneath their number on your board's silkscreen. These pin +numbers are available to your program in the :ref:`boardADCPins +` board-specific array. The number of +pins which are capable of analog to digital conversion on your board +is given by the ``BOARD_NR_ADC_PINS`` constant. These values are +documented for each board in the :ref:`Board Hardware Documentation +` pages. + +.. note:: Pin 3 is not marked ``AIN`` on the silkscreen for Maple + revisions through Rev 5; however **it does work** as an analog + input pin. Note ---- @@ -55,7 +56,6 @@ returned by ``analogRead()`` will fluctuate due to a number of reasons (like the values of the other analog inputs, how close your hand is to the board, etc.) in a "random" way. - Example ------- @@ -78,7 +78,6 @@ Example // a serial monitor } - Arduino Compatibility --------------------- @@ -100,27 +99,21 @@ shift ` the value of a Maple readout by 2, like so:: // be aware that you're losing a lot of precision if you do this int adc_reading = analogRead(pin) >> 2; -.. FIXME Mention Native can do analogReference(), when it's time +.. FIXME [0.1.0] Mention that Native can do analogReference() On the Arduino, the input range and resolution can be changed using -their implementation of `analogReference() -`_\ . Because of the -way its hardware (as of Rev 5) was designed, it's not possible to -implement analogReference on the Maple, so this function doesn't -exist. If your inputs lie in a different voltage range than 0V--3.3V, -you'll need to bring them into that range before using -``analogRead()``. Some basic tools to accomplish this are `resistor -dividers `_ and `Zener -diodes -`_\ -. However, `operational amplifiers -`_ and other -powered components can also be used if greater precision is required. - -See also +the `analogReference() +`_ function. Because +of hardware restrictions, this function is not available on the Maple +and Maple RET6 Edition. If your inputs lie in a different voltage +range than 0V--3.3V, you'll need to bring them into that range before +using ``analogRead()``. See the :ref:`ADC reference ` for +more information. + +See Also -------- - :ref:`ADC tutorial ` - `(Arduino) Tutorial: Analog Input Pins `_ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst index 9147b96..e789305 100644 --- a/source/lang/api/analogwrite.rst +++ b/source/lang/api/analogwrite.rst @@ -65,12 +65,12 @@ This will convert values in the range 0-255 to values in the range which control PWM output. See the :ref:`timers reference ` for more information. -Another fix is to consult the :ref:`pin mapping mega table -` to find the timer which controls PWM on the -pin you're using, then set that Timer's overflow to 255. Subsequent -calls to analogWrite() should work as on the Arduino (with the same -loss of precision). Note, however, that that affects the overflow for -the **entire timer**, so other code relying on that timer (such as any +Another fix is to consult your board's :ref:`pin maps ` +to find the timer which controls PWM on the pin you're using, then set +that Timer's overflow to 255. Subsequent calls to analogWrite() +should work as on the Arduino (with the same loss of precision). +Note, however, that that affects the overflow for the **entire +timer**, so other code relying on that timer (such as any :ref:`interrupts ` the timer controls) will likely need to be modified as well. @@ -140,9 +140,9 @@ If your application definitely requires Arduino's PWM frequency, then the steps are: 1. Figure out which :ref:`timer ` controls PWM - output on your pin (\ :ref:`this table ` is your - friend here). Let's say it's ``Timern``\ , where ``n`` is some - number 1, 2, 3, or 4. + output on your pin (\ :ref:`your board's Timer Pin Map + ` is your friend here). Let's say it's ``Timern``\ + , where ``n`` is some number 1, 2, 3, or 4. 2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of @@ -154,7 +154,7 @@ timer. The important examples are :ref:`timer interrupts ` and :ref:`PWM `\ . -See also +See Also -------- - :ref:`Maple PWM tutorial ` @@ -169,5 +169,4 @@ See also Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) integer with size 2 bytes can hold the values between 0 and 65,535. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst index 7c5a6c7..39902ac 100644 --- a/source/lang/api/attachinterrupt.rst +++ b/source/lang/api/attachinterrupt.rst @@ -5,9 +5,8 @@ attachInterrupt() ================= -Used to specify a function to call when an external interrupt (like an -GPIO changing from LOW to HIGH, a button getting pressed, etc.) -occurs. +Used to specify a function to call when an :ref:`external interrupt +` occurs. .. contents:: Contents :local: @@ -15,9 +14,9 @@ occurs. Library Documentation --------------------- -.. FIXME once breathe knows how to get the correct attachInterupt -.. (right now it's copying from HardwareTimer), replace with a -.. doxygenfunction directive +.. FIXME [doxygenfunction] once Breathe knows how to get the correct +.. attachInterupt (right now it's copying from HardwareTimer), replace +.. with a doxygenfunction directive .. cpp:function:: void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode) @@ -47,49 +46,29 @@ Discussion Because the function will run in interrupt context, inside of it, :ref:`lang-delay` won't work, and the value returned by -:ref:`lang-millis` will not increment. Serial data received while -in the function may be lost. You should declare as ``volatile`` any +:ref:`lang-millis` will not increment. Serial data received while in +the function may be lost. You should declare as ``volatile`` any global variables that you modify within the attached function. -There are a few constraints you should be aware of if you're using -more than one interrupt at a time; the :ref:`external-interrupts` page -has the details. - -Using Interrupts ----------------- - -Interrupts are useful for making things happen automatically in -microcontroller programs, and can help solve timing problems. A -good task for using an interrupt might be reading a rotary encoder, -or monitoring user input. - -If you wanted to insure that a program always caught the pulses -from a rotary encoder, never missing a pulse, it would make it very -tricky to write a program to do anything else, because the program -would need to constantly poll the sensor lines for the encoder, in -order to catch pulses when they occurred. Other sensors have a -similar interface dynamic too, such as trying to read a sound -sensor that is trying to catch a click, or an infrared slot sensor -(photo-interrupter) trying to catch a coin drop. In all of these -situations, using an interrupt can free the microcontroller to get -some other work done while not missing the doorbell. +There are a few limits you should be aware of if you're using more +than one interrupt at a time; the :ref:`External Interrupts +` page has more information. Example ------- -:: + :: - int maple_led_pin = 13; volatile int state = LOW; // must declare volatile, since it's - // modified within the blink handler + // modified within the blink() handler void setup() { - pinMode(maple_led_pin, OUTPUT); + pinMode(BOARD_LED_PIN, OUTPUT); attachInterrupt(0, blink, CHANGE); } void loop() { - digitalWrite(maple_led_pin, state); + digitalWrite(BOARD_LED_PIN, state); } void blink() { @@ -106,10 +85,10 @@ additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 number goes with which pin -- just tell ``attachInterrupt()`` the pin you want. -See also +See Also -------- -- :ref:`detachInterrupt ` -- :ref:`external-interrupts` +- :ref:`lang-detachinterrupt` +- :ref:`external-interrupts` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bit.rst b/source/lang/api/bit.rst index dd5c050..3df042c 100644 --- a/source/lang/api/bit.rst +++ b/source/lang/api/bit.rst @@ -12,33 +12,27 @@ Syntax ``bit(n)`` - Parameters ---------- * **n** the bit to set. - Value ----- The value of an integer with the given bit set. - Arduino Compatibility --------------------- -The Maple implementation of bit is compatible with Arduino. +The Maple implementation of ``bit()`` is compatible with Arduino. - -See also +See Also -------- - - :ref:`lang-bitread` - :ref:`lang-bitwrite` - :ref:`lang-bitset` - :ref:`lang-bitclear` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bitclear.rst b/source/lang/api/bitclear.rst index 941f912..f487059 100644 --- a/source/lang/api/bitclear.rst +++ b/source/lang/api/bitclear.rst @@ -10,7 +10,6 @@ Syntax ``bitClear(x, n)`` - Parameters ---------- @@ -19,20 +18,17 @@ Parameters * **n** which bit to clear, starting at 0 for the least-significant (rightmost) bit - Returns ------- -None. - +Nothing. Arduino Compatibility --------------------- -This implementation is compatible with that of Arduino. +The Maple implementation of ``bitClear()`` is compatible with Arduino. - -See also +See Also -------- - :ref:`bit `\ () @@ -40,5 +36,4 @@ See also - :ref:`bitWrite `\ () - :ref:`bitSet `\ () - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bitread.rst b/source/lang/api/bitread.rst index 46b4478..fd9fbbe 100644 --- a/source/lang/api/bitread.rst +++ b/source/lang/api/bitread.rst @@ -5,13 +5,11 @@ bitRead() (Macro) Gets the value of a bit in a number. - Syntax ------ ``bitRead(x, n)`` - Parameters ---------- @@ -20,27 +18,22 @@ Parameters * **n** which bit to read, starting at 0 for the least-significant (rightmost) bit - Value ----- The value of the bit (0 or 1). - Arduino Compatibility --------------------- The Maple implementation of ``bitRead`` is compatible with Arduino. - -See also +See Also -------- - - :ref:`lang-bit` - :ref:`lang-bitwrite` - :ref:`lang-bitset` - :ref:`lang-bitclear` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bitset.rst b/source/lang/api/bitset.rst index ccd76de..83ab5f8 100644 --- a/source/lang/api/bitset.rst +++ b/source/lang/api/bitset.rst @@ -5,13 +5,11 @@ bitSet() (Macro) Sets (writes a 1 to) a bit of a numeric variable. - Syntax ------ ``bitSet(x, n)`` - Parameters ---------- @@ -20,19 +18,16 @@ Parameters * **n** which bit to set, starting at 0 for the least-significant (rightmost) bit - Value ----- None. - Arduino Compatibility --------------------- The Maple implementation of bitSet is compatible with Arduino. - See Also -------- @@ -41,6 +36,4 @@ See Also - :ref:`lang-bitwrite` - :ref:`lang-bitclear` - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bitwrite.rst b/source/lang/api/bitwrite.rst index b3feff2..6106545 100644 --- a/source/lang/api/bitwrite.rst +++ b/source/lang/api/bitwrite.rst @@ -32,9 +32,9 @@ Nothing. Arduino Compatibility --------------------- -Maple's version of ``bitWrite()`` is compatible with Arduino. +Maple's implementation of ``bitWrite()`` is compatible with Arduino. -See also +See Also -------- - :ref:`bit() ` @@ -42,5 +42,4 @@ See also - :ref:`bitSet() ` - :ref:`bitClear() ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst index e274163..05e3837 100644 --- a/source/lang/api/board-values.rst +++ b/source/lang/api/board-values.rst @@ -12,6 +12,9 @@ it easier to share your code with other people who have different boards. Some example usages are given :ref:`below `. +The actual values for each board are given in the :ref:`Board Hardware +Documentation `. + .. contents:: Contents :local: @@ -111,8 +114,6 @@ Pin Arrays Some :ref:`arrays ` of pin numbers are available which you can use to find out certain important information about a given pin. -.. TODO [0.1.0] links to board-specific hardware information - - ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM ` output, using :ref:`pwmWrite() `. The total number of these pins is :ref:`BOARD_NR_PWM_PINS diff --git a/source/lang/api/cc-attribution.txt b/source/lang/api/cc-attribution.txt deleted file mode 100644 index e100140..0000000 --- a/source/lang/api/cc-attribution.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. Included in all this directory's files in order to satisfy the -.. Arduino CC Attribution-ShareAlike 3.0 License - -.. admonition:: License and Attribution - - This documentation page was adapted from the `Arduino Reference - Documentation `_\ , which - is released under a `Creative Commons Attribution-ShareAlike 3.0 - License `_. diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst index c5a7c0c..00c1a5c 100644 --- a/source/lang/api/constants.rst +++ b/source/lang/api/constants.rst @@ -320,4 +320,4 @@ See Also - :ref:`double ` - :ref:`Board-Specific Values ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/constrain.rst b/source/lang/api/constrain.rst index d19b61c..28af1e3 100644 --- a/source/lang/api/constrain.rst +++ b/source/lang/api/constrain.rst @@ -59,11 +59,10 @@ Arduino Compatibility Maple's implementation of ``constrain()`` is compatible with Arduino. -See also +See Also -------- - :ref:`min() ` - :ref:`max() ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/cos.rst b/source/lang/api/cos.rst index 3fbb0af..c340f09 100644 --- a/source/lang/api/cos.rst +++ b/source/lang/api/cos.rst @@ -19,14 +19,12 @@ Note that the Maple implementation comes from `newlib `_\ , while Arduino's is that of `avr-libc `_\ . -See also +See Also -------- - - :ref:`sin() ` - :ref:`tan() ` - :ref:`float ` - :ref:`double ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/delay.rst b/source/lang/api/delay.rst index 90ca268..9ef06a0 100644 --- a/source/lang/api/delay.rst +++ b/source/lang/api/delay.rst @@ -57,10 +57,9 @@ Example .. _lang-delay-seealso: -See also +See Also -------- - - :ref:`millis() ` - :ref:`micros() ` - :ref:`delayMicroseconds() ` @@ -68,5 +67,4 @@ See also `_ example (works unmodified on Maple) - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/delaymicroseconds.rst b/source/lang/api/delaymicroseconds.rst index 24a8286..7078660 100644 --- a/source/lang/api/delaymicroseconds.rst +++ b/source/lang/api/delaymicroseconds.rst @@ -48,9 +48,9 @@ Arduino Compatibility --------------------- While we have made every effort we could to ensure that the timing of -delayMicroseconds is as accurate as possible, we cannot guarantee it -will behave as the Arduino implementation down to the microsecond, -especially for smaller values of ``us``. +``delayMicroseconds()`` is as accurate as possible, we cannot +guarantee it will behave as the Arduino implementation down to the +microsecond, especially for smaller values of ``us``. See Also -------- @@ -59,7 +59,4 @@ See Also - :ref:`micros ` - :ref:`delay ` - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/detachinterrupt.rst b/source/lang/api/detachinterrupt.rst index 41642a7..82ce974 100644 --- a/source/lang/api/detachinterrupt.rst +++ b/source/lang/api/detachinterrupt.rst @@ -9,9 +9,8 @@ Used to disable an interrupt specified with Library Documentation --------------------- -.. FIXME once breathe knows how to get the correct detachInterupt -.. (right now it's copying from HardwareTimer), replace with a -.. doxygenfunction directive +.. FIXME [Breathe] once we can get the correct detachInterupt(), +.. replace with doxygenfunction. .. cpp:function:: void detachInterrupt(uint8 pin) @@ -39,5 +38,6 @@ See Also -------- - :ref:`attachInterrupt() ` +- :ref:`external-interrupts` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/digitalread.rst b/source/lang/api/digitalread.rst index 3502587..ccf4a4c 100644 --- a/source/lang/api/digitalread.rst +++ b/source/lang/api/digitalread.rst @@ -8,51 +8,44 @@ digitalRead() Reads the value from a specified digital pin, either :ref:`HIGH ` or :ref:`LOW `. - Library Documentation --------------------- .. doxygenfunction:: digitalRead +Discussion +---------- + +If the pin isn't connected to anything, ``digitalRead()`` can return +either HIGH or LOW (and this will change in a way that seems random). Example ------- -The following example turns the LED on when the button is pressed:: - - int ledPin = 13; // LED connected to Maple pin 13 - int buttonPin = 38; // BUT connected to Maple pin 38 +The following example turns the LED on or off when the button is pressed:: void setup() { - pinMode(ledPin, OUTPUT); - pinMode(buttonPin, INPUT); + pinMode(BOARD_LED_PIN, OUTPUT); + pinMode(BOARD_BUTTON_PIN, INPUT); } void loop() { - int val = digitalRead(buttonPin); // reads the input pin - digitalWrite(ledPin, val); + int val = digitalRead(BOARD_BUTTON_PIN); // reads the input pin + togglePin(BOARD_LED_PIN, val); } -Note ----- - -If the pin isn't connected to anything, ``digitalRead()`` can return -either HIGH or LOW (and this can change in a way that seems random). - Arduino Compatibility --------------------- The Maple version of ``digitalRead()`` is compatible with Arduino. - See Also -------- -- :ref:`pinMode ` -- :ref:`digitalWrite ` - - - - +- :ref:`BOARD_BUTTON_PIN ` +- :ref:`lang-isButtonPressed` +- :ref:`lang-pinmode` +- :ref:`lang-digitalWrite` +- :ref:`lang-togglepin` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/digitalwrite.rst b/source/lang/api/digitalwrite.rst index 6124d5f..376cbc3 100644 --- a/source/lang/api/digitalwrite.rst +++ b/source/lang/api/digitalwrite.rst @@ -21,42 +21,26 @@ If the pin has been configured as an ``OUTPUT`` with :ref:`pinMode() ` its voltage will be set to the corresponding value: 3.3V for ``HIGH``, and 0V (ground) for ``LOW``. -.. TODO make the following paragraphs true, but refer the reader to -.. INPUT_PULLUP and INPUT_PULLDOWN: - -If the pin is configured as an ``INPUT``, writing a ``HIGH`` value -with ``digitalWrite()`` will enable an internal pullup resistor. -Writing ``LOW`` will disable the pullup. The pullup resistor is enough -to light an LED dimly, so if LEDs appear to work, but very dimly, this -is a likely cause. The remedy is to set the pin to an output with the -:ref:`pinMode() ` function. - -.. note:: Pin 13 is harder to use as an input than the other pins - because it has an LED and resistor soldered to it in series. If you - enable its internal pull-up resistor, it will likely hang at around - 1.1V instead of the expected 3.3V because the onboard LED and - series resistor pull the voltage level down. If you must use pin 13 - as a digital input, use an external pull-down resistor. +Because it is soldered to an LED and resistor in series, your board's +:ref:`BOARD_LED_PIN ` will respond slightly +more slowly as an output than the other pins. Example ------- The following example sets pin 13 to ``HIGH``, makes a one-second-long delay, sets the pin back to ``LOW``, and delays again, causing a -blinking pattern:: - - - int ledPin = 13; // LED connected to digital pin 13 +blinking pattern (you could also use :ref:`lang-toggleled`):: void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output + pinMode(BOARD_LED_PIN, OUTPUT); // sets the digital pin as output } void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, LOW); // sets the LED off + delay(1000); // waits for a second } See Also @@ -64,5 +48,8 @@ See Also - :ref:`pinMode ` - :ref:`digitalRead ` +- :ref:`BOARD_LED_PIN ` +- :ref:`lang-toggleled` +- :ref:`lang-togglepin` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst index 3f086ca..526beb6 100644 --- a/source/lang/api/hardwaretimer.rst +++ b/source/lang/api/hardwaretimer.rst @@ -10,8 +10,7 @@ built-in timer peripherals. More information on these peripherals (including code examples) is available in the :ref:`timers reference `. -.. FIXME update HardwareTimer documentation after redoing it in terms -.. of the new timer interface. +.. FIXME [0.0.10] Updated HardwareTimer documentation, with deprecation .. warning:: This class has been deprecated. It is not available in the current build. @@ -27,8 +26,7 @@ documented below on one of the predefined ``HardwareTimer`` instances. For example, to set the prescale factor on timer 1 to 5, call ``Timer1.setPrescaleFactor(5)``. -.. TODO add code examples that people can copy and paste in case -.. they're unfamiliar with namespace syntax +.. TODO add tutorial-style examples .. cpp:class:: HardwareTimer @@ -92,9 +90,8 @@ For example, to set the prescale factor on timer 1 to 5, call Set the given channel of this timer to the given :ref:`mode `. The parameter ``channel`` is one of 1, 2, 3, and 4, and corresponds to the compare channel you would - like to set. Refer to the full :ref:`pin mapping table - ` to match up timer channels and pin - numbers. + like to set. Refer to your board's :ref:`master pin map + ` to match up timer channels and pin numbers. .. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode) @@ -377,3 +374,87 @@ different. Other Functions ^^^^^^^^^^^^^^^ .. doxygenfunction:: getTimer + +Examples +^^^^^^^^ + +**LED blink**:: + + #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles + + void handler_led(void); + + void setup() + { + // Set up the LED to blink + pinMode(BOARD_LED_PIN, OUTPUT); + + // Setup Timer + Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer2.setPeriod(LED_RATE); // in microseconds + Timer2.setCompare1(1); // overflow might be small + Timer2.attachCompare1Interrupt(handler_led); + } + + void loop() { + // Nothing! It's all in the interrupts + } + + void handler_led(void) { + toggleLED(); + } + +**Racing Counters**:: + + void handler_count1(void); + void handler_count2(void); + + int count1 = 0; + int count2 = 0; + + void setup() + { + // Set up BUT for input + pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); + + // Setup Counting Timers + Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer3.pause(); + Timer4.pause(); + Timer3.setCount(0); + Timer4.setCount(0); + Timer3.setOverflow(30000); + Timer4.setOverflow(30000); + Timer3.setCompare1(1000); // somewhere in the middle + Timer4.setCompare1(1000); + Timer3.attachCompare1Interrupt(handler1); + Timer4.attachCompare1Interrupt(handler2); + Timer3.resume(); + Timer4.resume(); + } + + void loop() { + // Display the running counts + SerialUSB.print("Count 1: "); + SerialUSB.print(count1); + SerialUSB.print("\t\tCount 2: "); + SerialUSB.println(count2); + + // Run... while BUT is held, pause Count2 + for(int i = 0; i<1000; i++) { + if(digitalRead(BOARD_BUTTON_PIN)) { + Timer4.pause(); + } else { + Timer4.resume(); + } + delay(1); + } + } + + void handler1(void) { + count1++; + } + void handler2(void) { + count2++; + } diff --git a/source/lang/api/highbyte.rst b/source/lang/api/highbyte.rst index 50a1fa6..4cb6f9b 100644 --- a/source/lang/api/highbyte.rst +++ b/source/lang/api/highbyte.rst @@ -52,8 +52,4 @@ See Also - :ref:`lowByte() ` - - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/loop.rst b/source/lang/api/loop.rst index d8f6183..c2a5097 100644 --- a/source/lang/api/loop.rst +++ b/source/lang/api/loop.rst @@ -15,7 +15,6 @@ Example :: - int buttonPin = 38; // setup initializes serial and the button pin @@ -42,4 +41,4 @@ See Also - :ref:`setup() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/lowbyte.rst b/source/lang/api/lowbyte.rst index 58e622f..c513711 100644 --- a/source/lang/api/lowbyte.rst +++ b/source/lang/api/lowbyte.rst @@ -22,4 +22,4 @@ Returns The low byte's value (this will be between 0 and 255). -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/map.rst b/source/lang/api/map.rst index 79122b3..69661a0 100644 --- a/source/lang/api/map.rst +++ b/source/lang/api/map.rst @@ -65,4 +65,4 @@ See Also - :ref:`constrain() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/max.rst b/source/lang/api/max.rst index d38eebe..d356f08 100644 --- a/source/lang/api/max.rst +++ b/source/lang/api/max.rst @@ -53,7 +53,7 @@ functions inside the parentheses. It may lead to incorrect results:: Arduino Compatibility --------------------- -The Maple version of ``max()`` is compatible with Arduino. +The Maple implementation of ``max()`` is compatible with Arduino. See Also -------- @@ -61,5 +61,4 @@ See Also - :ref:`min() ` - :ref:`constrain() ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/micros.rst b/source/lang/api/micros.rst index f12976b..de85303 100644 --- a/source/lang/api/micros.rst +++ b/source/lang/api/micros.rst @@ -43,4 +43,4 @@ See Also - :ref:`delay() ` - :ref:`delayMicroseconds() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/millis.rst b/source/lang/api/millis.rst index 0288c56..db0531c 100644 --- a/source/lang/api/millis.rst +++ b/source/lang/api/millis.rst @@ -49,4 +49,4 @@ See Also - :ref:`delay ` - :ref:`delayMicroseconds ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/min.rst b/source/lang/api/min.rst index 1245f6f..3307105 100644 --- a/source/lang/api/min.rst +++ b/source/lang/api/min.rst @@ -62,5 +62,4 @@ See Also - :ref:`max() ` - :ref:`constrain() ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/pinmode.rst b/source/lang/api/pinmode.rst index 03cbcfa..8cee3e5 100644 --- a/source/lang/api/pinmode.rst +++ b/source/lang/api/pinmode.rst @@ -60,13 +60,13 @@ set up a pin for these purposes before a call to, e.g., :ref:`lang-analogRead`. In practice, this should only add a few lines to your :ref:`lang-setup` function. -.. TODO verify following before putting it in: +.. TODO [0.1.0] verify following before putting it in: .. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and .. ``PWM_OPEN_DRAIN`` modes represent functionality not currently .. available on Arduino boards. -See also +See Also -------- - :ref:`lang-constants` @@ -74,6 +74,4 @@ See also - :ref:`lang-digitalread` - Maple :ref:`GPIO ` reference page - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/pow.rst b/source/lang/api/pow.rst index 4280400..219a866 100644 --- a/source/lang/api/pow.rst +++ b/source/lang/api/pow.rst @@ -10,8 +10,6 @@ Library Documentation .. doxygenfunction:: pow -.. TODO LATER some examples - See Also -------- @@ -19,5 +17,4 @@ See Also - :ref:`float ` - :ref:`double ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst index cea602b..5cc112e 100644 --- a/source/lang/api/pwmwrite.rst +++ b/source/lang/api/pwmwrite.rst @@ -11,10 +11,13 @@ pwmWrite(), the pin will output a steady square wave with the given duty cycle. You can change the duty cycle later by calling pwmWrite() again with the same pin and a different duty. -.. FIXME board-specific information - -On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, -9, 11, 12, 14, 24, 27, and 28. +The pins which support PWM have ``PWM`` listed underneath their number +on your board's silkscreen. These pin numbers are available to your +program in the :ref:`boardPWMPins ` +board-specific array. The number of pins which are capable of PWM on +your board is given by the ``BOARD_NR_PWM_PINS`` constant. These +values are documented for each board in the :ref:`Board Hardware +Documentation ` pages. The Arduino function :ref:`analogWrite() ` is an alias for ``pwmWrite()``, but it is badly named, and its use is @@ -54,4 +57,5 @@ potentiometer:: See Also -------- -- :ref:`Maple PWM tutorial ` +- :ref:`Maple PWM tutorial ` +- :ref:`boardPWMPins ` diff --git a/source/lang/api/random.rst b/source/lang/api/random.rst index dd8871d..9875ee6 100644 --- a/source/lang/api/random.rst +++ b/source/lang/api/random.rst @@ -10,9 +10,7 @@ The ``random()`` function generates pseudo-random numbers. Library Documentation --------------------- -.. FIXME keep tracking Sphinx/Breathe's ability to reference -.. overloaded functions so we can use doxygenfunction instead of -.. manually documenting. +.. FIXME [Breathe] use doxygenfunction when possible .. cpp:function:: random(long max) @@ -70,4 +68,4 @@ See Also - :ref:`randomSeed() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/randomseed.rst b/source/lang/api/randomseed.rst index d0a15b7..ca7b75f 100644 --- a/source/lang/api/randomseed.rst +++ b/source/lang/api/randomseed.rst @@ -57,4 +57,4 @@ See Also - :ref:`random() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst index 417063d..0821f43 100644 --- a/source/lang/api/serial.rst +++ b/source/lang/api/serial.rst @@ -12,49 +12,20 @@ devices. Introduction ------------ -.. FIXME [Maple-specific values] -.. FIXME [0.0.10] Serial4, Serial5 updates for high-density devices +.. FIXME [0.0.10] UART4, UART5 -The Maple has three serial ports (also known as a UARTs or USARTs): -``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the -pins summarized in the following table: - -.. list-table:: - :header-rows: 1 - - * - Serial port - - TX, RX, CK - - CTS, RTS (if present) - - * - ``Serial1`` - - 7, 8, 6 - - - - * - ``Serial2`` - - 1, 0, 10 - - 2, 3 - - * - ``Serial3`` - - 29, 30, 31 - - 32, 33 - -Thus, if you use a particular serial port, you cannot also use its -communication pins for other purposes at the same time. - -If you want to communicate with the Maple using the provided USB port, -use :ref:`SerialUSB ` instead. - -To use them to communicate with an external TTL serial device, connect -the TX pin to your device's RX pin, the RX to your device's TX pin, -and the ground of your Maple to your device's ground. +To use a serial port to communicate with an external serial device, +connect the TX pin to your device's RX pin, the RX to your device's TX +pin, and your Maple board's ground to your device's ground. .. warning:: Don't connect these pins directly to an RS232 serial port; they operate at +/- 12V and can damage your board. - Library Documentation --------------------- +.. FIXME [0.1.0] Tutorial-style usage introduction + All of the ``Serial[1,2,3]`` objects are instances of the ``HardwareSerial`` class, which is documented in this section. (This means that you can use any of these functions on any of ``Serial1``, @@ -209,9 +180,10 @@ Arduino Compatibility Note -------------------------- Unlike the Arduino, none of the Maple's serial ports is connected to -the USB port on the Maple board (for that, use :ref:`SerialUSB -`). Thus, to use these pins to communicate with your -personal computer, you will need an additional USB-to-serial adapter. +the USB port on the Maple board. If you want to communicate using the +built-in USB port, use :ref:`SerialUSB ` instead. You +will need an additional USB-to-serial adapter to communicate between a +USART and your computer. .. FIXME [0.1.0] port these examples over @@ -226,4 +198,4 @@ personal computer, you will need an additional USB-to-serial adapter. .. - `Serial Call Response `_ .. - `Serial Call Response ASCII `_ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/setup.rst b/source/lang/api/setup.rst index 837ddd6..1e8e3b8 100644 --- a/source/lang/api/setup.rst +++ b/source/lang/api/setup.rst @@ -26,4 +26,4 @@ Example // ... } -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/sin.rst b/source/lang/api/sin.rst index 398b8f3..3e28c0b 100644 --- a/source/lang/api/sin.rst +++ b/source/lang/api/sin.rst @@ -28,5 +28,4 @@ See Also - :ref:`float ` - :ref:`double ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/sq.rst b/source/lang/api/sq.rst index bd32648..96724d3 100644 --- a/source/lang/api/sq.rst +++ b/source/lang/api/sq.rst @@ -42,5 +42,4 @@ Arduino Compatibility Maple's implementation of ``sq()`` is compatible with Arduino. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/tan.rst b/source/lang/api/tan.rst index 4bbe0db..b1aed31 100644 --- a/source/lang/api/tan.rst +++ b/source/lang/api/tan.rst @@ -22,10 +22,9 @@ Note that the Maple implementation comes from `newlib See Also -------- - - :ref:`sin ` - :ref:`cos ` - :ref:`float ` - :ref:`double ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/volatile.rst b/source/lang/api/volatile.rst index 276bb6a..1b72897 100644 --- a/source/lang/api/volatile.rst +++ b/source/lang/api/volatile.rst @@ -24,8 +24,8 @@ for efficiency). A variable should be declared ``volatile`` whenever its value can be changed by something beyond the control of the code section in which it appears, such as an :ref:`external interrupt -`. On the Maple, the only place that this is -likely to occur is in sections of code associated with interrupts. +`. (The only place that this is likely to occur +in most programs is inside of code called by interrupts). Example ------- @@ -55,11 +55,11 @@ Example } } -See also +See Also -------- - :ref:`External Interrupts ` - :ref:`lang-attachinterrupt` - :ref:`lang-detachinterrupt` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cc-attribution.txt b/source/lang/cc-attribution.txt index e100140..11302b2 100644 --- a/source/lang/cc-attribution.txt +++ b/source/lang/cc-attribution.txt @@ -3,7 +3,8 @@ .. admonition:: License and Attribution - This documentation page was adapted from the `Arduino Reference - Documentation `_\ , which - is released under a `Creative Commons Attribution-ShareAlike 3.0 - License `_. + Some information in this page was adapted from the `Arduino + Reference Documentation + `_\ , which is released + under a `Creative Commons Attribution-ShareAlike 3.0 License + `_. diff --git a/source/lang/cpp/arithmetic.rst b/source/lang/cpp/arithmetic.rst index 26e2811..cef3954 100644 --- a/source/lang/cpp/arithmetic.rst +++ b/source/lang/cpp/arithmetic.rst @@ -121,4 +121,4 @@ See Also - :ref:`sizeof `\ () -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/array.rst b/source/lang/cpp/array.rst index 30a818f..39d4d91 100644 --- a/source/lang/cpp/array.rst +++ b/source/lang/cpp/array.rst @@ -113,11 +113,9 @@ Arduino Compatibility Arrays on Maple are identical those on Arduino. -See also +See Also -------- - :ref:`Storing arrays in FLASH memory ` - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/assignment.rst b/source/lang/cpp/assignment.rst index f9430b4..6379298 100644 --- a/source/lang/cpp/assignment.rst +++ b/source/lang/cpp/assignment.rst @@ -57,4 +57,4 @@ See Also `_ for more information. -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/bitshift.rst b/source/lang/cpp/bitshift.rst index e1c8de0..47413f2 100644 --- a/source/lang/cpp/bitshift.rst +++ b/source/lang/cpp/bitshift.rst @@ -140,5 +140,4 @@ See Also - :ref:`lang-bitwrite` - :ref:`lang-bitclear` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/bitwisemath.rst b/source/lang/cpp/bitwisemath.rst index 28fe6bf..59794ba 100644 --- a/source/lang/cpp/bitwisemath.rst +++ b/source/lang/cpp/bitwisemath.rst @@ -182,5 +182,4 @@ See Also - :ref:`Compound bitwise operations ` (``&=``, ``|=``, ``^=``). - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/boolean.rst b/source/lang/cpp/boolean.rst index 8d6aa5c..f09345e 100644 --- a/source/lang/cpp/boolean.rst +++ b/source/lang/cpp/boolean.rst @@ -87,5 +87,4 @@ See Also ``|=``, ``^=``). - :ref:`if statement ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/booleanvariables.rst b/source/lang/cpp/booleanvariables.rst index 6051b8c..0d76a12 100644 --- a/source/lang/cpp/booleanvariables.rst +++ b/source/lang/cpp/booleanvariables.rst @@ -42,13 +42,11 @@ Example } } -See also +See Also -------- - - :ref:`Boolean constants ` - :ref:`Boolean operators ` - :ref:`Variables ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/break.rst b/source/lang/cpp/break.rst index ce8ac17..f367b99 100644 --- a/source/lang/cpp/break.rst +++ b/source/lang/cpp/break.rst @@ -29,7 +29,4 @@ Example delay(50); } - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/byte.rst b/source/lang/cpp/byte.rst index 45c9d5f..4634594 100644 --- a/source/lang/cpp/byte.rst +++ b/source/lang/cpp/byte.rst @@ -30,5 +30,4 @@ See Also - :ref:`byte() ` (casting a value to a byte) - :ref:`Variables ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/bytecast.rst b/source/lang/cpp/bytecast.rst index b3f0de2..24c3b9e 100644 --- a/source/lang/cpp/bytecast.rst +++ b/source/lang/cpp/bytecast.rst @@ -24,13 +24,11 @@ Syntax ``byte(x)`` - Parameters ---------- **x**: a value of any integer type - Returns ------- @@ -38,13 +36,9 @@ The value, converted to a ``byte``. Note, however, that if the value is larger than the maximum value you can store in a byte (255), then the results might be strange and unexpected. - See Also -------- - :ref:`lang-byte` - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/char.rst b/source/lang/cpp/char.rst index b8747f3..686c0d1 100644 --- a/source/lang/cpp/char.rst +++ b/source/lang/cpp/char.rst @@ -10,7 +10,6 @@ value from -128 to 127). Character literals are written in single quotes, like this: ``'A'`` (for multiple characters - strings - use double quotes: ``"ABC"``). - Just like everything else on a computer, characters are stored as numbers. You can see the specific encoding in the `ASCII chart `_\ @@ -25,26 +24,21 @@ The ``char`` datatype is a signed type, meaning that it encodes numbers from -128 to 127. For an unsigned type, which stores values from 0 to 255, just use the type ``unsigned char`` (two words). - Example ------- :: - // the following two lines are equivalent, using the ASCII + // The following two lines are equivalent, using the ASCII // character encoding: char c = 'A'; char c = 65; - -See also +See Also -------- - - :ref:`lang-int` - :ref:`lang-array` (a string is just an array of ``char``\ s) - :ref:`Serial.println() ` - - .. include:: cc-attribution.txt diff --git a/source/lang/cpp/charcast.rst b/source/lang/cpp/charcast.rst index a480dec..640ad85 100644 --- a/source/lang/cpp/charcast.rst +++ b/source/lang/cpp/charcast.rst @@ -12,13 +12,11 @@ Syntax ``char(x)`` - Parameters ---------- **x**: a value of any type - Returns ------- @@ -26,11 +24,9 @@ The value, converted to a ``char``. Note, however, that if the value is outside the range of a ``char`` (-128 to 127), then the results might be strange and unexpected. - See Also -------- - :ref:`char ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/comments.rst b/source/lang/cpp/comments.rst index c5f118a..1428dc3 100644 --- a/source/lang/cpp/comments.rst +++ b/source/lang/cpp/comments.rst @@ -61,7 +61,4 @@ just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/comparison.rst b/source/lang/cpp/comparison.rst index b24355f..9cd0a9f 100644 --- a/source/lang/cpp/comparison.rst +++ b/source/lang/cpp/comparison.rst @@ -83,5 +83,4 @@ Comparison operators, along with :ref:`boolean operators appears within a conditional doesn't mean it's automatically wrong. Be careful to know what you mean.) - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/compoundarithmetic.rst b/source/lang/cpp/compoundarithmetic.rst index 420f1db..d70a43c 100644 --- a/source/lang/cpp/compoundarithmetic.rst +++ b/source/lang/cpp/compoundarithmetic.rst @@ -40,5 +40,4 @@ See Also - :ref:`Arithmetic operators ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/compoundbitwise.rst b/source/lang/cpp/compoundbitwise.rst index 8231130..4efe5df 100644 --- a/source/lang/cpp/compoundbitwise.rst +++ b/source/lang/cpp/compoundbitwise.rst @@ -226,5 +226,4 @@ See Also - :ref:`Boolean operations ` (``&&``, ``||``) - :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) - .. include:: cc-attribution.txt diff --git a/source/lang/cpp/const.rst b/source/lang/cpp/const.rst index 52de85f..ad0c580 100644 --- a/source/lang/cpp/const.rst +++ b/source/lang/cpp/const.rst @@ -21,7 +21,7 @@ method for defining constants than ``#define``. Example ------- -:: + :: // this defines a variable called "pi", which cannot be changed: const float pi = 3.14; @@ -33,7 +33,6 @@ Example pi = 7; // illegal - you can't write to (modify) a constant - **#define** or **const** ------------------------ @@ -48,5 +47,4 @@ See Also - :ref:`#define ` - :ref:`volatile ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/continue.rst b/source/lang/cpp/continue.rst index 13d1815..2a694f6 100644 --- a/source/lang/cpp/continue.rst +++ b/source/lang/cpp/continue.rst @@ -27,6 +27,4 @@ Example delay(50); } - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/curly-braces.rst b/source/lang/cpp/curly-braces.rst index a4bd3dc..df2fe2a 100644 --- a/source/lang/cpp/curly-braces.rst +++ b/source/lang/cpp/curly-braces.rst @@ -99,11 +99,8 @@ reference page for more information):: .. rubric:: Footnotes -.. TODO remove this once IDE 0.1.0 released - .. [#fbug] At present this feature is slightly buggy as the IDE will often find (incorrectly) a brace in text that has been commented out. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/define.rst b/source/lang/cpp/define.rst index 677390d..bdf7283 100644 --- a/source/lang/cpp/define.rst +++ b/source/lang/cpp/define.rst @@ -13,7 +13,6 @@ defined value at compile time. This can have some unwanted side effects. In general, the :ref:`const ` keyword is preferred for defining constants. - Syntax ------ @@ -42,7 +41,7 @@ is, **don't do this, either**:: Example ------- -:: + :: #define LED_PIN 13 // The compiler will replace any mention of LED_PIN with @@ -52,5 +51,4 @@ See Also -------- - :ref:`const ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/double.rst b/source/lang/cpp/double.rst index 1527778..59422eb 100644 --- a/source/lang/cpp/double.rst +++ b/source/lang/cpp/double.rst @@ -43,6 +43,4 @@ See Also - :ref:`float ` - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/doublecast.rst b/source/lang/cpp/doublecast.rst index 16a9907..d3f32ce 100644 --- a/source/lang/cpp/doublecast.rst +++ b/source/lang/cpp/doublecast.rst @@ -24,4 +24,4 @@ See Also - :ref:`float ` - :ref:`float() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/dowhile.rst b/source/lang/cpp/dowhile.rst index fe92226..d229122 100644 --- a/source/lang/cpp/dowhile.rst +++ b/source/lang/cpp/dowhile.rst @@ -23,5 +23,4 @@ Example:: x = readSensors(); // check the sensors } while (x < 100); - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/float.rst b/source/lang/cpp/float.rst index 6937c8c..5195fac 100644 --- a/source/lang/cpp/float.rst +++ b/source/lang/cpp/float.rst @@ -47,4 +47,4 @@ See Also - :ref:`double ` - :ref:`Variables ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/floatcast.rst b/source/lang/cpp/floatcast.rst index 4766478..af92543 100644 --- a/source/lang/cpp/floatcast.rst +++ b/source/lang/cpp/floatcast.rst @@ -25,4 +25,4 @@ See Also - :ref:`double ` - :ref:`double() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/for.rst b/source/lang/cpp/for.rst index 71c5aca..78ea562 100644 --- a/source/lang/cpp/for.rst +++ b/source/lang/cpp/for.rst @@ -123,7 +123,7 @@ questions (answers are in footnote [#fanswers]_\ ): 2. Why does it stop at 64? -See also +See Also -------- - :ref:`while ` loops @@ -139,4 +139,4 @@ See also false, and the loop stops. -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/goto.rst b/source/lang/cpp/goto.rst index ff2f248..2c0b3b0 100644 --- a/source/lang/cpp/goto.rst +++ b/source/lang/cpp/goto.rst @@ -126,5 +126,4 @@ See Also - Knuth, Donald. `Structured Programming with go to Statements `_ (PDF) - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/if.rst b/source/lang/cpp/if.rst index bef89e2..d57b9f1 100644 --- a/source/lang/cpp/if.rst +++ b/source/lang/cpp/if.rst @@ -118,4 +118,4 @@ See Also - :ref:`boolean operators ` - :ref:`comparison operators ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/include.rst b/source/lang/cpp/include.rst index 74fe7af..163509d 100644 --- a/source/lang/cpp/include.rst +++ b/source/lang/cpp/include.rst @@ -67,6 +67,4 @@ root `_ of a number:: SerialUSB.println(cubeRootOf3); } - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/increment.rst b/source/lang/cpp/increment.rst index 6dffa80..c423d1a 100644 --- a/source/lang/cpp/increment.rst +++ b/source/lang/cpp/increment.rst @@ -34,4 +34,4 @@ See Also - :ref:`lang-compoundarithmetic` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/intcast.rst b/source/lang/cpp/intcast.rst index 386fe14..da838c7 100644 --- a/source/lang/cpp/intcast.rst +++ b/source/lang/cpp/intcast.rst @@ -23,7 +23,4 @@ See Also - :ref:`int ` - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/longcast.rst b/source/lang/cpp/longcast.rst index f588fc6..493ad67 100644 --- a/source/lang/cpp/longcast.rst +++ b/source/lang/cpp/longcast.rst @@ -24,4 +24,4 @@ See Also - :ref:`long ` - :ref:`long long ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/longlong.rst b/source/lang/cpp/longlong.rst index 0ba56ed..d942cb4 100644 --- a/source/lang/cpp/longlong.rst +++ b/source/lang/cpp/longlong.rst @@ -53,4 +53,4 @@ See Also - :ref:`Integer Constants ` - :ref:`Variables ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/modulo.rst b/source/lang/cpp/modulo.rst index 289fba0..013d07e 100644 --- a/source/lang/cpp/modulo.rst +++ b/source/lang/cpp/modulo.rst @@ -67,4 +67,4 @@ See Also - :ref:`Arithmetic ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/pointer.rst b/source/lang/cpp/pointer.rst index 0a42270..ff4ec32 100644 --- a/source/lang/cpp/pointer.rst +++ b/source/lang/cpp/pointer.rst @@ -28,4 +28,4 @@ See Also - http://xkcd.com/138/ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/return.rst b/source/lang/cpp/return.rst index b4ef5fd..d9aecbe 100644 --- a/source/lang/cpp/return.rst +++ b/source/lang/cpp/return.rst @@ -57,5 +57,4 @@ See Also - :ref:`comments ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/scope.rst b/source/lang/cpp/scope.rst index 7b65bab..a270428 100644 --- a/source/lang/cpp/scope.rst +++ b/source/lang/cpp/scope.rst @@ -117,4 +117,4 @@ See Also - `C++ programming Wikibook `_. - Wikipedia article on `scope `_ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/semicolon.rst b/source/lang/cpp/semicolon.rst index 8164616..05e6218 100644 --- a/source/lang/cpp/semicolon.rst +++ b/source/lang/cpp/semicolon.rst @@ -19,7 +19,4 @@ compiler error comes up, one of the first things to check is a missing semicolon, in the immediate vicinity, preceding the line at which the compiler complained. - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/sizeof.rst b/source/lang/cpp/sizeof.rst index eae509c..ec2dea6 100644 --- a/source/lang/cpp/sizeof.rst +++ b/source/lang/cpp/sizeof.rst @@ -60,5 +60,5 @@ would look something like this:: standard guarantees, however, is that a ``char`` occupies at *least* 8 bits. -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/sqrt.rst b/source/lang/cpp/sqrt.rst index 956a754..fbabf82 100644 --- a/source/lang/cpp/sqrt.rst +++ b/source/lang/cpp/sqrt.rst @@ -21,5 +21,4 @@ See Also - :ref:`pow ` - :ref:`sq ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/static.rst b/source/lang/cpp/static.rst index 5d1802e..8c52ba0 100644 --- a/source/lang/cpp/static.rst +++ b/source/lang/cpp/static.rst @@ -53,5 +53,4 @@ then incremented, so it starts out at one. Subsequent calls to it was declared ``static``. Thus, ``numSensorReadings`` is a count of the number of times that ``readSensors()`` has been called. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/string.rst b/source/lang/cpp/string.rst index 0a270da..84917c1 100644 --- a/source/lang/cpp/string.rst +++ b/source/lang/cpp/string.rst @@ -124,5 +124,4 @@ See Also - :ref:`__attribute__ ` - :ref:`Variables ` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/switchcase.rst b/source/lang/cpp/switchcase.rst index b484bc5..e31ccf3 100644 --- a/source/lang/cpp/switchcase.rst +++ b/source/lang/cpp/switchcase.rst @@ -110,9 +110,9 @@ value as the variable to compare. In this case, you can write down all of the values the ``enum`` takes as ``case`` statements, and be sure you've covered all the possibilities. -See also: +See Also: --------- - :ref:`if/else ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/unsignedchar.rst b/source/lang/cpp/unsignedchar.rst index 5b946ed..45fedeb 100644 --- a/source/lang/cpp/unsignedchar.rst +++ b/source/lang/cpp/unsignedchar.rst @@ -16,18 +16,17 @@ won't store negative numbers; it is also subject to the same Example ------- -:: + :: unsigned char c = 240; See Also -------- - - :ref:`byte ` - :ref:`int ` - :ref:`array ` - :ref:`SerialUSB.println() ` - :ref:`Serial.println() ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/unsignedint.rst b/source/lang/cpp/unsignedint.rst index ad3e2f2..b7d9716 100644 --- a/source/lang/cpp/unsignedint.rst +++ b/source/lang/cpp/unsignedint.rst @@ -56,4 +56,4 @@ See Also - :ref:`Integer Constants ` - :ref:`Variables ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/unsignedlonglong.rst b/source/lang/cpp/unsignedlonglong.rst index 910b7e4..a1143f0 100644 --- a/source/lang/cpp/unsignedlonglong.rst +++ b/source/lang/cpp/unsignedlonglong.rst @@ -40,4 +40,4 @@ See Also - :ref:`Integer Constants ` - :ref:`Variables ` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/variables.rst b/source/lang/cpp/variables.rst index 336d5ab..9ffdd1d 100644 --- a/source/lang/cpp/variables.rst +++ b/source/lang/cpp/variables.rst @@ -165,6 +165,5 @@ See Also (usually) stored `_ on computers. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/void.rst b/source/lang/cpp/void.rst index 88c9c64..7af0acd 100644 --- a/source/lang/cpp/void.rst +++ b/source/lang/cpp/void.rst @@ -28,6 +28,4 @@ Example // ... } -.. TODO doc page on function declaration? - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/while.rst b/source/lang/cpp/while.rst index 9047d05..e66e0aa 100644 --- a/source/lang/cpp/while.rst +++ b/source/lang/cpp/while.rst @@ -35,4 +35,4 @@ Example var++; } -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/unimplemented/notone.rst b/source/lang/unimplemented/notone.rst index 485c9c5..8af878b 100644 --- a/source/lang/unimplemented/notone.rst +++ b/source/lang/unimplemented/notone.rst @@ -10,41 +10,28 @@ Stops the generation of a square wave triggered by `tone `_\ (). Has no effect if no tone is being generated. - - **NOTE:** if you want to play different pitches on multiple pins, you need to call noTone() on one pin before calling tone() on the next pin. - - Syntax ------ noTone(pin) - - Parameters ---------- pin: the pin on which to stop generating the tone - - Returns ------- -nothing - - +Nothing. -See also +See Also -------- - - `tone `_ () - - .. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/tone.rst b/source/lang/unimplemented/tone.rst index f83bf6b..13d581e 100644 --- a/source/lang/unimplemented/tone.rst +++ b/source/lang/unimplemented/tone.rst @@ -12,70 +12,47 @@ continues until a call to `noTone `_\ (). The pin can be connected to a piezo buzzer or other speaker to play tones. - - Only one tone can be generated at a time. If a tone is already playing on a different pin, the call to tone() will have no effect. If the tone is playing on the same pin, the call will set its frequency. - - Use of the tone() function will interfere with PWM output on pins 3 and 11 (on boards other than the Mega). - - **NOTE:** if you want to play different pitches on multiple pins, you need to call noTone() on one pin before calling tone() on the next pin. - - Syntax ------ tone(pin, frequency) tone(pin, frequency, duration) - - Parameters ---------- pin: the pin on which to generate the tone - - frequency: the frequency of the tone in hertz - - duration: the duration of the tone in milliseconds (optional) - - Returns ------- nothing - - -See also +See Also -------- - - `noTone `_\ () - `analogWrite `_\ () - `Tutorial:Tone `_ - `Tutorial:Pitch follower `_ - `Tutorial:Simple Keyboard `_ - `Tutorial: multiple tones `_ - - - `Tutorial: PWM `_ - - -.. include:: /lang/cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/source/language-index.rst b/source/language-index.rst index a064b3e..225a9ae 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -10,8 +10,21 @@ API references for documented libmaple functionality. The "C++ for Maple" pages are intended as a minimal reference/refresher for programmers familiar with the Arduino language. -**Looking for something else?** The low-level :ref:`libmaple library -interfaces ` are documented separately. +.. admonition:: **Looking for Something Else?** + + - See the :ref:`libraries` for extra built-in libraries for dealing + with different kinds of hardware. + + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + ` used to compile your programs is configured to link + against `newlib `_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. + + - If you're looking for pointers to low-level details, see the + :ref:`Language Recommended Reading + `. .. _index-language-index-cpp: .. _index-language-index-api: diff --git a/source/language.rst b/source/language.rst index 111a1f1..3ecbe43 100644 --- a/source/language.rst +++ b/source/language.rst @@ -10,8 +10,7 @@ The Maple can be programmed in the `Wiring `_ language, which is the same language used to program the `Arduino `_ boards. -.. TODO Wiring tutorial -- just describe setup()/loop(), then link to -.. some of the the bajillion external tutorials +.. TODO [0.2.0?] Wiring tutorial C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the @@ -20,31 +19,29 @@ language and C++ may wish to skip to the .. contents:: Contents :local: -.. _language-lang-docs: - -Maple Language Reference ------------------------- +.. admonition:: **Looking for Something Else?** -The following table summarizes the available core language features. -A more exhaustive index is available at the :ref:`language-index`. + - See the :ref:`libraries` for extra built-in libraries for dealing + with different kinds of hardware. -.. FIXME mention Maple Native supports malloc(), free(), operator -.. new(), and operator delete(), when that is a true thing to say. + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + ` used to compile your programs is configured to link + against `newlib `_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. -**Looking for something else?** + - If you're looking for pointers to low-level details, see this page's + :ref:`Recommended Reading `. -- See the :ref:`libraries` for extra built-in libraries for dealing - with different kinds of hardware. +.. _language-lang-docs: -- If you're looking for something from the C standard library (like - ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler - ` used to compile your programs is configured to link - against `newlib `_, and allows the - use of any of its header files. However, dynamic memory allocation - (``malloc()``, etc.) is not available. +Maple Language Reference +------------------------ -- If you're looking for low-level details, see the :ref:`libmaple - ` reference page. +The following table summarizes the most important core language +features. An exhaustive index is available at the +:ref:`language-index`. +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | @@ -458,14 +455,26 @@ Which could plausibly be turned into the final source file :: while (true) loop(); } +.. _language-recommended-reading: + Recommended Reading ------------------- -* `newlib Documentation `_ - * :ref:`libmaple Documentation ` - -* ST documentation: - - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (assembly language and register reference) +* Your board's :ref:`Board Hardware Documentation ` page +* ST Documentation: + * Reference Manual `RM0008 + `_ + (PDF). This is the most important reference work on the STM32 + line, and covers the low-level hardware capabilities and + interfaces in great detail. + * `Programming Manual + `_ + (PDF). This is an assembly language and register reference for + the STM32 line. +* ARM Documentation: + * `Cortex-M3 Technical Reference Manual, Revision r1p1 + `_ + (PDF). This ARM manual specifies much of the the Cortex M3 + Architecture, including instruction timings. +* `newlib Documentation `_ diff --git a/source/libmaple/api/systick.rst b/source/libmaple/api/systick.rst index 5ec906c..a02b8e4 100644 --- a/source/libmaple/api/systick.rst +++ b/source/libmaple/api/systick.rst @@ -1,6 +1,14 @@ .. highlight:: c + + .. _libmaple-systick: +.. FIXME [0.0.10] move these to the right places: + +.. _libmaple-systick_disable: + +.. _libmaple-systick_resume: + ``systick.h`` ============= diff --git a/source/libraries.rst b/source/libraries.rst index 7623963..2bc8b11 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -10,13 +10,13 @@ .. Note: if you port an Arduino library and document it here, be sure .. to update compatibility.rst to reflect that fact. -This page briefly summarizes the Arduino libraries that have been -ported to Maple. You can use a library from within a sketch by going -to Sketch > Import Library... from within the IDE, then choosing the -library you want. +This page lists the extra libraries that are part of the :ref:`Maple +IDE ` (along with the rest of :ref:`libmaple `). You +can use a library from within a sketch by going to Sketch > Import +Library... from within the IDE, then choosing the library you want. -Any incompatibilities between the Maple and Arduino versions are noted -in the description of the library. +Any incompatibilities between the Maple and Arduino versions of a +library are noted in the library's documentation. .. contents:: Contents :local: @@ -25,70 +25,47 @@ in the description of the library. :hidden: libs/servo.rst + libs/wire.rst -.. _libraries-servo: - -Servo ------ - -The Servo library is provided for convenient control of RC -servomotors. For more information, see the :ref:`Servo ` -reference. +.. admonition:: **Looking for Something Else?** -**Compatibility Note** + - See the :ref:`language` for information on the core functions + used for programming a Maple board. -The Servo class provides a public interface identical to the Arduino -version's documented functionality (as of Arduino 0021), so in most -cases, this library will be a drop-in replacement. + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + ` used to compile your programs is configured to link + against `newlib `_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. -However, there are some differences, essentially at the level of -implementation details. + - If you're looking for low-level hardware support libraries, see + the :ref:`libmaple Reference`. -The major difference is that while the Arduino implementation drives -the servos with "bit-banged" :ref:`PWM `, the Maple -implementation uses :ref:`timers ` to drive the PWM directly. - -Consequently, **the Maple implementation only allows Servo instances -to** :ref:`attach ` **to pins that support PWM**. - -To determine if a pin supports PWM (15 Maple pins do), you can either -check if "PWM" appears next to its number on the Maple silkscreen, or -consult the :ref:`pwmWrite() ` documentation. - -RC Servos expect a pulse approximately every 20ms. In the Maple -implementation, :ref:`periods ` are set -for entire timers, rather than individual channels. Thus, -``attach()``\ ing a Servo to a pin can interfere with other pins -associated with the same timer\ [#fard-servo]_. +.. _libraries-servo: -Because of this, we recommend connecting multiple servomotors to pins -which share a timer, in order to keep as many timers free for other -purposes as possible. Consult the :ref:`table provided in the timers -reference ` to match up pins and timer -channels. +Servo +----- -Another difference: although it is not publicly documented to do so, -the Arduino implementation of `attach() -`_ returns the timer -channel associated with the newly-attached pin, or 0 on failure (as of -Arduino 0021). The Maple implementation returns true on success, and -false on failure (and this is its documented behavior). +The :ref:`Servo ` library is provided for convenient +control of RC servomotors. .. _libraries-liquid-crystal: LiquidCrystal ------------- -.. TODO 0.0.10 make our own LiquidCrystal docs +.. TODO [0.1.0] LiquidCrystal docs under libs/liquidcrystal.rst The LiquidCrystal library allows Maple to control LCD screens. For more information, see the `Arduino LiquidCrystal documentation `_. -**Compatibility Note** +**Arduino Compatibility** At this time, no incompatibilities between the Maple and Arduino -versions are known. Any observed differences should be considered +versions are known (although the Maple version should perform +significantly faster). Any observed differences should be considered bugs, and reported on the forums. .. _libraries-wire: @@ -96,99 +73,8 @@ bugs, and reported on the forums. Wire ---- -We provide a soft (bit-banged) implementation of the `Wire I2C library -`_. - -**Compatibility Note** - -This implementation is synchronous, and thus supports only a subset of -the full Wire interface (however, the functionality which is supported -is fully compatible with Arduino). For now, please use the function -reference which follows when developing projects using our -implementation. - -Please note that the current implementation only supports master mode -using a bit-banged (software) protocol. Future enhancements will use -the hardware i2c peripheral on the stm32 as well as the DMA for -performance. Support for slave, smBUS, and multimaster modes are also -slated for inclusion in the enhanced Wire port. - -.. TODO 0.0.10 Wire docs in the cpp domain in own page under /libs/ - -Wire Function Reference -^^^^^^^^^^^^^^^^^^^^^^^ - -``Wire.begin()`` - Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL - (this is compatible with the pin settings on the Arduino Mega). - -``Wire.begin(sda, scl)`` - Like ``Wire.begin()``, but with the given pins as SDA and - SCL. - -``Wire.beginTransmission(slave_address)`` - Set up a transmission to a slave device with the given (7-bit) - address. Bytes subsequently queued for transmission (using - ``Wire.send``) will be sent to ``slave_address`` when ``void - Wire.endTransmission()`` is called. - -``void Wire.send(byte)`` - Queues the given byte (``uint8`` or ``int``) to the slave address - previously specified by a call to ``Wire.beginTransmission``. At - most 32 bytes may be queued in a single transmission. - -``Wire.send(string)`` - Queues a given string (``char*``) for transmission. The characters - of the string are individually queued for transmission as - bytes. At most 32 bytes may be queued in a single transmission. - -``Wire.send(buffer, length)`` - Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with - ``length`` elements, for transmission. At most 32 bytes may be - queued in a single transmission. - -``Wire.endTransmission()`` - Ends a transmission (begun by ``Wire.beginTransmission(uint8)``), - and actually sends the bytes queued by calls to Wire.send. - - The return value is one of the following status codes: - - * ``SUCCESS``: All bytes were transmitted successfully. - - * ``EDATA``: More than 32 bytes were queued for transmission. No - bytes are actually sent when this happens. - - * ``ENACKADDR``: Did not receive ACK on transmit of address. No - bytes are actually sent when this happens. - - * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some - bytes may have been sent when this happens; however, the - transmission is aborted after the first byte of data which is - not ACKed by the slave device. - - * ``EOTHER``: Other error occurred. - -``Wire.requestFrom(address, num_bytes)`` - Requests ``num_bytes`` bytes from 7-bit slave address - address. Returns the actual number of bytes read. These bytes may - subsequently be read one at a time using ``Wire.receive()``. - - Note: if ``num_bytes`` exceeds the size of the transmit/receive - buffer (currently 32), it will be truncated to 32. - -``Wire.receive()`` - Get and return the next byte read during the previous call to - ``Wire.requestFrom(uint8, int)``. You can check how many bytes are - left to read using ``uint8 Wire.available()``. - -``Wire.available()`` - Returns the number of bytes which are still available for reading - (with ``Wire.receive()``) from the last call to - ``Wire.requestFrom(uint8, int)``. - -.. rubric:: Footnotes +.. FIXME [0.1.0] Update with hard Wire implementation info -.. [#fard-servo] The Arduino implementation also captures timer - channels in groups as more Servo objects are attached, but the - details of which channels have their periods reset when are - slightly different. +We currently provide a soft (bit-banged) implementation of the +:ref:`Wire ` I2C library. A hardware version is planned +for Maple IDE release 0.1.0. diff --git a/source/libs/servo.rst b/source/libs/servo.rst index 475f7dd..891f151 100644 --- a/source/libs/servo.rst +++ b/source/libs/servo.rst @@ -2,9 +2,8 @@ .. _libs-servo: -======= - Servo -======= +Servo +===== .. FIXME [0.0.10] this is out of date @@ -16,7 +15,8 @@ You can use this library in the :ref:`IDE ` by choosing the Servo item under the Sketch > Import Library... menu. If you are using the :ref:`Unix toolchain `, the -library is located in ``$LIB_MAPLE_HOME/libraries/Servo/``. +library is located in the ``/libraries/Servo/`` :ref:`libmaple` +directory. Servo Class Reference --------------------- @@ -108,3 +108,54 @@ servomotor attached to pin 9, you could write :: microseconds. This will be clamped to lie in the [``min``, ``max``\ ] pulse width range set during :ref:`attach() `. + +Arduino Compatibility +--------------------- + +The Servo class provides a public interface identical to the Arduino +version's documented functionality (as of Arduino 0021), so in most +cases, this library will be a drop-in replacement. + +However, there are some differences, essentially at the level of +implementation details. + +The major difference is that while the Arduino implementation drives +the servos with "bit-banged" :ref:`PWM `, the Maple +implementation uses :ref:`timers ` to drive the PWM directly. + +Consequently, **the Maple implementation only allows Servo instances +to** :ref:`attach ` **to pins that support PWM**. + +To determine if a pin supports PWM (15 Maple pins do), you can either +check if "PWM" appears next to its number on the Maple silkscreen, or +consult the :ref:`pwmWrite() ` documentation. + +RC Servos expect a pulse approximately every 20ms. In the Maple +implementation, :ref:`periods ` are set +for entire timers, rather than individual channels. Thus, +``attach()``\ ing a Servo to a pin can interfere with other pins +associated with the same timer\ [#fard-servo]_. + +Because of this, we recommend connecting multiple servomotors to pins +which share a timer, in order to keep as many timers free for other +purposes as possible. Consult your board's :ref:`Timer Pin Map +` to match up pins and timer channels. + +Another difference: although it is not publicly documented to do so, +the Arduino implementation of `attach() +`_ returns the timer +channel associated with the newly-attached pin, or 0 on failure (as of +Arduino 0021). The Maple implementation returns :ref:`true +` on success, and :ref:`false +` on failure (and this is its documented +behavior). + +We currently provide a soft (bit-banged) implementation of the +:ref:`Wire ` I2C library. + +.. rubric:: Footnotes + +.. [#fard-servo] The Arduino implementation also captures timer + channels in groups as more Servo objects are attached, but the + details of which channels have their periods reset when are + slightly different. diff --git a/source/libs/wire.rst b/source/libs/wire.rst new file mode 100644 index 0000000..2c5bed9 --- /dev/null +++ b/source/libs/wire.rst @@ -0,0 +1,104 @@ +.. highlight:: cpp + +.. _libs-wire: + +Wire +==== + +.. TODO [0.1.0] Format this correctly, using Breathe + +This page documents the Wire library for the :ref:`i2c` protocol. You +can use this library in the :ref:`Maple IDE ` by choosing the +Wire item under the Sketch > Import Library... menu. + +If you are using the :ref:`Unix toolchain `, the +library is located in the ``/libraries/Wire/`` :ref:`libmaple` +directory. + +Wire Function Reference +----------------------- + +``Wire.begin()`` + Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL + (this is compatible with the pin settings on the Arduino Mega). + +``Wire.begin(sda, scl)`` + Like ``Wire.begin()``, but with the given pins as SDA and + SCL. + +``Wire.beginTransmission(slave_address)`` + Set up a transmission to a slave device with the given (7-bit) + address. Bytes subsequently queued for transmission (using + ``Wire.send``) will be sent to ``slave_address`` when ``void + Wire.endTransmission()`` is called. + +``void Wire.send(byte)`` + Queues the given byte (``uint8`` or ``int``) to the slave address + previously specified by a call to ``Wire.beginTransmission``. At + most 32 bytes may be queued in a single transmission. + +``Wire.send(string)`` + Queues a given string (``char*``) for transmission. The characters + of the string are individually queued for transmission as + bytes. At most 32 bytes may be queued in a single transmission. + +``Wire.send(buffer, length)`` + Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with + ``length`` elements, for transmission. At most 32 bytes may be + queued in a single transmission. + +``Wire.endTransmission()`` + Ends a transmission (begun by ``Wire.beginTransmission(uint8)``), + and actually sends the bytes queued by calls to Wire.send. + + The return value is one of the following status codes: + + * ``SUCCESS``: All bytes were transmitted successfully. + + * ``EDATA``: More than 32 bytes were queued for transmission. No + bytes are actually sent when this happens. + + * ``ENACKADDR``: Did not receive ACK on transmit of address. No + bytes are actually sent when this happens. + + * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some + bytes may have been sent when this happens; however, the + transmission is aborted after the first byte of data which is + not ACKed by the slave device. + + * ``EOTHER``: Other error occurred. + +``Wire.requestFrom(address, num_bytes)`` + Requests ``num_bytes`` bytes from 7-bit slave address + address. Returns the actual number of bytes read. These bytes may + subsequently be read one at a time using ``Wire.receive()``. + + Note: if ``num_bytes`` exceeds the size of the transmit/receive + buffer (currently 32), it will be truncated to 32. + +``Wire.receive()`` + Get and return the next byte read during the previous call to + ``Wire.requestFrom(uint8, int)``. You can check how many bytes are + left to read using ``uint8 Wire.available()``. + +``Wire.available()`` + Returns the number of bytes which are still available for reading + (with ``Wire.receive()``) from the last call to + ``Wire.requestFrom(uint8, int)``. + +Arduino Compatibility +--------------------- + +.. FIXME [0.1.0] Replace this section when i2c Wire wrapper is done + +This implementation is synchronous, and thus supports only a subset of +the full Wire interface (however, the functionality which is supported +is fully compatible with Arduino). For now, please use the function +reference which follows when developing projects using our +implementation. + +Please note that the current implementation only supports master mode +using a bit-banged (software) protocol. For now, use of the hardware +:ref:`i2c` peripheral is only available through :ref:`libmaple-i2c`. + + diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 899f720..c7596ce 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -6,7 +6,7 @@ Maple Quickstart Guide ======================== -.. TODO update the images since we changed "to FLASH" -> "to Flash" +.. TODO [0.1.0] Update the images; we've changed "to FLASH" -> "to Flash" You'll need a `Maple board `_, a `Mini-B USB cable `_, a @@ -73,12 +73,14 @@ window, and then a confirmation message will appear: Upload that program! -------------------- +.. FIXME [0.1.0 Maple-specific image; add one for Native] + Now it's time to plug in your Maple. Use a Mini-B cable, making sure -that the :ref:`power source jumper ` is on -the USB header first. We ship the Maple with the power source jumper -configured that way, so you shouldn't have to do anything. For -reference, it should look like this (don't worry if a jumper is -hanging half off of the CHRG header): +that the :ref:`power source jumper ` is on the USB +header first. We ship Maples with the power source jumper configured +that way, so you shouldn't have to do anything. For reference, it +should look like this (don't worry if a jumper is hanging half off of +the CHRG header): .. image:: /_static/img/plugged-in-maple.png :align: center diff --git a/source/pwm.rst b/source/pwm.rst index 1144d55..ac67689 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -19,29 +19,14 @@ filtering) generate audio waveforms. Overview -------- -The Maple has a large number of 16-bit PWM outputs, each connected to -one of 4 timers. Some configuration, such as the clock rate or -prescaling, must be common to the entire timer; see the :ref:`timer -documentation ` for more information. - -Note that unlike the Arduino, the Maple does not have PWM -functionality on pin D10; all other pins are :ref:`compatible -`. - -The following table shows which timer can generate which PWM -outputs. See the :ref:`pin mapping table ` to -track down exactly which timer *channel* corresponds to each pin. - -.. _pwm-timer-table: - -.. csv-table:: - :header: Timer, PWM Headers - :delim: | - - Timer1 | D6,D7,D8 - Timer2 | D0,D1,D2,D3 - Timer3 | D11,D12,D27,D28 - Timer4 | D5,D9,D14,D24 +.. FIXME [0.1.0] More information about how timer channels drive PWM + +Each PWM output is driven by an output channel connected to one of 4 +timers. Some configuration, such as the clock rate or prescaling, +must be common to the entire timer; see the :ref:`timer documentation +` for more information. See your board's :ref:`pin mapping +tables ` to track down the correspondence +between timer channels and GPIO pins. Background ---------- diff --git a/source/spi.rst b/source/spi.rst index ba43eef..2da4bf8 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -20,11 +20,15 @@ Recommended Reading * `Wikipedia Article on Serial Peripheral Interface Bus (SPI) `_ + * `Arduino reference on SPI `_ + * `Hardcore SPI on Arduino `_ by kik64 -* STMicro documentation for STM32F103RB microcontroller: - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) +* ST Documentation: + + * Reference Manual `RM0008 + `_ + (PDF), Chapter 25, "Serial Peripheral Interface" diff --git a/source/timers.rst b/source/timers.rst index 56dd686..cb30081 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -5,6 +5,8 @@ Timers ====== +.. FIXME [0.0.10] links to systick.h in a few places on this page + There are four general purpose timers in the Maple microcontroller that can be configured to generate periodic or delayed events with minimal work done by the microcontroller. For example, the :ref:`PWM @@ -43,164 +45,66 @@ event" interrupt is generated. You can configure the Maple to notify you when this takes place, by registering an interrupt handler, which is a function that will be called when the update event occurs. -libmaple Reference +Function Reference ------------------ -The libmaple API for interacting with timers is documented at the -:ref:`HardwareTimer reference `. +* :ref:`HardwareTimer ` Caveats ------- +Working with timers and interrupts can be tricky; they are a somewhat +"advanced" topic. The following subsections explain some common +problems associated with using timers and timer interrupts. + +In general: start simple, test with :ref:`ASSERT() `, +and don't try to do too much in your interrupt handlers! Make sure +that what you're trying to do in a handler isn't going to block other +interrupts from firing, if those other interrupts are important for +your program. + .. _timers-pwm-conflicts: -**PWM Conflicts:** Because PWM functionality on a given pin depends on +PWM Conflicts +^^^^^^^^^^^^^ + +Because PWM functionality on a given pin depends on the configuration of the timer and channel, you must chose your channels carefully if you want to use both timer interrupts and PWM in -the same program. Refer to the following table to match up timer -channels and Maple header pin numbers: - -.. _timers-pin-channel-map: - -.. csv-table:: - :header: Timer, Ch. 1 pin, Ch. 2 pin, Ch. 3 pin, Ch. 4 pin - - ``Timer1``, 6, 7, 8, -- - ``Timer2``, 2, 3, 1, 0 - ``Timer3``, 12, 11, 27, 28 - ``Timer4``, 5, 9, 14, 24 - -**Overhead:** there is some overhead associated with function and -interrupt calls (loading and unloading the stack, preparing state, -etc.) and this overhead can fudge your timing. Imperfect code -branching also means that, e.g., channel 1 interrupts may get called a -couple clock cycles sooner than a channel 4 interrupt, all other -configuration being the same. - -.. compound:: - - **Jitter:** other interrupts (USB, Serial, SysTick, or other - timers) can and will get called before or during the timer - interrupt routines, causing pseudorandom delays and other - frustrations. - - Disabling the USB port (by calling ``SerialUSB.end()``, or just - running off a battery) helps a lot, but then you lose the - auto-reset and communications functionality. This will require - that you put your Maple into :ref:`perpetual bootloader mode - ` before uploading a new - program to it (or somehow causing your program to re-enable serial - over USB using :ref:`SerialUSB.begin() `). - - Disabling SysTick with ``systick_disable()`` helps as well. - However, calling this function will break the ``micros()`` and - ``millis()`` functions. - -**General:** working with timers and interrupts can be tricky and hard -to debug; they are a somewhat "advanced" topic. Start simple, test -with :ref:`ASSERT() `, and don't try to do too much -in your interrupt handlers! Make sure that what you're trying to do in -a handler isn't going to block other interrupts from firing (e.g. USB, -Serial, SysTick) if those other interrupts are important for your -program. - -SysTick Peripheral ------------------- - -The SysTick peripheral allows another, simple way to perform periodic -or delayed events. This separate timer does not conflict with any -other peripherals, but the associated 1kHz interrupt can jitter the -general purpose timer interrupts; this is clearly seen when running -VGA code, where the timing jitters are transformed into visual jags in -the image. The SysTick peripheral can be disabled by calling -``systick_disable()``, and re-enabled using ``systick_resume()``. - -Code Examples -------------- - -LED blink -^^^^^^^^^ - -:: - - #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles - - void handler_led(void); - - void setup() - { - // Set up the LED to blink - pinMode(BOARD_LED_PIN, OUTPUT); - - // Setup Timer - Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer2.setPeriod(LED_RATE); // in microseconds - Timer2.setCompare1(1); // overflow might be small - Timer2.attachCompare1Interrupt(handler_led); - } - - void loop() { - // Nothing! It's all in the interrupts - } - - void handler_led(void) { - toggleLED(); - } - -Racing Counters -^^^^^^^^^^^^^^^ - -:: - - void handler_count1(void); - void handler_count2(void); - - int count1 = 0; - int count2 = 0; - - void setup() - { - // Set up BUT for input - pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); - - // Setup Counting Timers - Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer3.pause(); - Timer4.pause(); - Timer3.setCount(0); - Timer4.setCount(0); - Timer3.setOverflow(30000); - Timer4.setOverflow(30000); - Timer3.setCompare1(1000); // somewhere in the middle - Timer4.setCompare1(1000); - Timer3.attachCompare1Interrupt(handler1); - Timer4.attachCompare1Interrupt(handler2); - Timer3.resume(); - Timer4.resume(); - } - - void loop() { - // Display the running counts - SerialUSB.print("Count 1: "); - SerialUSB.print(count1); - SerialUSB.print("\t\tCount 2: "); - SerialUSB.println(count2); - - // Run... while BUT is held, pause Count2 - for(int i = 0; i<1000; i++) { - if(digitalRead(BOARD_BUTTON_PIN)) { - Timer4.pause(); - } else { - Timer4.resume(); - } - delay(1); - } - } - - void handler1(void) { - count1++; - } - void handler2(void) { - count2++; - } +the same program. Refer to your board's :ref:`Timer Pin Map +` to match up timer channels and pin numbers. + +Overhead +^^^^^^^^ + +There is some overhead associated with function and interrupt calls +(loading and unloading the stack, preparing state, etc.) and this +overhead can fudge your timing. Imperfect code branching also means +that, e.g., channel 1 interrupts may get called a couple clock cycles +sooner than a channel 4 interrupt, all other configuration being the +same. + +Jitter +^^^^^^ + +Other interrupts can and will get called before or during the timer +interrupt routines, causing pseudorandom delays and other +frustrations. + +Disabling the :ref:`USB ` port (by calling ``SerialUSB.end()``, +or just running off a battery) helps a lot, but then you lose the +auto-reset and communications functionality. This will require that +you put your Maple into :ref:`perpetual bootloader mode +` before uploading a new program +to it (or somehow causing your program to re-enable serial over USB +using :ref:`SerialUSB.begin() `). + +The SysTick peripheral another way to perform periodic or delayed +events. Its separate timer does not conflict with any other +peripherals, but the associated 1 kHz interrupt can jitter the general +purpose timer interrupts. The SysTick peripheral can be disabled by +calling :ref:`systick_disable() `, and +re-enabled using :ref:`systick_resume() `. +However, be aware that calling ``systick_disable()`` will stop the +values coming from :ref:`lang-micros` and :ref:`lang-millis` from +increasing. diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 2151171..f49580c 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -100,8 +100,6 @@ a board selected. The work-around is to restart the IDE. Mysterious! A classic! Make sure you have selected a board from the pulldown menu. -.. TODO: remove when Python version is released - ``undefined reference to setup()/loop()`` ----------------------------------------- @@ -133,8 +131,6 @@ There is an intermittent bug with the temporary directory build system that on occasion will lose many of the ``#include``\ d libmaple files. If you recompile everything, it should be fine. -.. TODO remove when the Python version is released - .. _troubleshooting-upload: ======================== diff --git a/source/usart.rst b/source/usart.rst index 3beb3fc..9506cc8 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -4,23 +4,34 @@ USART ======= -.. contents:: +.. contents:: Contents :local: Hardware/Circuit Design ----------------------- +.. FIXME [0.0.10] UART4 and UART5 +.. FIXME [0.1.0] Maple Native and Mini info and links + The Maple has 3 separate USART devices. In the most simple use case, the RX and TX pins are used to send data at a predetermined baudrate with the line voltage level relative to ground. Their usage is documented in the :ref:`Serial Ports ` language reference -page. +page. Which pins correspond to the USART TX and RX pins are given on +your board's silkscreen, and also in the board-specific USART pin maps +available here: + +* :ref:`Maple ` +* :ref:`Maple RET6 Edition ` + +If you use a particular serial port, you cannot also use its +communication pins for other purposes at the same time. Compatible Devices and Specifications ------------------------------------- -We have successfully used the Maple USART ports with an FT232R-based -USB-serial converter at up to 115200 baud; higher speeds should +We have successfully used the USART ports with an FT232R-based +USB-serial converter at up to 115200 baud. Higher speeds should certainly be possible. Recommended Reading diff --git a/source/usb.rst b/source/usb.rst index f040034..a67d710 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -2,34 +2,32 @@ .. _usb: -===== - USB -===== +USB +=== -The Maple STM32 microprocessor includes a dedicated USB peripheral -which can be configured to act as a general USB slave device with -transfer rates up to 12Mbps (it unfortunately can't be configured as a -host or on-the-go device). By default, the peripheral is configured -for two uses: first, to receive sketch/program uploads from the IDE, -and second, to emulate a regular serial port for use as a terminal -(text read/write). +The STM32 microprocessors include a dedicated USB peripheral which can +be configured to act as a general USB slave device with transfer rates +up to 12Mbps. (It unfortunately can't be configured as a host or +on-the-go device). By default, the peripheral is configured for two +uses: first, to receive sketch/program uploads from the :ref:`IDE +`, and second, to emulate a regular serial port for use as a +terminal (text read/write). The emulated terminal is relatively slow and inefficient; it is best for transferring data at regular serial speeds (kilobaud). Library support for accessing the emulated terminal is available at the :ref:`SerialUSB ` reference. -The SerialUSB channel is used as part of the auto-reset feature of the -IDE to program the board on Maple Rev 3 and Rev 5: a :ref:`magic -sequence of control line toggles and transmitted data -` causes the Maple to reset itself and enter -bootloader mode. As an unfortunate consequence, the auto-reset will -not work if the IDE can not access the serial port, either due to a -conflict with another program (serial monitor) or because the -interface has been disabled from the Maple side (through -:ref:`SerialUSB.end() `). A solution to the -second problem is the use of :ref:`perpetual bootloader mode -`. +The SerialUSB channel is used with the :ref:`Maple bootloader +` to reprogram the board: a :ref:`magic sequence of +control line toggles and transmitted data ` causes a +Maple to reset itself and enter bootloader mode. As an unfortunate +consequence, the auto-reset will not work if the IDE can not access +the serial port, either due to a conflict with another program (serial +monitor) or because the interface has been disabled from the Maple +side (through :ref:`SerialUSB.end() `). A +solution to the second problem is the use of :ref:`perpetual +bootloader mode `. Recommended Reading ------------------- @@ -40,9 +38,11 @@ Recommended Reading * `Embedded USB - a brief tutorial `_ * `Wikipedia article on Universal Serial Bus (USB) `_ * Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (pdf; assembly - language and register reference) +* ST documentation: + * Reference Manual `RM0008 + `_ + (PDF), Chapter 23, "Universal serial bus full-speed device + interface" + * `Programming Manual + `_ + (PDF; assembly language and register reference) -- cgit v1.2.3 From 763e7ffaea9fabf3de0245e9fd0280aa1c8dcbd3 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 28 Apr 2011 13:27:30 -0400 Subject: boardUsesPin() docs tweak. --- source/lang/api/boardusespin.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/lang/api/boardusespin.rst b/source/lang/api/boardusespin.rst index 8dc4c64..126c4a0 100644 --- a/source/lang/api/boardusespin.rst +++ b/source/lang/api/boardusespin.rst @@ -6,8 +6,9 @@ boardUsesPin() ============== Each LeafLabs board connects some pins to external hardware. The most -important examples of this are the built-in LED and button. You can -check if a board uses a particular pin using this function. +important examples of this are the pins connected to the built-in LED +and button. You can check if a board uses a particular pin using this +function. Library Documentation --------------------- @@ -24,4 +25,3 @@ See Also - :ref:`BOARD_BUTTON_PIN ` - :ref:`isButtonPressed() ` - :ref:`waitForButtonPress() ` - -- cgit v1.2.3 From f99f3935e31be17ec425540756d6e5e7deda4dd0 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 28 Apr 2011 13:52:58 -0400 Subject: SPI refactor. Still a polling driver, but the libmaple proper interface exposes enough that users enable the various interrupts and define their own IRQ handlers if they feel like it. Wirish HardwareSPI interface was largely redone; it's more like the Arduino implementation now, although there are some differences when I didn't like their API. The old methods are still there, but are deprecated and slated for deletion in 0.1.0. New board-specific values: BOARD_NR_SPI, BOARD_SPIx_NSS_PIN, BOARD_SPIx_MOSI_PIN, BOARD_SPIx_MISO_PIN, and BOARD_SPIx_SCK_PIN, for x from 1 to BOARD_NR_SPI. Documentation was updated appropriately. --- source/lang/api/hardwarespi.rst | 215 ++++++++++++++++++++-------------------- source/spi.rst | 6 +- 2 files changed, 109 insertions(+), 112 deletions(-) diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst index 53a225d..289ded5 100644 --- a/source/lang/api/hardwarespi.rst +++ b/source/lang/api/hardwarespi.rst @@ -5,160 +5,161 @@ HardwareSPI =========== -This class is used for creating objects to manage the Maple's built-in -SPI ports. The Maple has two SPI ports. The relevant pins -corresponding to each port's logic signals are documented in the -following table (and on the Maple silkscreen): +This page describes how to use the built-in SPI ports. It does not +describe the SPI protocol itself. For more information about SPI, see +the :ref:`SPI reference `. -.. _lang-hardwarespi-pinout: +.. contents:: Contents + :local: -.. list-table:: - :header-rows: 1 +Getting Started +--------------- - * - Port number - - NSS - - MOSI - - MISO - - SCK +.. TODO [0.1.0] Add a note about calling disableDebugPorts() when +.. using SPI3 on Maple Native - * - 1 - - 10 - - 11 - - 12 - - 13 +In order to get started, you'll first need to define a ``HardwareSPI`` +variable, which you'll use to control the SPI port. Do this by +putting the line "``HardwareSPI spi(number);``" with your variables, +where ``number`` is the SPI port's number. - * - 2 - - 31 - - 32 - - 33 - - 34 +Here's an example (we'll fill in :ref:`setup() ` and +:ref:`loop() ` later):: -If you use a SPI port, you cannot simultaneously use its associated -pins for other purposes. + // Use SPI port number 1 + HardwareSPI spi(1); -Library Documentation ---------------------- + void setup() { + // Your setup code + } + + void loop() { + // Do stuff with SPI + } -Using the SPI Class -^^^^^^^^^^^^^^^^^^^ +Turning the SPI Port On +----------------------- -You can declare that you want to use SPI in your sketch by putting -``HardwareSPI Spi(number);`` with your variables, where ``number`` is -1 or 2, depending on which SPI you want to use. Then you can use the -functions described in the next section. For example:: +Now it's time to turn your SPI port on. Do this with the ``begin()`` +function (an example is given below). - // Use SPI 1 - HardwareSpi Spi(1); +.. FIXME [0.0.10] Breathe doesn't include the class; fix & submit pull req + +.. doxygenfunction:: HardwareSPI::begin + +The speed at which the SPI port communicates is configured using a +``SPIFrequency`` value: + +.. FIXME [0.1.0] Breathe's enum output is enormous; shrink & submit pull req + +.. doxygenenum:: SPIFrequency + +.. note:: Due to hardware issues, you can't use the frequency + ``SPI_140_625KHz`` with SPI port 1. + +You'll need to determine the correct values for ``frequency``, +``bitOrder``, and ``mode`` yourself, by consulting the datasheet for +the device you're communicating with. Continuing our example from +before, we'll add a call to ``begin()`` to our ``setup()``:: + + // Use SPI port number 1 + HardwareSPI spi(1); void setup() { - Spi.begin(SPI_18MHZ); + // Turn on the SPI port + spi.begin(SPI_18MHZ, MSBFIRST, 0); } void loop() { - // Get the next byte from the peripheral - uint8 byte = Spi.recv(); + // Do stuff with SPI } -HardwareSPI Class Reference -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you call ``begin()`` with no arguments (as in "``spi.begin();``"), +it's the same as if you wrote "``spi.begin(SPI_1_125MHZ, MSBFIRST, +0);``". -.. cpp:class:: HardwareSPI +Communicating Over SPI +---------------------- - Class for interacting with SPI. +Now that you've got your SPI port set up, it's time to start +communicating. You can send data using ``HardwareSPI::write()``, +receive data using ``HardwareSPI::read()``, and do both using +``HardwareSPI::transfer()``. -.. cpp:function:: HardwareSPI::HardwareSPI(uint32 spi_num) +.. cpp:function:: void HardwareSPI::write(byte data) - Construct an object for managing a SPI peripheral. ``spi_num`` - must be 1 or 2; see the :ref:`table above - ` for pinout information. + Send a single byte of data. -.. cpp:function:: void HardwareSPI::begin(SPIFrequency freq, uint32 endianness, uint32 mode) + **Parameters**: - Configure the baudrate of the given SPI port and set up the header - pins appropriately. + - ``data``: Byte to send - Parameters: +.. cpp:function:: byte HardwareSPI::read() - - ``freq``: one of the ``SPIFrequency`` values, given :ref:`below - `. + Get the next available, unread byte. If there aren't any unread + bytes, this function will wait until one is received. - - ``endianness``: either ``LSBFIRST`` (little-endian) or - ``MSBFIRST`` (big-endian). +.. cpp:function:: byte HardwareSPI::transmit(byte data) - - ``mode``: one of 0, 1, 2, or 3, and specifies which SPI mode is - used. The mode number determines a combination of polarity and - phase according to the following table: + Send a byte, then return the next byte received. - .. list-table:: - :header-rows: 1 + **Parameters:** - * - Mode - - Polarity - - Phase + - ``data``: Byte to send - * - 0 - - 0 - - 0 + **Returns:** Next unread byte - * - 1 - - 0 - - 1 +Continuing our example from before, let's send a number over SPI and +print out whatever we get back over :ref:`lang-serialusb`:: - * - 2 - - 1 - - 0 + // Use SPI port number 1 + HardwareSPI spi(1); - * - 3 - - 1 - - 1 + void setup() { + // Turn on the SPI port + spi.begin(SPI_18MHZ, MSBFIRST, 0); + } - For more information on polarity and phase, see the - :ref:`external references, below `. + void loop() { + // Send 245 over SPI, and wait for a response. + spi.write(245); + byte response = spi.read(); + // Print out the response received. + SerialUSB.print("response: "); + SerialUSB.println(response, DEC); + } + +HardwareSPI Class Reference +--------------------------- + +There are a number of other things you can accomplish with your +``spi`` object. A full function listing follows. -.. cpp:function:: void HardwareSPI::begin() +.. doxygenclass:: HardwareSPI + :members: HardwareSPI, begin, beginSlave, end, read, write, transfer - A convenience ``begin()``, equivalent to ``begin(SPI_1_125MHZ, - MSBFIRST, 0)``. +Deprecated Functions +-------------------- -.. cpp:function:: uint8 HardwareSpi::send(uint8 *data, uint32 length) +The following functions are defined for now, but they have been +deprecated, and will be removed in a future Maple IDE release. You +shouldn't use them in new programs, and you should change any of your +programs which do use them to the up-to-date functions discussed +above. + +.. cpp:function:: uint8 HardwareSPI::send(uint8 *data, uint32 length) Writes ``data`` into the port buffer to be transmitted as soon as possible, where ``length`` is the number of bytes to send from ``data``. Returns the last byte shifted back from slave. -.. cpp:function:: uint8 HardwareSpi::send(uint8 data) +.. cpp:function:: uint8 HardwareSPI::send(uint8 data) Writes the single byte ``data`` into the port buffer to be transmitted as soon as possible. Returns the data byte shifted back from the slave. -.. cpp:function:: uint8 HardwareSpi::recv() +.. cpp:function:: uint8 HardwareSPI::recv() Reads a byte from the peripheral. Returns the next byte in the buffer. - -SPI Speeds -^^^^^^^^^^ - -.. _lang-hardwarespi-spifrequency: - -The possible SPI speeds are configured using the ``SPIFrequency`` enum: - -.. doxygenenum:: SPIFrequency - -.. _lang-hardwarespi-seealso: - -See Also --------- - -* `Wikipedia Article on Serial Peripheral Interface Bus (SPI) - `_ -* `Arduino reference on SPI - `_ -* `Hardcore SPI on Arduino `_ by kik64 -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - - diff --git a/source/spi.rst b/source/spi.rst index 2da4bf8..dd9f1f5 100644 --- a/source/spi.rst +++ b/source/spi.rst @@ -8,12 +8,8 @@ The Serial Peripheral Interface Bus (SPI) is a serial data transfer protocol useful for interacting with a wide variety of hardware peripherals. -The Maple has two SPI ports. The first has NSS on D10, MOSI on -D11, MISO on D12, and SCK on D13. The second has NSS on D31, SCK on -D32, MISO on D33, and MOSI on D34. - The public libmaple API for managing the SPI ports is the -:ref:`HardwareSpi ` class. +:ref:`HardwareSPI ` class. Recommended Reading ------------------- -- cgit v1.2.3 From 2204cbabd91d0823fded18b7b03d773e6f56111c Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 4 May 2011 13:15:33 -0400 Subject: SerialUSB fixups. --- source/lang/api/serialusb.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst index ee7146e..ed466f2 100644 --- a/source/lang/api/serialusb.rst +++ b/source/lang/api/serialusb.rst @@ -16,9 +16,8 @@ Introduction In addition to three :ref:`serial ports `, the Maple's STM32 microprocessor includes a dedicated USB peripheral. This peripheral is used to emulate a regular serial port for use as a -terminal (text read/write). The emulated terminal is relatively slow -and inefficient; it is best for transferring data at regular serial -speeds (kilobaud). +terminal. The emulated terminal is relatively slow; it is best for +transferring data at regular serial speeds (kilobaud). Library access to the emulated serial port is provided through the ``SerialUSB`` object. You can mostly use ``SerialUSB`` as a drop-in @@ -30,14 +29,14 @@ replacement for ``Serial1``, ``Serial2``, and ``Serial3``. This means that if you have a number of calls to one of the ``SerialUSB`` ``write()`` or ``print()`` functions in your code, - and you are not monitoring the emulated on a computer, your program - will run much, much slower than if it is being monitored or totally - disconnected (run off of a battery). + and you are not monitoring ``SerialUSB`` on a computer, your + program will run much slower than if it is being monitored or + totally disconnected (run off of a battery). You can avoid this behavior by :ref:`deciphering the port status - using the DTR and RTS line status `; the + using the DTR and RTS line status ` (the behavior of these control lines is platform dependent and we no - longer interpret them by default. + longer interpret them by default). Library Documentation --------------------- -- cgit v1.2.3 From ba2883d21a4a1f8598bf6eaae667a6bb4d86943d Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 5 May 2011 16:17:16 -0400 Subject: Documentation link fixes. Fixing some Sphinx error messages. --- source/hardware/maple.rst | 2 ++ source/lang/cpp/built-in-types.rst | 31 ++++++++++++++++++------------- source/libraries.rst | 2 +- source/pwm.rst | 2 +- source/troubleshooting.rst | 6 +++--- 5 files changed, 25 insertions(+), 18 deletions(-) diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 44848a7..f4fcaf4 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -313,6 +313,8 @@ Rev 3 * **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the corresponding "AIN" is missing from the Rev 3 silkscreen. +.. _maple-rev3-bad-buttons: + * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 have questionable RESET and BUT buttons. diff --git a/source/lang/cpp/built-in-types.rst b/source/lang/cpp/built-in-types.rst index a7349e6..28e8cdc 100644 --- a/source/lang/cpp/built-in-types.rst +++ b/source/lang/cpp/built-in-types.rst @@ -41,55 +41,60 @@ Integral types .. cpp:type:: int8 - Synonym for ``char``. + 8-bit integer value. Synonym for ``signed char``. .. cpp:type:: uint8 - Synonym for ``unsigned char``. + 8-bit unsigned integer value. Synonym for ``unsigned char``. + +.. cpp:type:: byte + + 8-bit unsigned integer value. Synonym for ``unsigned char``. .. cpp:type:: int16 - Synonym for ``short``. + 16-bit integer value. Synonym for ``short``. .. cpp:type:: uint16 - Synonym for ``unsigned short``. + 16-bit unsigned integer value. Synonym for ``unsigned short``. .. cpp:type:: int32 - Synonym for ``int``. + 32-bit integer value. Synonym for ``int``. .. cpp:type:: uint32 - Synonym for ``unsigned int`` + Unsigned 32-bit integer value. Synonym for ``unsigned int`` .. cpp:type:: int64 - Synonym for ``long long`` + 64-bit integer value. Synonym for ``long long`` .. cpp:type:: uint64 - Synonym for ``unsigned long long``. + Unsigned 64-bit integer value. Synonym for ``unsigned long long``. Floating-Point Types -------------------- .. cpp:type:: float - 32-bit, IEEE 754 single-precision floating-point type. + 32-bit, IEEE-754 single-precision floating-point type. .. cpp:type:: double - 64-bit, IEEE 754 double-precision floating-point type. + 64-bit, IEEE-754 double-precision floating-point type. Other Types ----------- .. cpp:type:: voidFuncPtr - Pointer to a function that takes no arguments and returns nothing, i.e. - - :: + Pointer to a function that takes no arguments and returns nothing, i.e. :: typedef void (*voidFuncPtr)(void); +.. cpp:type:: bool + + Boolean type. diff --git a/source/libraries.rst b/source/libraries.rst index 2bc8b11..44a72f7 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -40,7 +40,7 @@ library are noted in the library's documentation. (``malloc()``, etc.) is not available. - If you're looking for low-level hardware support libraries, see - the :ref:`libmaple Reference`. + the :ref:`libmaple Reference `. .. _libraries-servo: diff --git a/source/pwm.rst b/source/pwm.rst index ac67689..34ad508 100644 --- a/source/pwm.rst +++ b/source/pwm.rst @@ -25,7 +25,7 @@ Each PWM output is driven by an output channel connected to one of 4 timers. Some configuration, such as the clock rate or prescaling, must be common to the entire timer; see the :ref:`timer documentation ` for more information. See your board's :ref:`pin mapping -tables ` to track down the correspondence +tables ` to track down the correspondence between timer channels and GPIO pins. Background diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index f49580c..bf1b129 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -48,9 +48,9 @@ The reset and D38/serial buttons don't seem to work reliably! ------------------------------------------------------------- A few Maple Rev3 boards shipped in May-June 2010 may have had -unreliable buttons; see the :ref:`errata page ` for -details. `We're happy to replace these for you -`_\ ! +unreliable buttons; see the :ref:`Maple Errata +` for details. `We're happy to replace these +for you `_\ ! .. _troubleshooting-ide-install: -- cgit v1.2.3 From b1f6476ba450121af95c9f8e74adfbc6ece03ef4 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 5 May 2011 17:18:25 -0400 Subject: Putting updated HardwareTimer back into the build. HardwareTimer was removed from the build when the timer refactor was done; this redoes it in terms of the new timer.h interface. A variety of conflicting or badly designed bits were deprecated or removed. I'm still not satisfied with this interface, as it's going to make life difficult moving forward to high-density chips, where the addition of basic timers means that the capture/compare methods won't apply in some cases. However, we need to get 0.0.10 out the door, so it'll have to do for now. The docs are up to date, and contain a warning that the Wirish API isn't stable and a recommendation to use libmaple proper. --- source/lang/api/analogwrite.rst | 24 +- source/lang/api/hardwaretimer.rst | 579 +++++++++++++++----------------------- source/timers.rst | 10 + 3 files changed, 256 insertions(+), 357 deletions(-) diff --git a/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst index e789305..dd2192a 100644 --- a/source/lang/api/analogwrite.rst +++ b/source/lang/api/analogwrite.rst @@ -52,7 +52,7 @@ you much more precise control over the duty cycle of your PWM output. If you're porting code from the Arduino and want a quick-and-dirty fix, one solution is to :ref:`map ` the argument to -analogWrite into the right range:: +analogWrite() into the right range:: // Arduino code: analogWrite(pin, duty); @@ -71,8 +71,8 @@ that Timer's overflow to 255. Subsequent calls to analogWrite() should work as on the Arduino (with the same loss of precision). Note, however, that that affects the overflow for the **entire timer**, so other code relying on that timer (such as any -:ref:`interrupts ` the timer controls) will -likely need to be modified as well. +:ref:`interrupts ` the timer controls) +will likely need to be modified as well. Difference 2: You must use pinMode() to set up PWM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -141,23 +141,27 @@ the steps are: 1. Figure out which :ref:`timer ` controls PWM output on your pin (\ :ref:`your board's Timer Pin Map - ` is your friend here). Let's say it's ``Timern``\ - , where ``n`` is some number 1, 2, 3, or 4. + ` is your friend here). -2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's - period to approximately 2041 microseconds, which is a frequency of - approximately 490 Hz. +2. Let's say it's timer ``n``, where ``n`` is some number. You'll + then need to put "``HardwareTimer timer(n);``" with your variables, + as described in the :ref:`HardwareTimer + ` reference. + +3. In your :ref:`lang-setup`, put "``timer.setPeriod(2041);``". This + will set the timer's period to approximately 2041 microseconds, + which is a frequency of approximately 490 Hz. Be aware that this will change the period for the **entire timer**\ , and will affect anything else in your program that depends on that timer. The important examples are :ref:`timer interrupts -` and :ref:`PWM +` and :ref:`PWM `\ . See Also -------- -- :ref:`Maple PWM tutorial ` +- :ref:`pwm` .. rubric:: Footnotes diff --git a/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst index 526beb6..09245f0 100644 --- a/source/lang/api/hardwaretimer.rst +++ b/source/lang/api/hardwaretimer.rst @@ -5,456 +5,341 @@ HardwareTimer ============= -This class defines the public API for interfacing with the STM32's -built-in timer peripherals. More information on these peripherals -(including code examples) is available in the :ref:`timers reference -`. +This page describes how to control the built-in timers. It does not +describe how the timers work on your board. For more information on +that, the :ref:`timers reference `. -.. FIXME [0.0.10] Updated HardwareTimer documentation, with deprecation +.. warning:: The timer interface is still taking shape, and is + expected to change significantly between releases. Because of + that, the functionality described in this page shouldn't be + considered stable. -.. warning:: This class has been deprecated. It is not available in - the current build. + If you want a timer API that will be consistent between releases of + the Maple IDE, your best bet for now is to use the low-level + support in :ref:`libmaple-timer`. -Library Documentation ---------------------- +.. contents:: Contents + :local: -HardwareTimer Class Reference -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _lang-hardwaretimer-getting-started: -To interact with a particular timer, call one of the methods -documented below on one of the predefined ``HardwareTimer`` instances. -For example, to set the prescale factor on timer 1 to 5, call -``Timer1.setPrescaleFactor(5)``. +Getting Started +--------------- -.. TODO add tutorial-style examples +You'll first need to define a ``HardwareTimer`` variable, which you'll +use to control the timer. Do this by putting the line +"``HardwareTimer timer(number);``" with your variables, where +``number`` is the timer's number. -.. cpp:class:: HardwareTimer +Here's an example (we'll fill in :ref:`setup() ` and +:ref:`loop() ` later):: - Class for interacting with a timer. There are four predefined - instances available on the Maple: ``Timer1``, ``Timer2``, - ``Timer3``, and ``Timer4``. + // Use timer 1 + HardwareTimer timer(1); -.. _lang-hardwaretimer-attachinterrupt: + void setup() { + // Your setup code + } -.. cpp:function:: void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler) + void loop() { + // ... + } - Attach an interrupt handler to the given ``channel``. This - interrupt handler will be called when the timer's counter reaches - the given channel :ref:`compare ` - value. +Configuring the Prescaler and Overflow +-------------------------------------- - ``handler`` should be a function which takes no arguments and has - :ref:`void ` value; i.e. it should have signature :: +After defining your ``timer`` variable, you'll probably want to +configure how fast your timer's counter changes (using the prescaler) +and when it gets reset to zero (using the overflow value). You can do +that with the ``setPrescaleFactor()`` and ``setOverflow()`` functions. - void handler(void); - - You can later detach the interrupt using :ref:`detachInterrupt() - `. - - .. note:: The function (often called an *interrupt service - routine*, or ISR) should attempt to return as quickly as - possible. :ref:`Blinking the LED `, some - logic, :ref:`PWM ` updates, and :ref:`Serial - ` writes are fine; writing to - :ref:`SerialUSB ` or :ref:`waiting - ` for user input can take a long - time and prevent other interrupts from firing on time. - - Tip: if you have a :ref:`delay() ` in your - ISR, you're probably doing it wrong. - -.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(1, handler)``. - -.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(2, handler)``. - -.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(3, handler)``. - -.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(4, handler)``. - -.. _lang-hardwaretimer-setchannelmode: - -.. cpp:function:: void HardwareTimer::setChannelMode(int channel, TimerMode mode) - - Set the given channel of this timer to the given :ref:`mode - `. The parameter ``channel`` is one of - 1, 2, 3, and 4, and corresponds to the compare channel you would - like to set. Refer to your board's :ref:`master pin map - ` to match up timer channels and pin numbers. - -.. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(1, mode)``. - -.. cpp:function:: void HardwareTimer::setChannel2Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(2, mode)``. - -.. cpp:function:: void HardwareTimer::setChannel3Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(3, mode)``. - -.. cpp:function:: void HardwareTimer::setChannel4Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(4, mode)``. - -.. _lang-hardwaretimer-getcompare: - -.. cpp:function:: uint16 HardwareTimer::getCompare(int channel) - - Gets the compare value for the given ``channel``, from 1 to 4. See - :ref:`setCompare() `. - -.. cpp:function:: uint16 HardwareTimer::getCompare1() - - Equivalent to :ref:`getCompare `\ - ``(1, mode)``. - -.. cpp:function:: uint16 HardwareTimer::getCompare2() - - Equivalent to :ref:`getCompare `\ - ``(2, mode)``. - -.. cpp:function:: uint16 HardwareTimer::getCompare3() - - Equivalent to :ref:`getCompare `\ - ``(3, mode)``. - -.. cpp:function:: uint16 HardwareTimer::getCompare4() +.. _lang-hardwaretimer-setprescalefactor: - Equivalent to :ref:`getCompare `\ - ``(4, mode)``. +.. doxygenfunction:: HardwareTimer::setPrescaleFactor + :no-link: -.. _lang-hardwaretimer-setcompare: +.. _lang-hardwaretimer-setoverflow: -.. cpp:function:: void HardwareTimer::setCompare(int channel, uint16 compare) +.. doxygenfunction:: HardwareTimer::setOverflow + :no-link: - Sets the compare value for the given ``channel`` to ``compare``. - If ``compare`` is greater than this timer's overflow value, it will - be truncated to the overflow value. The default compare value is - 65,535 (the largest unsigned 16-bit integer value). +For example:: - When the counter reaches this value the interrupt for this channel - will fire if the given ``channel`` :ref:`mode - ` is ``TIMER_OUTPUTCOMPARE`` and - an interrupt is :ref:`attached - `. + // Use timer 1 + HardwareTimer timer(1); - By default, this only changes the relative offsets between events - on a single timer ("phase"); they don't control the frequency with - which they occur. However, a common trick is to increment the - compare value manually in the interrupt handler so that the event - will fire again after the increment period. There can be a - different increment value for each channel, so this trick allows - events to be programmed at 4 different rates on a single - timer. Note that function call overheads mean that the smallest - increment rate is at least a few microseconds. + void setup() { + timer.setPrescaleFactor(5); + timer.setOverflow(255); + } -.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) + void loop() { + // ... + } - Equivalent to :ref:`setCompare `\ - ``(1, compare)``. +You may also find the ``setPeriod()`` function useful: -.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) +.. _lang-hardwaretimer-setperiod: - Equivalent to :ref:`setCompare `\ - ``(2, compare)``. +.. doxygenfunction:: HardwareTimer::setPeriod + :no-link: -.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) +For example:: - Equivalent to :ref:`setCompare `\ - ``(3, compare)``. + // Use timer 1 + HardwareTimer timer(1); -.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) + void setup() { + // Have the timer repeat every 20 milliseconds + int microseconds_per_millisecond = 1000; + timer.setPeriod(20 * microseconds_per_millisecond); + } - Equivalent to :ref:`setCompare `\ - ``(4, compare)``. + void loop() { + // ... + } -.. cpp:function:: uint16 HardwareTimer::getCount() +.. _lang-hardwaretimer-interrupts: - Gets the current timer count. Due to function call overhead, the - return value will be increasingly accurate with smaller prescale - values. Also see :ref:`setCount() `. +Using Timer Interrupts +---------------------- -.. _lang-hardwaretimer-setcount: +.. TODO [0.2.0] Improve the interrupts section, here or in timers.rst -.. cpp:function:: void HardwareTimer::setCount(uint16 val) +In order to use timer interrupts, we recommend the following sequence: - Set the timer's current count to ``val``. +* Pause the timer. +* Configure the prescaler and overflow. +* Pick a timer channel to handle the interrupt and set the channel's + :ref:`mode ` to ``TIMER_OUTPUT_COMPARE``. +* Set the channel compare value appropriately (this controls what counter value, + from 0 to overflow - 1). If you just want to make the interrupt fire once + every time the timer overflows, and you don't care what the timer count is, + the channel compare value can just be 1. +* Attach an interrupt handler to the channel. +* Refresh the timer. +* Resume the timer. - Note that there is some function call overhead associated with - calling this method, so using it is not a robust way to get - multiple timers to share a count value. +Here are two complete examples. - If ``val`` exceeds the timer's :ref:`overflow value - `, it is truncated to the overflow - value. +**LED blink**: This example blinks the built-in LED without doing +anything in ``loop()``. :: + #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles -.. _lang-hardwaretimer-detachinterrupt: - -.. cpp:function:: void HardwareTimer::detachInterrupt(int channel) + // We'll use timer 2 + HardwareTimer timer(2); - Remove the interrupt handler attached to the given ``channel``, if - any. The handler will no longer be called by this timer. + void setup() { + // Set up the LED to blink + pinMode(BOARD_LED_PIN, OUTPUT); -.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() + // Pause the timer while we're configuring it + timer.pause(); - Equivalent to :ref:`detachInterrupt - `\ ``(1)``. + // Set up period + timer.setPeriod(LED_RATE); // in microseconds -.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() + // Set up an interrupt on channel 1 + timer.setChannel1Mode(TIMER_OUTPUT_COMPARE); + timer.setCompare(TIMER_CH1, 1); // Interrupt 1 count after each update + timer.attachCompare1Interrupt(handler_led); - Equivalent to :ref:`detachInterrupt - `\ ``(2)``. + // Refresh the timer's count, prescale, and overflow + timer.refresh(); -.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() + // Start the timer counting + timer.resume(); + } - Equivalent to :ref:`detachInterrupt - `\ ``(3)``. + void loop() { + // Nothing! It's all in the handler_led() interrupt: + } -.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() + void handler_led(void) { + toggleLED(); + } - Equivalent to :ref:`detachInterrupt - `\ ``(4)``. +**Racing Counters**: This example shows how to use multiple timers at +the same time. :: -.. _lang-hardwaretimer-generateupdate: + int count3 = 0; + int count4 = 0; -.. cpp:function:: void HardwareTimer::generateUpdate() + // We'll use timers 3 and 4 + HardwareTimer timer3(3); + HardwareTimer timer4(4); - Re-initializes the counter (to 0 in upcounting mode, which is the - default), and generates an update of the prescale and overflow - registers. + void setup() { + // Set up the button for input + pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); -.. _lang-hardwaretimer-getoverflow: + // Set up timers to add 1 to their counts each time + // their interrupts fire. + timer3.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE); + timer4.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE); + timer3.pause(); + timer4.pause(); + timer3.setCount(0); + timer4.setCount(0); + timer3.setOverflow(30000); + timer4.setOverflow(30000); + timer3.setCompare(TIMER_CH1, 1000); // somewhere in the middle + timer4.setCompare(TIMER_CH1, 1000); + timer3.attachCompare1Interrupt(handler3); + timer4.attachCompare1Interrupt(handler4); + timer3.refresh(); + timer4.refresh(); + timer3.resume(); + timer4.resume(); + } -.. cpp:function:: uint16 HardwareTimer::getOverflow() + void loop() { + // Display the running counts + SerialUSB.print("Count 3: "); + SerialUSB.print(count3); + SerialUSB.print("\t\tCount 4: "); + SerialUSB.println(count4); + + // While the button is held down, pause timer 4 + for (int i = 0; i < 1000; i++) { + if (digitalRead(BOARD_BUTTON_PIN)) { + timer4.pause(); + } else { + timer4.resume(); + } + delay(1); + } + } - Gets the timer's overflow value. See :ref:`setOverflow() - `. + void handler3(void) { + count3++; + } -.. _lang-hardwaretimer-setoverflow: + void handler4(void) { + count4++; + } -.. cpp:function:: void HardwareTimer::setOverflow(uint16 val) +``HardwareTimer`` Class Reference +--------------------------------- - Sets the timer overflow (or "reload") value to ``val``. +This section gives a full listing of the capabilities of a +``HardwareTimer``. - When the timer's counter reaches this, value it resets to - zero. Its default value is 65535 (the largest unsigned 16-bit - integer); setting the overflow to anything lower will cause - interrupts to be called more frequently (see :ref:`setPeriod() - ` function for a shortcut). +.. doxygenclass:: HardwareTimer + :members: HardwareTimer, pause, resume, getPrescaleFactor, setPrescaleFactor, getOverflow, setOverflow, getCount, setCount, setPeriod, setMode, getCompare, setCompare, attachInterrupt, detachInterrupt, refresh - After the next :ref:`timer update - `, this number will be the - maximum value for the timer's channel compare values. +.. _lang-hardwaretimer-timermode: -.. _lang-hardwaretimer-pause: +.. doxygenenum:: timer_mode -.. cpp:function:: void HardwareTimer::pause() +Deprecated Functionality +------------------------ - Stop the timer's counter, without affecting its configuration. +The following functionality exists for now, but it has been +deprecated, and will be removed in a future Maple IDE release. You +shouldn't use it in new programs, and you should change any of your +programs which do use them to use the up-to-date features described +above. - The timer will no longer count or fire interrupts after this - function is called, until it is resumed. This function is useful - during timer setup periods, in order to prevent interrupts from - firing before the timer is fully configured. +The ``TimerMode`` type from previous releases has been renamed +``timer_mode``. The mode ``TIMER_OUTPUTCOMPARE`` is still present, +but will be removed in a future release. Use ``TIMER_OUTPUT_COMPARE`` +instead. - Note that there is some function call overhead associated with this - method, so using it in concert with :ref:`resume() - ` is not a robust way to align multiple - timers to the same count value. +.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) -.. _lang-hardwaretimer-setperiod: + Use ``attachInterrupt(1, handler)`` instead. -.. cpp:function:: uint16 HardwareTimer::setPeriod(uint32 microseconds) +.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) - Configure the :ref:`prescaler - ` and :ref:`overflow - ` values to generate a timer reload - with a period as close to the given number of ``microseconds`` as - possible. + Use ``attachInterrupt(2, handler)`` instead. - The return value is the new overflow value, which may be used to - set channel compare values. However, if a clock that fires an - interrupt every given number of microseconds is all that is - desired, and the relative "phases" are unimportant, channel compare - values may all be set to 1. +.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) -.. _lang-hardwaretimer-getprescalefactor: + Use ``attachInterrupt(3, handler)`` instead. -.. cpp:function:: uint16 HardwareTimer::getPrescaleFactor() +.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) - Returns the timer's prescale factor. See - :ref:`setPrescaleFactor() `. + Use ``attachInterrupt(4, handler)`` instead. -.. _lang-hardwaretimer-setprescalefactor: +.. _lang-hardwaretimer-setchannelmode: -.. cpp:function:: void HardwareTimer::setPrescaleFactor(uint16 factor) +.. cpp:function:: void HardwareTimer::setChannelMode(int channel, timer_mode mode) - Set the timer's prescale factor to ``factor``. + Use ``setMode(channel, mode)`` instead. - The prescaler acts as a clock divider to slow down the rate at - which the counter increments. +.. cpp:function:: void HardwareTimer::setChannel1Mode(timer_mode mode) - For example, the system clock rate is 72MHz, so the counter will - reach 65535 in (13.89 nanoseconds) × (65535 counts) = (910.22 - microseconds), or about a thousand times a second. If the - prescaler equals 1098, then the clock rate is effectively 72MHz / - 1098 = 65.56KHz, and the counter will reach 65536 in (15.25 - microseconds) × (65536 counts) = (0.999 seconds), or about once - per second. + Use ``setMode(1, mode)`` instead. - The :ref:`setPeriod() ` method may - also be used as a convenient alternative. +.. cpp:function:: void HardwareTimer::setChannel2Mode(timer_mode mode) -.. _lang-hardwaretimer-resume: + Use ``setMode(2, mode)`` instead. -.. cpp:function:: void HardwareTimer::resume() +.. cpp:function:: void HardwareTimer::setChannel3Mode(timer_mode mode) - Resume a paused timer, without affecting its configuration. + Use ``setMode(3, mode)`` instead. - The timer will resume counting and firing interrupts as - appropriate. +.. cpp:function:: void HardwareTimer::setChannel4Mode(timer_mode mode) - Note that there is some function call overhead associated with - using this method, so using it in concert with :ref:`pause() - ` is not a robust way to align multiple - timers to the same count value. + Use ``setMode(4, mode)`` instead. -.. cpp:function:: timer_dev_num HardwareTimer::getTimerNum() +.. cpp:function:: uint16 HardwareTimer::getCompare1() - Returns the :ref:`timer device number - ` associated with the timer. For - example, ``Timer1.getTimerNum()`` would return ``TIMER1``. + Use ``getCompare(1, mode)`` instead. - In most cases, you should not need to use this function. If you do - use it, be careful; the constant ``TIMER1`` is *not equal* to the - number 1; similarly, ``TIMER2`` is *not* the number 2, etc. Be - sure to refer to the timer device number by name. +.. cpp:function:: uint16 HardwareTimer::getCompare2() -.. _lang-hardwaretimer-modes: + Use ``getCompare(2, mode)`` instead. -Timer Modes -^^^^^^^^^^^ -.. doxygenenum:: TimerMode +.. cpp:function:: uint16 HardwareTimer::getCompare3() -.. _lang-hardwaretimer-timer-dev-num: + Use ``getCompare(3, mode)`` instead. -Timer Device Numbers -^^^^^^^^^^^^^^^^^^^^ +.. cpp:function:: uint16 HardwareTimer::getCompare4() -These provide a lower-level interface for interacting with timers. -They are mostly useful in context with the :ref:`getTimer() -` function. **Be careful** when using -these not to confuse e.g. ``TIMER1`` with the number 1; they are -different. + Use ``getCompare(4, mode)`` instead. -.. doxygenenum:: timer_dev_num +.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) -.. _lang-hardwaretimer-convenience: + Use ``setCompare(1, compare)`` instead. -.. _lang-hardwaretimer-gettimer: +.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) -Other Functions -^^^^^^^^^^^^^^^ -.. doxygenfunction:: getTimer + Use ``setCompare(2, compare)`` instead. -Examples -^^^^^^^^ +.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) -**LED blink**:: + Use ``setCompare(3, compare)`` instead. - #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles +.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) - void handler_led(void); + Use ``setCompare(4, compare)`` instead. - void setup() - { - // Set up the LED to blink - pinMode(BOARD_LED_PIN, OUTPUT); +.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() - // Setup Timer - Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer2.setPeriod(LED_RATE); // in microseconds - Timer2.setCompare1(1); // overflow might be small - Timer2.attachCompare1Interrupt(handler_led); - } + Use ``detachInterrupt(1)`` instead. - void loop() { - // Nothing! It's all in the interrupts - } +.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() - void handler_led(void) { - toggleLED(); - } + Use ``detachInterrupt(2)`` instead. -**Racing Counters**:: +.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() - void handler_count1(void); - void handler_count2(void); + Use ``detachInterrupt(3)`` instead. - int count1 = 0; - int count2 = 0; +.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() - void setup() - { - // Set up BUT for input - pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); + Use ``detachInterrupt(4)`` instead. - // Setup Counting Timers - Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer3.pause(); - Timer4.pause(); - Timer3.setCount(0); - Timer4.setCount(0); - Timer3.setOverflow(30000); - Timer4.setOverflow(30000); - Timer3.setCompare1(1000); // somewhere in the middle - Timer4.setCompare1(1000); - Timer3.attachCompare1Interrupt(handler1); - Timer4.attachCompare1Interrupt(handler2); - Timer3.resume(); - Timer4.resume(); - } +.. cpp:function:: void HardwareTimer::generateUpdate() - void loop() { - // Display the running counts - SerialUSB.print("Count 1: "); - SerialUSB.print(count1); - SerialUSB.print("\t\tCount 2: "); - SerialUSB.println(count2); - - // Run... while BUT is held, pause Count2 - for(int i = 0; i<1000; i++) { - if(digitalRead(BOARD_BUTTON_PIN)) { - Timer4.pause(); - } else { - Timer4.resume(); - } - delay(1); - } - } + Use ``refresh()`` instead. - void handler1(void) { - count1++; - } - void handler2(void) { - count2++; - } +In previous releases, to interact with a particular timers, you would +use one of the predefined ``HardwareTimer`` instances ``Timer1``, +``Timer2``, ``Timer3``, and ``Timer4``. These are still available for +now, but they are also deprecated, and will be removed in a future +release. As detailed in :ref:`lang-hardwaretimer-getting-started`, +you should define your own ``HardwareTimer`` variables. diff --git a/source/timers.rst b/source/timers.rst index cb30081..9163e69 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -45,6 +45,16 @@ event" interrupt is generated. You can configure the Maple to notify you when this takes place, by registering an interrupt handler, which is a function that will be called when the update event occurs. +By default, different compare values only change the relative offsets +between events on a single timer ("phase"). They don't control the +frequency with which they occur. However, a common trick is to +increment the compare value manually in the interrupt handler so that +the event will fire again after the increment period. There can be a +different increment value for each channel, so this trick allows +events to be programmed at 4 different rates on a single timer. Note +that function call overheads mean that the smallest increment rate is +at least a few microseconds. + Function Reference ------------------ -- cgit v1.2.3 From 5b7b0d3deb3bfeba30e80d2cb57f920324e77934 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 11 May 2011 13:45:27 -0400 Subject: 0.0.10 beta. --- source/conf.py | 2 +- source/index.rst | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/source/conf.py b/source/conf.py index baadccb..63f109f 100644 --- a/source/conf.py +++ b/source/conf.py @@ -59,7 +59,7 @@ copyright = u'2010, LeafLabs, LLC' # The short X.Y version. version = '0.0' # The full version, including alpha/beta/rc tags. -release = '0.0.10' +release = '0.0.10beta' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/source/index.rst b/source/index.rst index 8c7ac84..c01c34f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,10 +3,12 @@ LeafLabs Documentation Index ============================ -Welcome! This is the Maple documentation index. If you just bought a -Maple board, you probably want to head to the :ref:`quickstart -`. If you're having problems, check out the -:ref:`troubleshooting ` page. +Welcome! This is the Maple documentation index for version 0.0.10 +Beta. + +If you just bought a Maple board, you probably want to head to the +:ref:`quickstart `. If you're having problems, +check out the :ref:`troubleshooting ` page. Have fun! -- cgit v1.2.3 From 45fd9e188108c6a2c7db0dab1c78e397d7ebfbf9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 12 May 2011 04:36:38 -0400 Subject: making docs/source/index.rst not know its version again --- source/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/index.rst b/source/index.rst index c01c34f..f6b7f92 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,8 +3,7 @@ LeafLabs Documentation Index ============================ -Welcome! This is the Maple documentation index for version 0.0.10 -Beta. +Welcome! This is the Maple documentation index. If you just bought a Maple board, you probably want to head to the :ref:`quickstart `. If you're having problems, -- cgit v1.2.3 From afe0da1dce1b48b494f249ae40dbd020beea5684 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 12 May 2011 18:21:59 -0400 Subject: Fixing Maple and Maple RET6 Edition technical specifications. Takes into account the extra GPIOs afforded by disableDebugPorts() and the extra PWM channels on the RET6. --- source/hardware/maple-ret6.rst | 6 +++--- source/hardware/maple.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 06dcaff..45a59cd 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -15,15 +15,15 @@ Technical Specifications * Clock Speed: **72 MHz** * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V - * 39 Digital I/O Pins (:ref:`GPIO `) + * 44 Digital I/O Pins (:ref:`GPIO `) * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC `) - * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) + * 19 **PWM** pins at 16-bit resolution (:ref:`PWM `) * Dedicated **USB** port for programming and communications (:ref:`USB`) * External **JTAG** interface (:ref:`JTAG `) * **512KB Flash** and **64KB SRAM** * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) * Integrated **SPI** (:ref:`SPI `) - * Integrated **I2C** (:ref:`I2C `) + * Integrated **I2C** and **I2S** (:ref:`I2C `) * 12 Channels of Direct Memory Access (**DMA**) * 3 **USART** and 2 **UART** devices (:ref:`USART `) * Six 4-channel and two basic **timers** (:ref:`Timers `) diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index f4fcaf4..87878e9 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -15,7 +15,7 @@ Technical Specifications * Clock Speed: **72 MHz** * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V - * 39 Digital I/O Pins (:ref:`GPIO `) + * 44 Digital I/O Pins (:ref:`GPIO `) * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC `) * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) * Dedicated **USB** port for programming and communications (:ref:`USB `) -- cgit v1.2.3 From 8d1a128d717b98b8f0e6186e39b2b180c87a1a55 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 12 May 2011 18:42:50 -0400 Subject: More technical specs fixes. --- source/hardware/maple-ret6.rst | 28 +++++++++++++++++++++------- source/hardware/maple.rst | 32 +++++++++++++++++++++++++++----- 2 files changed, 48 insertions(+), 12 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 45a59cd..5fa43a8 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -13,22 +13,27 @@ Technical Specifications * MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor * Clock Speed: **72 MHz** - * Operating Voltage: 3.3V - * Input Voltage (recommended): 3V-12V + * **512KB Flash** and **64KB SRAM** * 44 Digital I/O Pins (:ref:`GPIO `) * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC `) + * Built-in, 2 channel **DAC** at 12 bit resolution + (:ref:`libmaple-dac`). * 19 **PWM** pins at 16-bit resolution (:ref:`PWM `) * Dedicated **USB** port for programming and communications (:ref:`USB`) * External **JTAG** interface (:ref:`JTAG `) - * **512KB Flash** and **64KB SRAM** - * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) + * 64 Channel nested vector interrupt handler (including + :ref:`external interrupt ` on GPIOs) * Integrated **SPI** (:ref:`SPI `) + * Integrated **SDIO** * Integrated **I2C** and **I2S** (:ref:`I2C `) - * 12 Channels of Direct Memory Access (**DMA**) + * 12 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) * 3 **USART** and 2 **UART** devices (:ref:`USART `) - * Six 4-channel and two basic **timers** (:ref:`Timers `) + * Two advanced control, four general purpose, two basic **timers** + (:ref:`timers`) * Supplies up to 800mA @ 3.3v * Support for low power and sleep modes (<500uA) + * Operating Voltage: 3.3V + * Input Voltage (recommended): 3V-12V * Dimensions are 2.05″x2.1″ .. _maple-ret6-powering: @@ -256,12 +261,21 @@ Errata This section lists known issues and warnings for the Maple RET6 Edition. -* **DAC, UART4, UART5 GPIOs unavailable**: Pins related to the digital +* **UART4, UART5 GPIOs unavailable**: Pins related to the digital to analog converter (DAC) and UARTs 4 and 5 are not broken out to headers. The RET6 Edition's hardware layout is identical to that of the Maple Rev 5, which wasn't designed for use with these STM32F103RET6-only peripherals. +* **DAC channel 2 on BOARD_LED_PIN**: The Maple Rev 5 connects PA5 to + the board's built-in LED; this is the same GPIO bit which is + connected to the DAC's channel 2 output. + +* **Reset and NJTRST tied together**: The MCU's reset pin is tied to + PB4, the NJTRST (JTAG reset) pin, which is pin 43. Thus, attempting + to use pin 43 as a GPIO will reset your board (and also prevents the + JTAG "reset halt" command from working properly). + Recommended Reading ------------------- diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 87878e9..4616ac7 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -13,22 +13,23 @@ Technical Specifications * MCU: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor * Clock Speed: **72 MHz** - * Operating Voltage: 3.3V - * Input Voltage (recommended): 3V-12V + * **128KB Flash** and **20KB SRAM** * 44 Digital I/O Pins (:ref:`GPIO `) * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC `) * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) * Dedicated **USB** port for programming and communications (:ref:`USB `) * External **JTAG** interface (:ref:`JTAG `) - * **128KB Flash** and **20KB SRAM** - * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) + * 64 Channel nested vector interrupt handler (including + :ref:`external interrupt ` on GPIOs) * Integrated **SPI** (:ref:`SPI `) * Integrated **I2C** (:ref:`I2C `) - * 7 Channels of Direct Memory Access (**DMA**) + * 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple.dma`) * 3 **USART** divices (:ref:`USART `) * Four 4-channel **timers** (:ref:`Timers `) * Supplies up to 800mA @ 3.3v * Support for low power and sleep modes (<500uA) + * Operating Voltage: 3.3V + * Input Voltage (recommended): 3V-12V * Dimensions are 2.05″x2.1″ .. _maple-identify-rev: @@ -307,6 +308,13 @@ Rev 5 from its silkscreen. This mistake was fixed in later manufacturing runs. +* **Reset and NJTRST tied together**: The MCU's reset pin is tied to + PB4, the NJTRST pin, which is pin 43. Thus, attempting to use pin + 43 as a GPIO will reset your board (and also prevents the JTAG + "reset halt") command from working properly. It's possible to cut + the trace, but doing so will damage your board, so we *do not + recommend it* unless you're very sure about what you're doing. + Rev 3 ^^^^^ @@ -352,6 +360,13 @@ Rev 3 * **PWM Marketing Mistake**: We originally sold the Maple advertising 22 channels of 16-bit hardware PWM; actually the Maple only has 15. +* **Reset and NJTRST tied together**: The MCU's reset pin is tied to + PB4, the NJTRST pin, which is pin 43. Thus, attempting to use pin + 43 as a GPIO will reset your board (and also prevents the JTAG + "reset halt") command from working properly. It's possible to cut + the trace, but doing so will damage your board, so we *do not + recommend it* unless you're very sure about what you're doing. + Rev 1 ^^^^^ @@ -386,6 +401,13 @@ Rev 1 * **PWM Marketing Mistake**: We originally sold the Maple advertising 22 channels of 16-bit hardware PWM; the correct number is 15. +* **Reset and NJTRST tied together**: The MCU's reset pin is tied to + PB4, the NJTRST pin, which is pin 43. Thus, attempting to use pin + 43 as a GPIO will reset your board (and also prevents the JTAG + "reset halt") command from working properly. It's possible to cut + the trace, but doing so will damage your board, so we *do not + recommend it* unless you're very sure about what you're doing. + Recommended Reading ------------------- -- cgit v1.2.3 From b4de7c0594f7d1ea0dcfe816e7e458bbfdc5f879 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 12 May 2011 19:16:04 -0400 Subject: Docs: Adding 0.0.10beta download links. --- source/maple-ide-install.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index beba54d..98a5fcc 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -17,8 +17,8 @@ us directly`_\ ! Download -------- -The current release of the Maple IDE is version 0.0.9. Choose the -correct version for your operating system: +Maple IDE 0.0.10 Beta is now available. Choose the correct version +for your operating system: .. list-table:: :widths: 15 30 50 @@ -29,15 +29,13 @@ correct version for your operating system: - IDE Package * - Windows - Tested on 32bit Windows XP - - `maple-ide-0.0.9-windowsxp32.zip `_ (about 75mb) + - `maple-ide-0.0.10beta-windowsxp32.zip `_ (about 75mb) * - Linux - - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) - - `maple-ide-0.0.9-linux32.tgz `_ (about 30mb) - - `maple-ide-0.0.9-linux64.tgz `_ (about 30mb) + - Tested on Ubuntu 10.04 (32bit) + - `maple-ide-0.0.10beta-linux32.tgz `_ (about 30mb) * - Mac OSX - - Tested on Snow Leopard 10.6 (64bit and 32bit) - - `maple-ide-0.0.9-macosx-10_6.dmg `_ (about 40mb) + - Tested on Snow Leopard (10.6) + - `maple-ide-0.0.10beta-macosx-10_6.dmg `_ (about 40mb) The package bundles together a compiler, an upload utility, a software library, and a simple GUI text editor. All this software is `free and -- cgit v1.2.3 From 42bbfd34070557848410bf2289a01f0d06e4f19f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 17:27:47 -0400 Subject: Docs: Fixing power supply marketing mistake. --- source/hardware/maple-ret6.rst | 16 ++++++++++++---- source/hardware/maple.rst | 32 +++++++++++++++++++++++--------- 2 files changed, 35 insertions(+), 13 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 5fa43a8..e9eebd0 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -15,22 +15,26 @@ Technical Specifications * Clock Speed: **72 MHz** * **512KB Flash** and **64KB SRAM** * 44 Digital I/O Pins (:ref:`GPIO `) - * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC `) + * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC + `) * Built-in, 2 channel **DAC** at 12 bit resolution (:ref:`libmaple-dac`). * 19 **PWM** pins at 16-bit resolution (:ref:`PWM `) - * Dedicated **USB** port for programming and communications (:ref:`USB`) + * Dedicated **USB** port for programming and communications + (:ref:`USB`) * External **JTAG** interface (:ref:`JTAG `) * 64 Channel nested vector interrupt handler (including :ref:`external interrupt ` on GPIOs) * Integrated **SPI** (:ref:`SPI `) * Integrated **SDIO** * Integrated **I2C** and **I2S** (:ref:`I2C `) - * 12 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) + * 12 Channels of Direct Memory Access (**DMA**) + (:ref:`libmaple-dma`) * 3 **USART** and 2 **UART** devices (:ref:`USART `) * Two advanced control, four general purpose, two basic **timers** (:ref:`timers`) - * Supplies up to 800mA @ 3.3v + * Supplies up to 500mA @ 3.3v (with separate 250 mA digital and + analog regulators) * Support for low power and sleep modes (<500uA) * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V @@ -261,6 +265,10 @@ Errata This section lists known issues and warnings for the Maple RET6 Edition. +* **Power Supply Marketing Mistake**: We originally sold the Maple + advertising that it was capable of supplying up to 800 mA; the + correct value is 500 mA. + * **UART4, UART5 GPIOs unavailable**: Pins related to the digital to analog converter (DAC) and UARTs 4 and 5 are not broken out to headers. The RET6 Edition's hardware layout is identical to that of diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 4616ac7..b3124e0 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -15,18 +15,22 @@ Technical Specifications * Clock Speed: **72 MHz** * **128KB Flash** and **20KB SRAM** * 44 Digital I/O Pins (:ref:`GPIO `) - * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC `) + * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC + `) * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) - * Dedicated **USB** port for programming and communications (:ref:`USB `) + * Dedicated **USB** port for programming and communications + (:ref:`USB `) * External **JTAG** interface (:ref:`JTAG `) * 64 Channel nested vector interrupt handler (including :ref:`external interrupt ` on GPIOs) * Integrated **SPI** (:ref:`SPI `) * Integrated **I2C** (:ref:`I2C `) - * 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple.dma`) + * 7 Channels of Direct Memory Access (**DMA**) + (:ref:`libmaple.dma`) * 3 **USART** divices (:ref:`USART `) * Four 4-channel **timers** (:ref:`Timers `) - * Supplies up to 800mA @ 3.3v + * Supplies up to 500mA @ 3.3v (with separate 250 mA digital and + analog regulators) * Support for low power and sleep modes (<500uA) * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V @@ -297,11 +301,21 @@ permanently. Errata ------ -This section lists known issues and warnings for each revision of the -Maple board. +General +^^^^^^^ + +* **Power Supply Marketing Mistake**: We originally sold the Maple + advertising that it was capable of supplying up to 800 mA; the + correct value is 500 mA. + +By Rev +^^^^^^ + +The following subsections lists known issues and warnings for each +revision of the Maple board. Rev 5 -^^^^^ +~~~~~ * **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on Rev 5s manufactured during Fall 2010, the corresponding "AIN" is missing @@ -316,7 +330,7 @@ Rev 5 recommend it* unless you're very sure about what you're doing. Rev 3 -^^^^^ +~~~~~ * **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the corresponding "AIN" is missing from the Rev 3 silkscreen. @@ -368,7 +382,7 @@ Rev 3 recommend it* unless you're very sure about what you're doing. Rev 1 -^^^^^ +~~~~~ * **ADC noise**: generally very high, in particular when the USB port is being used for communications (including keep-alive pings when -- cgit v1.2.3 From 0cfeed3fe453118be00ec6965a3de6dda7853852 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 17:40:04 -0400 Subject: Docs: Adding "standby" to low-power marketing. --- source/hardware/maple-ret6.rst | 2 +- source/hardware/maple.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index e9eebd0..1f3a656 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -35,7 +35,7 @@ Technical Specifications (:ref:`timers`) * Supplies up to 500mA @ 3.3v (with separate 250 mA digital and analog regulators) - * Support for low power and sleep modes (<500uA) + * Support for low power, sleep, and standby modes (<500uA) * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V * Dimensions are 2.05″x2.1″ diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index b3124e0..2ae1c30 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -31,7 +31,7 @@ Technical Specifications * Four 4-channel **timers** (:ref:`Timers `) * Supplies up to 500mA @ 3.3v (with separate 250 mA digital and analog regulators) - * Support for low power and sleep modes (<500uA) + * Support for low power, sleep, and standby modes (<500uA) * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V * Dimensions are 2.05″x2.1″ -- cgit v1.2.3 From 3bf30c706c1a5a266dbe55af0d206385887882fa Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 17:44:46 -0400 Subject: Docs: Removing note about cutting the Maple's NJTRST<->NRST trace. Worried about the possibility of an attractive nuisance. --- source/hardware/maple-ret6.rst | 8 ++++---- source/hardware/maple.rst | 10 ++++------ 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 1f3a656..d6a7c0e 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -279,10 +279,10 @@ This section lists known issues and warnings for the Maple RET6 Edition. the board's built-in LED; this is the same GPIO bit which is connected to the DAC's channel 2 output. -* **Reset and NJTRST tied together**: The MCU's reset pin is tied to - PB4, the NJTRST (JTAG reset) pin, which is pin 43. Thus, attempting - to use pin 43 as a GPIO will reset your board (and also prevents the - JTAG "reset halt" command from working properly). +* **Reset and NJTRST tied together**: The MCU's reset pin is connected + to PB4, the NJTRST (JTAG reset) pin, which is pin 43. Thus, + attempting to use pin 43 as a GPIO will reset your board (and also + prevents the JTAG "reset halt" command from working properly). Recommended Reading ------------------- diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 2ae1c30..d0434ab 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -322,12 +322,10 @@ Rev 5 from its silkscreen. This mistake was fixed in later manufacturing runs. -* **Reset and NJTRST tied together**: The MCU's reset pin is tied to - PB4, the NJTRST pin, which is pin 43. Thus, attempting to use pin - 43 as a GPIO will reset your board (and also prevents the JTAG - "reset halt") command from working properly. It's possible to cut - the trace, but doing so will damage your board, so we *do not - recommend it* unless you're very sure about what you're doing. +* **Reset and NJTRST tied together**: The MCU's reset pin is connected + to PB4, the NJTRST pin, which is pin 43. Thus, attempting to use + pin 43 as a GPIO will reset your board (and also prevents the JTAG + "reset halt") command from working properly. Rev 3 ~~~~~ -- cgit v1.2.3 From f6169a9aa9036ae0baed9901ce21a49fe47b24a3 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 18:14:26 -0400 Subject: Docs: More complete board-specific values list. --- source/lang/api/board-values.rst | 41 +++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst index 05e3837..5fbf20f 100644 --- a/source/lang/api/board-values.rst +++ b/source/lang/api/board-values.rst @@ -1,10 +1,12 @@ .. _lang-board-values: -Board-Specific Constants -======================== +Board-Specific Values +===================== There are a number of board-specific values: constants or variables -which are different depending on which LeafLabs board you have. +which are different depending on which LeafLabs board you have. The +exact values for each board are given in your :ref:`board's hardware +documentation `. This page lists and documents the board-specific values. You should use these when appropriate in your own programs. This will help make @@ -21,14 +23,21 @@ Documentation `. Constants --------- +.. TODO [systick.rst] Add a link to systick.rst instead of systick.h +.. below, when systick.rst exists. + +- ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on + your board. + - ``CLOCK_SPEED_MHZ``: Clock speed of your board, in megahertz (MHz). This is the same as ``CYCLES_PER_MICROSECOND``. - ``CLOCK_SPEED_HZ``: Clock speed of your board, in hertz (Hz). This - is the same as ``CLOCK_SPEED_MHZ * 1000000``. + is the same as ``CLOCK_SPEED_MHZ`` × 1,000,000. -- ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on - your board. +- ``SYSTICK_RELOAD_VAL``: Value used when reloading the :ref:`SysTick + ` timer's counter. For :ref:`lang-millis` to work + properly, this must be ``CYCLES_PER_MICROSECOND`` × 1,000 - 1. .. _lang-board-values-but: @@ -70,7 +79,7 @@ Constants .. _lang-board-values-usart: -- USART (serial port) related constants: +- :ref:`USART ` (serial port) related constants: * ``BOARD_USART1_TX_PIN``, ``BOARD_USART2_TX_PIN``, ``BOARD_USART3_TX_PIN``: TX pins for the 3 USARTS. @@ -87,6 +96,24 @@ Constants * ``BOARD_NR_USARTS``: Number of serial ports on the board. This number includes UARTs 4 and 5 if they are available. +- :ref:`SPI ` related constants: + + * ``BOARD_SPI1_NSS_PIN``, ``BOARD_SPI1_MOSI_PIN``, + ``BOARD_SPI1_MISO_PIN``, ``BOARD_SPI1_SCK_PIN``: SPI1 + peripheral's NSS, MOSI, MISO, and SCK pins, respectively. + + * ``BOARD_SPI2_NSS_PIN``, ``BOARD_SPI2_MOSI_PIN``, + ``BOARD_SPI2_MISO_PIN``, ``BOARD_SPI2_SCK_PIN``: SPI2 + peripheral's NSS, MOSI, MISO, and SCK pins, respectively. + + * ``BOARD_SPI3_NSS_PIN``, ``BOARD_SPI3_MOSI_PIN``, + ``BOARD_SPI3_MISO_PIN``, ``BOARD_SPI3_SCK_PIN``: SPI3 + peripheral's NSS, MOSI, MISO, and SCK pins, respectively + (available on high-density devices like Maple Native and Maple + RET6 edition only). + + * ``BOARD_NR_SPI``: Number of SPI peripherals on the board. + .. _lang-board-values-debug: - Debug (JTAG, SW-Debug) related constants: ``BOARD_JTMS_SWDIO_PIN``, -- cgit v1.2.3 From 9cca28742e8669e69df04f4deb6f6f4bd11b38a1 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 18:33:08 -0400 Subject: Docs: board-specific values for Maple and Maple RET6 Edition. --- source/hardware/maple-ret6.rst | 60 +++++++++++++++++++++++++++++++++++------- source/hardware/maple.rst | 43 +++++++++++++++++++++++++----- 2 files changed, 88 insertions(+), 15 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index d6a7c0e..fa7e50e 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -75,7 +75,7 @@ GPIO Information The RET6 Edition features 38 ready-to-use general purpose input/output (GPIO) pins for digital input/output, numbered ``D0`` through ``D37``. These numbers correspond to the numeric values next to each header on -the Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are +the Maple silkscreen. More GPIOs (numbered ``D39``\ --``D43``) are available through use in combination with the :ref:`lang-disabledebugports` function; see the :ref:`board-specific debug pin constants ` for more information. @@ -207,11 +207,10 @@ The following table shows which pins connect to which :ref:`EXTI lines USART Pin Map ^^^^^^^^^^^^^ -.. FIXME [0.0.10] UART4 and UART5 information - -The Maple RET6 Edition has three serial ports (also known as a UARTs -or USARTs): ``Serial1``, ``Serial2``, and ``Serial3``. They -communicate using the pins summarized in the following table: +The Maple RET6 Edition has three serial ports whose pins are broken +out to headers (also known as a UARTs or USARTs): ``Serial1``, +``Serial2``, and ``Serial3``. They communicate using the pins +summarized in the following table: .. csv-table:: :header: Serial Port, TX, RX, CK, CTS, RTS @@ -221,12 +220,53 @@ communicate using the pins summarized in the following table: ``Serial2`` | 1 | 0 | 10 | 2 | 3 ``Serial3`` | 29 | 30 | 31 | 32 | 33 +Unfortunately, :ref:`UART4 and UART5 aren't completely available +`. + Board-Specific Values --------------------- -.. TODO [0.0.10] - -Stub. +This section lists the Maple RET6 Edition's :ref:`board-specific +values `. + +- ``CYCLES_PER_MICROSECOND``: 72 +- ``BOARD_BUTTON_PIN``: 38 +- ``BOARD_LED_PIN``: 13 +- ``BOARD_NR_GPIO_PINS``: 44 +- ``BOARD_NR_PWM_PINS``: 16 +- ``boardPWMPins``: 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 25, 27, 28 +- ``BOARD_NR_ADC_PINS``: 15 +- ``boardADCPins``: 0, 1, 2, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 +- ``BOARD_NR_USED_PINS``: 7 +- ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN``, + ``BOARD_JTMS_SWDIO_PIN``, ``BOARD_JTCK_SWCLK_PIN``, + ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``, ``BOARD_NJTRST_PIN`` +- ``BOARD_NR_USARTS``: 3 (unfortunately, due to the Maple Rev 5 + design, UARTs 4 and 5 have pins which are not broken out) +- ``BOARD_USART1_TX_PIN``: 7 +- ``BOARD_USART1_RX_PIN``: 8 +- ``BOARD_USART2_TX_PIN``: 1 +- ``BOARD_USART2_RX_PIN``: 0 +- ``BOARD_USART3_TX_PIN``: 29 +- ``BOARD_USART3_RX_PIN``: 30 +- ``BOARD_NR_SPI``: 3 +- ``BOARD_SPI1_NSS_PIN``: 10 +- ``BOARD_SPI1_MOSI_PIN``: 11 +- ``BOARD_SPI1_MISO_PIN``: 12 +- ``BOARD_SPI1_SCK_PIN``: 13 +- ``BOARD_SPI2_NSS_PIN``: 31 +- ``BOARD_SPI2_MOSI_PIN``: 34 +- ``BOARD_SPI2_MISO_PIN``: 33 +- ``BOARD_SPI2_SCK_PIN``: 32 +- ``BOARD_SPI3_NSS_PIN``: 41 +- ``BOARD_SPI3_MOSI_PIN``: 4 +- ``BOARD_SPI3_MISO_PIN``: 43 +- ``BOARD_SPI3_SCK_PIN``: 42 +- ``BOARD_JTMS_SWDIO_PIN``: 39 +- ``BOARD_JTCK_SWCLK_PIN``: 40 +- ``BOARD_JTDI_PIN``: 41 +- ``BOARD_JTDO_PIN``: 42 +- ``BOARD_NJTRST_PIN``: 43 Hardware Design Files --------------------- @@ -269,6 +309,8 @@ This section lists known issues and warnings for the Maple RET6 Edition. advertising that it was capable of supplying up to 800 mA; the correct value is 500 mA. +.. _maple-ret6-uart-errata: + * **UART4, UART5 GPIOs unavailable**: Pins related to the digital to analog converter (DAC) and UARTs 4 and 5 are not broken out to headers. The RET6 Edition's hardware layout is identical to that of diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index d0434ab..4aed91d 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -118,7 +118,7 @@ GPIO Information The Maple features 38 ready-to-use general purpose input/output (GPIO) pins for digital input/output, numbered ``D0`` through ``D37``. These numbers correspond to the numeric values next to each header on the -Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are +Maple silkscreen. More GPIOs (numbered ``D39``\ --``D43``) are available through use in combination with the :ref:`lang-disabledebugports` function; see the :ref:`board-specific debug pin constants ` for more information. @@ -246,8 +246,6 @@ The following table shows which pins connect to which :ref:`EXTI lines USART Pin Map ^^^^^^^^^^^^^ -.. FIXME [0.0.10] UART4, UART5 - The Maple has three serial ports (also known as a UARTs or USARTs): ``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the pins summarized in the following table: @@ -263,9 +261,42 @@ pins summarized in the following table: Board-Specific Values --------------------- -.. TODO [0.0.10] - -Stub. +This section lists the Maple's :ref:`board-specific values +`. + +- ``CYCLES_PER_MICROSECOND``: 72 +- ``BOARD_BUTTON_PIN``: 38 +- ``BOARD_LED_PIN``: 13 +- ``BOARD_NR_GPIO_PINS``: 44 +- ``BOARD_NR_PWM_PINS``: 16 +- ``boardPWMPins``: 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 25, 27, 28 +- ``BOARD_NR_ADC_PINS``: 15 +- ``boardADCPins``: 0, 1, 2, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 +- ``BOARD_NR_USED_PINS``: 7 +- ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN``, + ``BOARD_JTMS_SWDIO_PIN``, ``BOARD_JTCK_SWCLK_PIN``, + ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``, ``BOARD_NJTRST_PIN`` +- ``BOARD_NR_USARTS``: 3 +- ``BOARD_USART1_TX_PIN``: 7 +- ``BOARD_USART1_RX_PIN``: 8 +- ``BOARD_USART2_TX_PIN``: 1 +- ``BOARD_USART2_RX_PIN``: 0 +- ``BOARD_USART3_TX_PIN``: 29 +- ``BOARD_USART3_RX_PIN``: 30 +- ``BOARD_NR_SPI``: 2 +- ``BOARD_SPI1_NSS_PIN``: 10 +- ``BOARD_SPI1_MOSI_PIN``: 11 +- ``BOARD_SPI1_MISO_PIN``: 12 +- ``BOARD_SPI1_SCK_PIN``: 13 +- ``BOARD_SPI2_NSS_PIN``: 31 +- ``BOARD_SPI2_MOSI_PIN``: 34 +- ``BOARD_SPI2_MISO_PIN``: 33 +- ``BOARD_SPI2_SCK_PIN``: 32 +- ``BOARD_JTMS_SWDIO_PIN``: 39 +- ``BOARD_JTCK_SWCLK_PIN``: 40 +- ``BOARD_JTDI_PIN``: 41 +- ``BOARD_JTDO_PIN``: 42 +- ``BOARD_NJTRST_PIN``: 43 Hardware Design Files --------------------- -- cgit v1.2.3 From b93c724a9e811c6716cd6e0b34a233f4b4d35502 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 18:53:07 -0400 Subject: Docs: correcting "Github" -> "GitHub". --- source/hardware/maple-ret6.rst | 2 +- source/hardware/maple.rst | 2 +- source/libmaple.rst | 10 +++++----- source/libmaple/contributing.rst | 8 ++++---- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index fa7e50e..2f23bc4 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -279,7 +279,7 @@ subdirectory of the Maple repository. A schematic for a JTAG adapter suitable for use with Maple is available in the ``jtagadapter`` directory. -From the Github repository main page, you can download the entire +From the GitHub repository main page, you can download the entire repository by clicking the "Download" button. If you are familiar with `git `_, you can also clone the repository at the command line with :: diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 4aed91d..e460e00 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -308,7 +308,7 @@ design files for Rev 1, Rev 3, and Rev 5 are respectively in the schematic for a JTAG adapter suitable for use with Maple is available in the ``jtagadapter`` directory. -From the Github repository main page, you can download the entire +From the GitHub repository main page, you can download the entire repository by clicking the "Download" button. If you are familiar with `git `_, you can also clone the repository at the command line with :: diff --git a/source/libmaple.rst b/source/libmaple.rst index 375e821..d9f30be 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -5,12 +5,12 @@ ``libmaple`` ============ -LeafLabs' libmaple (`source code on Github +LeafLabs' libmaple (`source code on GitHub `_) is the library we have -developed for the `STM32 `_ line of ARM Cortex M3 -microcontrollers. Its high-level interfaces are :ref:`largely -compatible ` with the AVR libraries written for -the `Arduino `_ and `Wiring +developed for the `STM32 `_ line of ARM +Cortex M3 microcontrollers. Its high-level interfaces are +:ref:`largely compatible ` with the AVR +libraries written for the `Arduino `_ and `Wiring `_ development boards. libmaple is split into two pieces: a lower level layer written in pure diff --git a/source/libmaple/contributing.rst b/source/libmaple/contributing.rst index 724605b..ded25f8 100644 --- a/source/libmaple/contributing.rst +++ b/source/libmaple/contributing.rst @@ -60,14 +60,14 @@ source tree when the time comes. The steps to submit a pull request are as follows: -1. If you don't already have one, get a `Github account +1. If you don't already have one, get a `GitHub account `_ (free). 2. Fork libmaple, then clone your fork to the computer you code on. - Github provides detailed instructions on `forking and cloning a + GitHub provides detailed instructions on `forking and cloning a repository `_. -3. Push your commits to your Github libmaple fork (see instructions +3. Push your commits to your GitHub libmaple fork (see instructions linked in Step 2 for a step-by-step walkthrough on how to do this). 4. `Submit a pull request `_ to @@ -78,7 +78,7 @@ The steps to submit a pull request are as follows: Submitting Via Email -------------------- -If you're unfamiliar with Git or would prefer not to use Github, you +If you're unfamiliar with Git or would prefer not to use GitHub, you can always send us a patch via email at info@leaflabs.com. We'd love it if you used the `Linux kernel patch format `_, but please at least include -- cgit v1.2.3 From 8482c195902d9c98085b8dc79d71db4b17c37964 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 20:06:41 -0400 Subject: Docs: Updating Servo docs. --- Doxyfile | 3 +- source/libs/servo.rst | 110 ++++++++++---------------------------------------- 2 files changed, 24 insertions(+), 89 deletions(-) diff --git a/Doxyfile b/Doxyfile index 5fbb079..a441c4f 100644 --- a/Doxyfile +++ b/Doxyfile @@ -591,7 +591,8 @@ WARN_LOGFILE = # with spaces. INPUT = ../libmaple/ \ - ../wirish/ + ../wirish/ \ + ../libraries/ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/source/libs/servo.rst b/source/libs/servo.rst index 891f151..3b96467 100644 --- a/source/libs/servo.rst +++ b/source/libs/servo.rst @@ -5,8 +5,6 @@ Servo ===== -.. FIXME [0.0.10] this is out of date - This documents the Servo library for controlling RC servomotors. It is implemented as a thin layer over the built-in :ref:`timer peripherals `. @@ -31,83 +29,15 @@ servomotor attached to pin 9, you could write :: servo.attach(9); -.. cpp:class:: Servo - - Class for controlling RC servomotors via :ref:`timers `. +.. TODO [0.0.10] figure out the cpp domain well enough to replace +.. references here .. _libs-servo-attach: -.. cpp:function:: bool Servo::attach(uint8 pin, uint16 min, uint16 max) - - Attach this Servo object to the given ``pin``. The pin must be - capable of PWM. You can check this by seeing if "PWM" is written - next to its number on the Maple silkscreen, or by consulting the - :ref:`pwmWrite() ` documentation. - - Sets this pin's :ref:`mode ` to :ref:`PWM - `, and returns true if successful. - Does nothing and returns false if the pin doesn't support PWM. - - Parameter ``min`` is the pulse width corresponding to 0 degrees; - ``max`` is the pulse width corresponding to 180 degrees (both are - in microseconds). - -.. cpp:function:: bool Servo::attach(uint8 pin) - - Equivalent to :ref:`attach(pin, 544, 2400) `. - .. _libs-servo-attached: -.. cpp:function:: int Servo::attached() const - - If currently attached (via :ref:`attach() `) to - a pin, returns that pin's number. Returns ``NOT_ATTACHED`` - otherwise. - -.. cpp:function:: bool Servo::detach() - - If this Servo object is currently attached to pin, stops driving - the servo by setting a zero pulse width (this is accomplished by - setting the associated :ref:`channel mode - ` to ``TIMER_DISABLED``). - - Subsequently, calling :ref:`attached() ` will - return ``NOT_ATTACHED``. - -.. cpp:function:: void Servo::write(unsigned int value) - - If ``value`` is less than ``SERVO_MAX_WRITE_ANGLE`` (which, for - Arduino compatibility, is 200), it's interpreted as an angle in - degrees. Otherwise, it's treated as a pulse width in microseconds. - - Drives the servo to target the given angle, based on a linear - interpolation of the ``min`` and ``max`` pulse widths determined - when :ref:`attach() ` was called. - - Be aware that some (especially lower-cost) servos have fairly - non-linear maps between pulse width and target angle. Make sure to - test your motor before relying on this method. - -.. cpp:function:: void Servo::writeMicroseconds(uint16 pulseWidth) - - Drives the servo using a ``pulseWidth``-microsecond pulse. - - If ``pulseWidth`` is outside of the [``min``, ``max``\ ] pulse - width range set during :ref:`attach() `, it will - be clamped to lie in this range. - -.. cpp:function:: int Servo::read() const - - Returns the servo's target angle, in degrees. This will be clamped - to lie between 0 (when the pulse width is at most ``min``) and 180 - (when the pulse width is at least ``max``). - -.. cpp:function:: uint16 Servo::readMicroseconds() const - - Returns the pulse width of the wave currently driving the servo, in - microseconds. This will be clamped to lie in the [``min``, - ``max``\ ] pulse width range set during :ref:`attach() - `. +.. doxygenclass:: Servo + :members: Arduino Compatibility --------------------- @@ -126,9 +56,10 @@ implementation uses :ref:`timers ` to drive the PWM directly. Consequently, **the Maple implementation only allows Servo instances to** :ref:`attach ` **to pins that support PWM**. -To determine if a pin supports PWM (15 Maple pins do), you can either -check if "PWM" appears next to its number on the Maple silkscreen, or -consult the :ref:`pwmWrite() ` documentation. +To determine if a pin supports PWM, you can either check if "PWM" +appears next to its number on your board's silkscreen, or look for it +in the list of :ref:`boardPWMPins ` in +your board's :ref:`hardware documentation `. RC Servos expect a pulse approximately every 20ms. In the Maple implementation, :ref:`periods ` are set @@ -141,17 +72,20 @@ which share a timer, in order to keep as many timers free for other purposes as possible. Consult your board's :ref:`Timer Pin Map ` to match up pins and timer channels. -Another difference: although it is not publicly documented to do so, -the Arduino implementation of `attach() -`_ returns the timer -channel associated with the newly-attached pin, or 0 on failure (as of -Arduino 0021). The Maple implementation returns :ref:`true -` on success, and :ref:`false -` on failure (and this is its documented -behavior). - -We currently provide a soft (bit-banged) implementation of the -:ref:`Wire ` I2C library. +And here's some fine print: + +- Although it is not publicly documented to do so, the Arduino + implementation of `attach() + `_ returns the timer + channel associated with the newly-attached pin, or 0 on failure (as + of Arduino 0021). The Maple implementation returns :ref:`true + ` on success, and :ref:`false + ` on failure (and this is its documented + behavior). + +- In another bit of undocumented behavior, the Arduino implementation + of write() also treats its argument as an angle or a pulse width + depending on its value. This is a bad idea, and we don't do it. .. rubric:: Footnotes -- cgit v1.2.3 From 3fe24fd92c0462c9bceee0c36dc4d9d9b7723142 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 20:06:52 -0400 Subject: Docs: Various improvements. --- source/hardware/maple.rst | 87 ++++++++++++++++++++++------------------- source/i2c.rst | 2 +- source/index.rst | 1 + source/libmaple/api/systick.rst | 5 +-- source/systick.rst | 13 ++++++ source/timers.rst | 27 ++++++------- 6 files changed, 77 insertions(+), 58 deletions(-) create mode 100644 source/systick.rst diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index e460e00..c2dc895 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -136,49 +136,54 @@ the header is connected to on the microcontroller. The "5V?" column documents whether or not the pin is 5 volt tolerant. .. csv-table:: - :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" - - "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" - "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" - "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" - "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" - "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" - "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" - "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" - "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" - "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" - "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" - "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" - "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" - "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" - "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" - "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" - "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" - "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" - "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" - "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" - "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" - "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" - "D21", "PC13", "-", "-", "-", "-", "-", "No" - "D22", "PC14", "-", "-", "-", "-", "-", "No" - "D23", "PC15", "-", "-", "-", "-", "-", "No" - "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" - "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" - "D26", "PC10", "-", "-", "-", "-", "-", "Yes" - "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" - "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" - "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" - "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" - "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes" - "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" - "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" - "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" - "D35", "PC6", "-", "-", "-", "-", "-", "Yes" - "D36", "PC7", "-", "-", "-", "-", "-", "Yes" - "D37", "PC8", "-", "-", "-", "-", "-", "Yes" + :header: Pin, STM32, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5v? + + D0, PA3, ADC3, TIM2_CH4, -, USART2_RX, -, No + D1, PA2, ADC2, TIM2_CH3, -, USART2_TX, -, No + D2, PA0, ADC0, TIM2_CH1_ETR, -, USART2_CTS, -, No + D3, PA1, ADC1, TIM2_CH2, -, USART2_RTS, -, No + D4, PB5, -, -, ISC1_SMBA, -, -, No + D5, PB6, -, TIM4_CH1, I2C1_SCL, -, -, Yes + D6, PA8, -, TIM1_CH1, -, USART1_CK, -, Yes + D7, PA9, -, TIM1_CH2, -, USART1_TX, -, Yes + D8, PA10, -, TIM1_CH3, -, USART1_RX, -, Yes + D9, PB7, -, TIM4_CH2, I2C1_SDA, -, -, Yes + D10, PA4, ADC4, -, -, USART2_CK, SPI1_NSS, No + D11, PA7, ADC7, TIM3_CH2, -, -, SPI1_MOSI, No + D12, PA6, ADC6, TIM3_CH1, -, -, SPI1_MISO, No + D13, PA5, ADC5, -, -, -, SPI1_SCK, No + D14, PB8, -, TIM4_CH3, -, -, -, Yes + D15, PC0, ADC10, -, -, -, -, No + D16, PC1, ADC11, -, -, -, -, No + D17, PC2, ADC12, -, -, -, -, No + D18, PC3, ADC13, -, -, -, -, No + D19, PC4, ADC14, -, -, -, -, No + D20, PC5, ADC15, -, -, -, -, No + D21, PC13, -, -, -, -, -, No + D22, PC14, -, -, -, -, -, No + D23, PC15, -, -, -, -, -, No + D24, PB9, -, TIM4_CH4, -, -, -, Yes + D25, PD2, -, TIM3_ETR, -, -, -, Yes + D26, PC10, -, -, -, -, -, Yes + D27, PB0, ADC8, TIM3_CH3, -, -, -, No + D28, PB1, ADC9, TIM3_CH4, -, -, -, No + D29, PB10, -, -, I2C2_SCL, USART3_TX, -, Yes + D30, PB11, -, -, I2C2_SDA, USART3_RX, -, Yes + D31, PB12, -, TIM1_BKIN, I2C2_SMBA, USART3_CK, SPI2_NSS, Yes + D32, PB13, -, TIM1_CH1N, -, USART3_CTS, SPI2_SCK, Yes + D33, PB14, -, TIM1_CH2N, -, USART3_RTS, SPI2_MISO, Yes + D34, PB15, -, TIM1_CH3N, -, -, SPI2_MOSI, Yes + D35, PC6, -, -, -, -, -, Yes + D36, PC7, -, -, -, -, -, Yes + D37, PC8, -, -, -, -, -, Yes .. TODO [0.0.10] JTAG pins +.. The following pins are used for :ref:`jtag` debugging by default, but +.. can be used as ordinary GPIOs through the use of the +.. :ref:`lang-disabledebugports` function. (Though see :ref:`this +.. erratum `). + Timer Pin Map ^^^^^^^^^^^^^ @@ -353,6 +358,8 @@ Rev 5 from its silkscreen. This mistake was fixed in later manufacturing runs. +.. _maple-reset-njtrst: + * **Reset and NJTRST tied together**: The MCU's reset pin is connected to PB4, the NJTRST pin, which is pin 43. Thus, attempting to use pin 43 as a GPIO will reset your board (and also prevents the JTAG diff --git a/source/i2c.rst b/source/i2c.rst index e3d68c0..31976ac 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -25,7 +25,7 @@ interrupt handlers) at the same time. Hardware/Circuit Design ----------------------- -.. FIXME [0.0.10 add links to board-specific values] +.. FIXME [0.1.0] Link to board-specific values (BOARD_I2C1_SDA_PIN, etc.) Maple boards have two |i2c| ports. Maples reliably communicate with up to a 400kHz clock speed; this doesn't translate into a 400kbps data diff --git a/source/index.rst b/source/index.rst index f6b7f92..ce3985f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -54,6 +54,7 @@ Have fun! pwm spi timers + systick usb usart diff --git a/source/libmaple/api/systick.rst b/source/libmaple/api/systick.rst index a02b8e4..a8c0971 100644 --- a/source/libmaple/api/systick.rst +++ b/source/libmaple/api/systick.rst @@ -1,14 +1,13 @@ .. highlight:: c - -.. _libmaple-systick: - .. FIXME [0.0.10] move these to the right places: .. _libmaple-systick_disable: .. _libmaple-systick_resume: +.. _libmaple-systick: + ``systick.h`` ============= diff --git a/source/systick.rst b/source/systick.rst new file mode 100644 index 0000000..6f20133 --- /dev/null +++ b/source/systick.rst @@ -0,0 +1,13 @@ +SysTick +======= + +.. TODO Recommended reading and more content. + +The SysTick peripheral provides a timer which :ref:`libmaple` uses to +keep track of the board's uptime. + +Library Documentation +--------------------- + +See :ref:`libmaple-systick` for more information on library support +for interfacing with the SysTick peripheral. diff --git a/source/timers.rst b/source/timers.rst index 9163e69..403193f 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -5,8 +5,6 @@ Timers ====== -.. FIXME [0.0.10] links to systick.h in a few places on this page - There are four general purpose timers in the Maple microcontroller that can be configured to generate periodic or delayed events with minimal work done by the microcontroller. For example, the :ref:`PWM @@ -55,10 +53,11 @@ events to be programmed at 4 different rates on a single timer. Note that function call overheads mean that the smallest increment rate is at least a few microseconds. -Function Reference ------------------- +Library Documentation +--------------------- -* :ref:`HardwareTimer ` +See the :ref:`HardwareTimer ` reference for more +information on controlling the built-in timers. Caveats ------- @@ -109,12 +108,12 @@ you put your Maple into :ref:`perpetual bootloader mode to it (or somehow causing your program to re-enable serial over USB using :ref:`SerialUSB.begin() `). -The SysTick peripheral another way to perform periodic or delayed -events. Its separate timer does not conflict with any other -peripherals, but the associated 1 kHz interrupt can jitter the general -purpose timer interrupts. The SysTick peripheral can be disabled by -calling :ref:`systick_disable() `, and -re-enabled using :ref:`systick_resume() `. -However, be aware that calling ``systick_disable()`` will stop the -values coming from :ref:`lang-micros` and :ref:`lang-millis` from -increasing. +The :ref:`SysTick ` peripheral another way to perform +periodic or delayed events. Its separate timer does not conflict with +any other peripherals, but the associated 1 kHz interrupt can jitter +the general purpose timer interrupts. The SysTick peripheral can be +disabled by calling :ref:`systick_disable() +`, and re-enabled using +:ref:`systick_resume() `. However, be aware +that calling ``systick_disable()`` will stop the values coming from +:ref:`lang-micros` and :ref:`lang-millis` from increasing. -- cgit v1.2.3 From 0605b47810b88e8d6b0dd0a9975949e1ac11477e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 20:29:02 -0400 Subject: Docs: whitespace fascism. --- source/_static/apilist.html | 2 +- source/_templates/layout.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_static/apilist.html b/source/_static/apilist.html index e9eb8e3..556fcc9 100644 --- a/source/_static/apilist.html +++ b/source/_static/apilist.html @@ -2,4 +2,4 @@ {% set parents = parents.pop() %} {% if parents %} {{ parents.title }} -{% endif %} \ No newline at end of file +{% endif %} diff --git a/source/_templates/layout.html b/source/_templates/layout.html index 93547f0..4d92d33 100644 --- a/source/_templates/layout.html +++ b/source/_templates/layout.html @@ -2,4 +2,4 @@ {% block rootrellink %}
  • LeafLabs |
    • {{ super() }} -{% endblock %} +{% endblock %} -- cgit v1.2.3 From 6c42c6f5671e830c350c751c10a38fa54d3864bc Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 14 May 2011 19:03:49 -0400 Subject: Docs: Removing first person ("I'll") usage. --- source/unix-toolchain.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 8b81e75..32a380e 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -52,7 +52,7 @@ contemporary Debian-based distribution. **1. Collect and Install Tools** -First I'll give the commands to run, then explain:: +Firs, you'll need some tools:: $ sudo aptitude install build-essential git-core wget screen dfu-util \ openocd python python-serial -- cgit v1.2.3 From 21b3d84b244d0852e79eef2da06cfaa989cc25e8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 17 May 2011 14:31:08 -0400 Subject: Docs: fixing tar invocation in Unix toolchain quickstart. --- source/unix-toolchain.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 32a380e..fddb529 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -98,7 +98,7 @@ in `Python `_, and requires the `PySerial $ git clone git://github.com/leaflabs/libmaple.git libmaple $ cd libmaple $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz - $ tar xvf gcc-arm-none-eabi-latest-linux32.tar.gz + $ tar xvzf gcc-arm-none-eabi-latest-linux32.tar.gz $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up This step is fairly straightforward: do a git clone of the `libmaple -- cgit v1.2.3 From 780ed306ef5fbb6a1defe71f1075885216933953 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 17 May 2011 14:33:05 -0400 Subject: Docs: removing reference to String class. --- source/lang/cpp/string.rst | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/source/lang/cpp/string.rst b/source/lang/cpp/string.rst index 84917c1..3497484 100644 --- a/source/lang/cpp/string.rst +++ b/source/lang/cpp/string.rst @@ -5,15 +5,8 @@ Strings ======= -Text strings can be represented in two ways. You can - -1. Use the :ref:`String ` data type, which is -part of the core as of version 0.0.9, or - -2. You can make a string out of an array of type :ref:`char -` and null-terminate it. - -This page describes the second method. +Text strings on the Maple can be represented with null-terminated +arrays of type :ref:`char `. Examples -------- -- cgit v1.2.3 From fce940294469a49a4d04302a790e9e399e81ad06 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 20 May 2011 16:44:29 -0400 Subject: analogWrite() docs typo --- source/lang/api/analogwrite.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst index dd2192a..b553d8b 100644 --- a/source/lang/api/analogwrite.rst +++ b/source/lang/api/analogwrite.rst @@ -61,7 +61,7 @@ analogWrite() into the right range:: analogWrite(pin, map(duty, 0, 255, 0, 65535)); This will convert values in the range 0-255 to values in the range -0--65,635, which is the correct default range for all of the timers +0--65,535, which is the correct default range for all of the timers which control PWM output. See the :ref:`timers reference ` for more information. -- cgit v1.2.3 From 9975593eb413c7bdb5711f25d9cedb6c276cfd65 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 20 May 2011 15:30:15 -0400 Subject: 0.0.10 docs RC --- source/adc.rst | 4 +- source/hardware/maple-ret6.rst | 146 ++++++++++++++++++++++----------------- source/hardware/maple.rst | 90 +++++++++++++----------- source/lang/api/board-values.rst | 13 ++-- source/lang/api/constants.rst | 1 + source/lang/api/hardwarespi.rst | 2 +- source/lang/api/serial.rst | 2 +- source/language-index.rst | 2 +- source/libmaple/api/systick.rst | 3 +- source/libs/servo.rst | 10 +-- source/systick.rst | 2 + source/usart.rst | 37 +++++----- 12 files changed, 172 insertions(+), 140 deletions(-) diff --git a/source/adc.rst b/source/adc.rst index af613cc..f3d5f55 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -20,7 +20,7 @@ number of techniques must be used to get good precision and accuracy. Noise and Bias -------------- -.. FIXME [0.0.10, Maple-specific] +.. FIXME [0.0.11, Maple form factor-specific] The biggest issues with analog-digital conversion are noise and bias. With the Maple, we have tried to isolate the ADC pins and traces from @@ -38,7 +38,7 @@ voltages that the sample is being compared against. In the case of the Maple, the high reference is |vcc| and the low reference is ground. This means that noise or fluctuations on either |vcc| or ground will affect the measurement. It also means that the voltage you are trying -to sample must be between ground and 3.3V. +to sample must be between ground and 3.3V. .. _adc-range: diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 2f23bc4..b8970e4 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -14,7 +14,7 @@ Technical Specifications * MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor * Clock Speed: **72 MHz** * **512KB Flash** and **64KB SRAM** - * 44 Digital I/O Pins (:ref:`GPIO `) + * 43 Digital I/O Pins (:ref:`GPIO `) * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC `) * Built-in, 2 channel **DAC** at 12 bit resolution @@ -73,12 +73,22 @@ GPIO Information ---------------- The RET6 Edition features 38 ready-to-use general purpose input/output -(GPIO) pins for digital input/output, numbered ``D0`` through ``D37``. -These numbers correspond to the numeric values next to each header on -the Maple silkscreen. More GPIOs (numbered ``D39``\ --``D43``) are -available through use in combination with the +(see :ref:`gpio`) pins for digital input/output, numbered ``D0`` +through ``D37``. These numbers correspond to the numeric values next +to each header on the Maple silkscreen. + +.. _maple-ret6-but: + +Pin ``D38`` is the board's :ref:`button pin `. +It is thus mainly useful as an :ref:`input `. The +pin will :ref:`read ` ``HIGH`` when the :ref:`button +is pressed `. + +More GPIOs (numbered ``D39``\ --``D42``) are available if you use the :ref:`lang-disabledebugports` function; see the :ref:`board-specific debug pin constants ` for more information. +(See :ref:`this erratum ` for information about +the pin numbered ``43`` on the silkscreen). .. TODO [0.1.0] silkscreen pictures which expand abbreviations @@ -87,64 +97,65 @@ debug pin constants ` for more information. Master Pin Map ^^^^^^^^^^^^^^ -.. TODO [0.0.10] Update from base Maple information - This table shows the available functionality on every GPIO pin, by peripheral type. The "STM32" column refers to the port and number that the header is connected to on the microcontroller. The "5V?" column documents whether or not the pin is 5 volt tolerant. .. csv-table:: - :header: "Pin", "STM32", ":ref:`ADC `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`SPI `", "5v?" - - "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" - "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" - "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" - "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" - "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" - "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" - "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" - "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" - "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" - "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" - "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" - "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" - "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" - "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" - "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" - "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" - "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" - "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" - "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" - "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" - "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" - "D21", "PC13", "-", "-", "-", "-", "-", "No" - "D22", "PC14", "-", "-", "-", "-", "-", "No" - "D23", "PC15", "-", "-", "-", "-", "-", "No" - "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" - "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" - "D26", "PC10", "-", "-", "-", "-", "-", "Yes" - "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" - "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" - "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" - "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" - "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes" - "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" - "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" - "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" - "D35", "PC6", "-", "-", "-", "-", "-", "Yes" - "D36", "PC7", "-", "-", "-", "-", "-", "Yes" - "D37", "PC8", "-", "-", "-", "-", "-", "Yes" - -.. TODO [0.0.10] Another table for the JTAG pins + :header: Pin, STM32, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5v? + + D0, PA3, ADC3, TIM2_CH4, -, USART2_RX, -, - + D1, PA2, ADC2, TIM2_CH3, -, USART2_TX, -, - + D2, PA0, ADC0, TIM2_CH1_ETR, -, USART2_CTS, -, - + D3, PA1, ADC1, TIM2_CH2, -, USART2_RTS, -, - + D4, PB5, -, -, ISC1_SMBA, -, SPI3_MOSI, - + D5, PB6, -, TIM4_CH1, I2C1_SCL, -, -, Yes + D6, PA8, -, TIM1_CH1, -, USART1_CK, -, Yes + D7, PA9, -, TIM1_CH2, -, USART1_TX, -, Yes + D8, PA10, -, TIM1_CH3, -, USART1_RX, -, Yes + D9, PB7, -, TIM4_CH2, I2C1_SDA, -, -, Yes + D10, PA4, ADC4, -, -, USART2_CK, SPI1_NSS, - + D11, PA7, ADC7, TIM3_CH2, -, -, SPI1_MOSI, - + D12, PA6, ADC6, TIM3_CH1, -, -, SPI1_MISO, - + D13, PA5, ADC5, -, -, -, SPI1_SCK, - + D14, PB8, -, TIM4_CH3, -, -, -, Yes + D15, PC0, ADC10, -, -, -, -, - + D16, PC1, ADC11, -, -, -, -, - + D17, PC2, ADC12, -, -, -, -, - + D18, PC3, ADC13, -, -, -, -, - + D19, PC4, ADC14, -, -, -, -, - + D20, PC5, ADC15, -, -, -, -, - + D21, PC13, -, -, -, -, -, - + D22, PC14, -, -, -, -, -, - + D23, PC15, -, -, -, -, -, - + D24, PB9, -, TIM4_CH4, -, -, -, Yes + D25, PD2, -, TIM3_ETR, -, -, UART5_RX, Yes + D26, PC10, -, -, -, -, UART4_TX, Yes + D27, PB0, ADC8, TIM3_CH3, -, -, -, - + D28, PB1, ADC9, TIM3_CH4, -, -, -, - + D29, PB10, -, -, I2C2_SCL, USART3_TX, -, Yes + D30, PB11, -, -, I2C2_SDA, USART3_RX, -, Yes + D31, PB12, -, TIM1_BKIN, I2C2_SMBA, USART3_CK, SPI2_NSS, Yes + D32, PB13, -, TIM1_CH1N, -, USART3_CTS, SPI2_SCK, Yes + D33, PB14, -, TIM1_CH2N, -, USART3_RTS, SPI2_MISO, Yes + D34, PB15, -, TIM1_CH3N, -, -, SPI2_MOSI, Yes + D35, PC6, -, TIM8_CH1, -, -, -, Yes + D36, PC7, -, TIM8_CH2, -, -, -, Yes + D37, PC8, -, TIM8_CH3, -, -, -, Yes + D38, PC9, -, TIM8_CH4, -, -, -, Yes + D39, PA13, -, -, -, -, -, Yes + D40, PA14, -, -, -, -, -, Yes + D41, PA15, -, -, -, -, SPI3_NSS, Yes + D42, PB3, -, -, -, -, SPI3_SCK, Yes Timer Pin Map ^^^^^^^^^^^^^ -.. TODO [0.0.10] Add Timer 5,6,7,8 information - The following table shows what pins are associated with a particular -timer's capture/compare channels. +timer's capture/compare channels. Note that timer 5's channels share +pins with timer 2 (e.g., timer 5 channel 1 is also available on D2, +channel 2 on D3, etc.). .. csv-table:: :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4 @@ -154,6 +165,7 @@ timer's capture/compare channels. 2 | D2 | D3 | D1 | D0 3 | D12 | D11 | D27 | D28 4 | D5 | D9 | D14 | D24 + 8 | D35 | D36 | D37 | :ref:`D38 ` .. _maple-ret6-exti-map: @@ -306,25 +318,31 @@ Errata This section lists known issues and warnings for the Maple RET6 Edition. * **Power Supply Marketing Mistake**: We originally sold the Maple - advertising that it was capable of supplying up to 800 mA; the - correct value is 500 mA. + RET6 Edition advertising that it was capable of supplying up to 800 + mA; the correct value is 500 mA. .. _maple-ret6-uart-errata: -* **UART4, UART5 GPIOs unavailable**: Pins related to the digital - to analog converter (DAC) and UARTs 4 and 5 are not broken out to - headers. The RET6 Edition's hardware layout is identical to that of - the Maple Rev 5, which wasn't designed for use with these +* **UART4, UART5 GPIOs unavailable**: Pins related to UARTs 4 and 5 + are not broken out to headers (specifically, PC11/UART4_RX and + PC12/UART5_TX). The RET6 Edition's hardware layout is identical to + that of the Maple Rev 5, which wasn't designed for use with these STM32F103RET6-only peripherals. * **DAC channel 2 on BOARD_LED_PIN**: The Maple Rev 5 connects PA5 to the board's built-in LED; this is the same GPIO bit which is - connected to the DAC's channel 2 output. + connected to the DAC's channel 2 output. This is also due to the + RET6 Edition's board layout being copied from the base Maple Rev 5. + +.. _maple-ret6-nrst-pb4: -* **Reset and NJTRST tied together**: The MCU's reset pin is connected - to PB4, the NJTRST (JTAG reset) pin, which is pin 43. Thus, - attempting to use pin 43 as a GPIO will reset your board (and also - prevents the JTAG "reset halt" command from working properly). +* **Reset and PB4 tied together**: The Maple's reset line is also + connected to PB4, which is labeled on the silkscreen as pin 43. + Thus, attempting to use pin 43 as a GPIO may reset your board. This + has other implications. Since PB4 is also the JTAG NJTRST line, + this prevents the :ref:`JTAG ` "reset halt" command from + working properly. Also, since PB4 is SPI3_MISO, the SPI3 peripheral + is not fully usable. Recommended Reading ------------------- @@ -338,3 +356,5 @@ Recommended Reading * `Programming Manual `_ (PDF; assembly language and register reference) + * `ST's STM32F103RE reference page + `_ diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index c2dc895..bb4bf35 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -14,7 +14,7 @@ Technical Specifications * MCU: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor * Clock Speed: **72 MHz** * **128KB Flash** and **20KB SRAM** - * 44 Digital I/O Pins (:ref:`GPIO `) + * 43 Digital I/O Pins (:ref:`GPIO `) * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC `) * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) @@ -26,7 +26,7 @@ Technical Specifications * Integrated **SPI** (:ref:`SPI `) * Integrated **I2C** (:ref:`I2C `) * 7 Channels of Direct Memory Access (**DMA**) - (:ref:`libmaple.dma`) + (:ref:`libmaple-dma`) * 3 **USART** divices (:ref:`USART `) * Four 4-channel **timers** (:ref:`Timers `) * Supplies up to 500mA @ 3.3v (with separate 250 mA digital and @@ -115,13 +115,23 @@ DONE will also light up. GPIO Information ---------------- -The Maple features 38 ready-to-use general purpose input/output (GPIO) -pins for digital input/output, numbered ``D0`` through ``D37``. These -numbers correspond to the numeric values next to each header on the -Maple silkscreen. More GPIOs (numbered ``D39``\ --``D43``) are -available through use in combination with the +The Maple features 38 ready-to-use general purpose input/output (see +:ref:`gpio`) pins for digital input/output, numbered ``D0`` through +``D37``. These numbers correspond to the numeric values next to each +header on the Maple silkscreen. + +.. _maple-ret6-but: + +Pin ``D38`` is the board's :ref:`button pin `. +It is thus mainly useful as an :ref:`input `. The +pin will :ref:`read ` ``HIGH`` when the :ref:`button +is pressed `. + +More GPIOs (numbered ``D39``\ --``D42``) are available if you use the :ref:`lang-disabledebugports` function; see the :ref:`board-specific debug pin constants ` for more information. +(See :ref:`this erratum ` for information about the +pin numbered ``43`` on the silkscreen). .. TODO [0.1.0] silkscreen pictures which expand abbreviations @@ -138,35 +148,35 @@ documents whether or not the pin is 5 volt tolerant. .. csv-table:: :header: Pin, STM32, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5v? - D0, PA3, ADC3, TIM2_CH4, -, USART2_RX, -, No - D1, PA2, ADC2, TIM2_CH3, -, USART2_TX, -, No - D2, PA0, ADC0, TIM2_CH1_ETR, -, USART2_CTS, -, No - D3, PA1, ADC1, TIM2_CH2, -, USART2_RTS, -, No - D4, PB5, -, -, ISC1_SMBA, -, -, No + D0, PA3, ADC3, TIM2_CH4, -, USART2_RX, -, - + D1, PA2, ADC2, TIM2_CH3, -, USART2_TX, -, - + D2, PA0, ADC0, TIM2_CH1_ETR, -, USART2_CTS, -, - + D3, PA1, ADC1, TIM2_CH2, -, USART2_RTS, -, - + D4, PB5, -, -, ISC1_SMBA, -, -, - D5, PB6, -, TIM4_CH1, I2C1_SCL, -, -, Yes D6, PA8, -, TIM1_CH1, -, USART1_CK, -, Yes D7, PA9, -, TIM1_CH2, -, USART1_TX, -, Yes D8, PA10, -, TIM1_CH3, -, USART1_RX, -, Yes D9, PB7, -, TIM4_CH2, I2C1_SDA, -, -, Yes - D10, PA4, ADC4, -, -, USART2_CK, SPI1_NSS, No - D11, PA7, ADC7, TIM3_CH2, -, -, SPI1_MOSI, No - D12, PA6, ADC6, TIM3_CH1, -, -, SPI1_MISO, No - D13, PA5, ADC5, -, -, -, SPI1_SCK, No + D10, PA4, ADC4, -, -, USART2_CK, SPI1_NSS, - + D11, PA7, ADC7, TIM3_CH2, -, -, SPI1_MOSI, - + D12, PA6, ADC6, TIM3_CH1, -, -, SPI1_MISO, - + D13, PA5, ADC5, -, -, -, SPI1_SCK, - D14, PB8, -, TIM4_CH3, -, -, -, Yes - D15, PC0, ADC10, -, -, -, -, No - D16, PC1, ADC11, -, -, -, -, No - D17, PC2, ADC12, -, -, -, -, No - D18, PC3, ADC13, -, -, -, -, No - D19, PC4, ADC14, -, -, -, -, No - D20, PC5, ADC15, -, -, -, -, No - D21, PC13, -, -, -, -, -, No - D22, PC14, -, -, -, -, -, No - D23, PC15, -, -, -, -, -, No + D15, PC0, ADC10, -, -, -, -, - + D16, PC1, ADC11, -, -, -, -, - + D17, PC2, ADC12, -, -, -, -, - + D18, PC3, ADC13, -, -, -, -, - + D19, PC4, ADC14, -, -, -, -, - + D20, PC5, ADC15, -, -, -, -, - + D21, PC13, -, -, -, -, -, - + D22, PC14, -, -, -, -, -, - + D23, PC15, -, -, -, -, -, - D24, PB9, -, TIM4_CH4, -, -, -, Yes D25, PD2, -, TIM3_ETR, -, -, -, Yes D26, PC10, -, -, -, -, -, Yes - D27, PB0, ADC8, TIM3_CH3, -, -, -, No - D28, PB1, ADC9, TIM3_CH4, -, -, -, No + D27, PB0, ADC8, TIM3_CH3, -, -, -, - + D28, PB1, ADC9, TIM3_CH4, -, -, -, - D29, PB10, -, -, I2C2_SCL, USART3_TX, -, Yes D30, PB11, -, -, I2C2_SDA, USART3_RX, -, Yes D31, PB12, -, TIM1_BKIN, I2C2_SMBA, USART3_CK, SPI2_NSS, Yes @@ -176,13 +186,11 @@ documents whether or not the pin is 5 volt tolerant. D35, PC6, -, -, -, -, -, Yes D36, PC7, -, -, -, -, -, Yes D37, PC8, -, -, -, -, -, Yes - -.. TODO [0.0.10] JTAG pins - -.. The following pins are used for :ref:`jtag` debugging by default, but -.. can be used as ordinary GPIOs through the use of the -.. :ref:`lang-disabledebugports` function. (Though see :ref:`this -.. erratum `). + D38, PC9, -, -, -, -, -, Yes + D39, PA13, -, -, -, -, -, Yes + D40, PA14, -, -, -, -, -, Yes + D41, PA15, -, -, -, -, -, Yes + D42, PB3, -, -, -, -, -, Yes Timer Pin Map ^^^^^^^^^^^^^ @@ -288,7 +296,7 @@ This section lists the Maple's :ref:`board-specific values - ``BOARD_USART2_RX_PIN``: 0 - ``BOARD_USART3_TX_PIN``: 29 - ``BOARD_USART3_RX_PIN``: 30 -- ``BOARD_NR_SPI``: 2 +- ``BOARD_NR_SPI``: 2 - ``BOARD_SPI1_NSS_PIN``: 10 - ``BOARD_SPI1_MOSI_PIN``: 11 - ``BOARD_SPI1_MISO_PIN``: 12 @@ -358,12 +366,14 @@ Rev 5 from its silkscreen. This mistake was fixed in later manufacturing runs. -.. _maple-reset-njtrst: +.. _maple-nrst-pb4: -* **Reset and NJTRST tied together**: The MCU's reset pin is connected - to PB4, the NJTRST pin, which is pin 43. Thus, attempting to use - pin 43 as a GPIO will reset your board (and also prevents the JTAG - "reset halt") command from working properly. +* **Reset and PB4 tied together**: The Maple's reset line is also + connected to PB4, which is labeled on the silkscreen as pin 43. + Thus, attempting to use pin 43 as a GPIO may reset your board. This + has other implications. Since PB4 is also the JTAG NJTRST line, + this prevents the :ref:`JTAG ` "reset halt" command from + working properly. Rev 3 ~~~~~ diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst index 5fbf20f..7198407 100644 --- a/source/lang/api/board-values.rst +++ b/source/lang/api/board-values.rst @@ -23,9 +23,6 @@ Documentation `. Constants --------- -.. TODO [systick.rst] Add a link to systick.rst instead of systick.h -.. below, when systick.rst exists. - - ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on your board. @@ -35,9 +32,8 @@ Constants - ``CLOCK_SPEED_HZ``: Clock speed of your board, in hertz (Hz). This is the same as ``CLOCK_SPEED_MHZ`` × 1,000,000. -- ``SYSTICK_RELOAD_VAL``: Value used when reloading the :ref:`SysTick - ` timer's counter. For :ref:`lang-millis` to work - properly, this must be ``CYCLES_PER_MICROSECOND`` × 1,000 - 1. +- ``SYSTICK_RELOAD_VAL``: Value used when reloading the :ref:`systick` + timer's counter [#fmillis]_. .. _lang-board-values-but: @@ -205,3 +201,8 @@ See Also - :ref:`lang-pwmwrite` - :ref:`lang-enabledebugports` - :ref:`lang-disabledebugports` + +.. rubric:: Footnotes + +.. [#fmillis] In order for :ref:`lang-millis` to work properly, this + must be ``CYCLES_PER_MICROSECOND`` × 1,000 - 1. diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst index 00c1a5c..3ba99f0 100644 --- a/source/lang/api/constants.rst +++ b/source/lang/api/constants.rst @@ -42,6 +42,7 @@ Note that the ``true`` and ``false`` constants are typed in lowercase; unlike e.g. ``HIGH``, ``LOW``, ``INPUT``, and ``OUTPUT`` (which are described below). +.. _lang-pin-levels: Pin Levels: HIGH and LOW ------------------------ diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst index 289ded5..a80e429 100644 --- a/source/lang/api/hardwarespi.rst +++ b/source/lang/api/hardwarespi.rst @@ -43,7 +43,7 @@ Turning the SPI Port On Now it's time to turn your SPI port on. Do this with the ``begin()`` function (an example is given below). -.. FIXME [0.0.10] Breathe doesn't include the class; fix & submit pull req +.. FIXME [0.0.11] Breathe doesn't include the class; fix & submit pull req .. doxygenfunction:: HardwareSPI::begin diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst index 0821f43..a08c9b7 100644 --- a/source/lang/api/serial.rst +++ b/source/lang/api/serial.rst @@ -12,7 +12,7 @@ devices. Introduction ------------ -.. FIXME [0.0.10] UART4, UART5 +.. FIXME [0.0.12/Maple Native] UART4, UART5 To use a serial port to communicate with an external serial device, connect the TX pin to your device's RX pin, the RX to your device's TX diff --git a/source/language-index.rst b/source/language-index.rst index 225a9ae..6c20605 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -24,7 +24,7 @@ programmers familiar with the Arduino language. - If you're looking for pointers to low-level details, see the :ref:`Language Recommended Reading - `. + ` and :ref:`libmaple` pages. .. _index-language-index-cpp: .. _index-language-index-api: diff --git a/source/libmaple/api/systick.rst b/source/libmaple/api/systick.rst index a8c0971..fa959f2 100644 --- a/source/libmaple/api/systick.rst +++ b/source/libmaple/api/systick.rst @@ -1,6 +1,7 @@ .. highlight:: c -.. FIXME [0.0.10] move these to the right places: +.. FIXME [0.1.0] move these to the right places once Breathe is fast +.. enough to use for libmaple proper .. _libmaple-systick_disable: diff --git a/source/libs/servo.rst b/source/libs/servo.rst index 3b96467..f131ee1 100644 --- a/source/libs/servo.rst +++ b/source/libs/servo.rst @@ -29,13 +29,6 @@ servomotor attached to pin 9, you could write :: servo.attach(9); -.. TODO [0.0.10] figure out the cpp domain well enough to replace -.. references here - -.. _libs-servo-attach: - -.. _libs-servo-attached: - .. doxygenclass:: Servo :members: @@ -54,7 +47,8 @@ the servos with "bit-banged" :ref:`PWM `, the Maple implementation uses :ref:`timers ` to drive the PWM directly. Consequently, **the Maple implementation only allows Servo instances -to** :ref:`attach ` **to pins that support PWM**. +to attach (via** :cpp:func:Servo::attach() **) to pins that support +PWM**. To determine if a pin supports PWM, you can either check if "PWM" appears next to its number on your board's silkscreen, or look for it diff --git a/source/systick.rst b/source/systick.rst index 6f20133..afc8d09 100644 --- a/source/systick.rst +++ b/source/systick.rst @@ -1,3 +1,5 @@ +.. _systick: + SysTick ======= diff --git a/source/usart.rst b/source/usart.rst index 9506cc8..b3e1ea1 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -1,8 +1,7 @@ .. _usart: -======= - USART -======= +USART +===== .. contents:: Contents :local: @@ -10,15 +9,17 @@ Hardware/Circuit Design ----------------------- -.. FIXME [0.0.10] UART4 and UART5 -.. FIXME [0.1.0] Maple Native and Mini info and links +.. FIXME [0.0.12/Maple Native] UART4 and UART5, Native links +.. FIXME [0.0.11] Mini info and links -The Maple has 3 separate USART devices. In the most simple use case, -the RX and TX pins are used to send data at a predetermined baudrate -with the line voltage level relative to ground. Their usage is -documented in the :ref:`Serial Ports ` language reference -page. Which pins correspond to the USART TX and RX pins are given on -your board's silkscreen, and also in the board-specific USART pin maps +Each LeafLabs board has at least 3 separate USART devices. In the most +simple use case, the RX and TX pins are used to send data at a +predetermined baud rate with the line voltage level relative to +ground. Their usage is documented in the :ref:`Serial Ports +` language reference page. + +Which pins correspond to the USART TX and RX pins are given on your +board's silkscreen, and also in the board-specific USART pin maps available here: * :ref:`Maple ` @@ -37,9 +38,11 @@ certainly be possible. Recommended Reading ------------------- -* `Wikipedia article on Universal asynchronous receiver/transmitter (USART) `_ -* `Arduino reference on Serial `_ -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) +* `Wikipedia article on Universal Asynchronous Receiver/Transmitter + (USART) + `_ +* `Arduino Serial reference + `_ +* ST `Reference Manual RM0008 + `_ + (PDF), Chapter 27. -- cgit v1.2.3 From 401e463ae777cf110344957b7d5bc7c2962338b2 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 23 May 2011 10:36:40 -0400 Subject: Servo docs fixups. --- source/libs/servo.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/libs/servo.rst b/source/libs/servo.rst index f131ee1..80288c6 100644 --- a/source/libs/servo.rst +++ b/source/libs/servo.rst @@ -16,6 +16,9 @@ If you are using the :ref:`Unix toolchain `, the library is located in the ``/libraries/Servo/`` :ref:`libmaple` directory. +.. contents:: Contents + :local: + Servo Class Reference --------------------- @@ -43,12 +46,12 @@ However, there are some differences, essentially at the level of implementation details. The major difference is that while the Arduino implementation drives -the servos with "bit-banged" :ref:`PWM `, the Maple -implementation uses :ref:`timers ` to drive the PWM directly. +servos with "bit-banged" PWM (in the sense that timer interrupt +handlers are used to manually toggle pins), the Maple implementation +uses :ref:`timers ` to drive the PWM directly. Consequently, **the Maple implementation only allows Servo instances -to attach (via** :cpp:func:Servo::attach() **) to pins that support -PWM**. +to attach to pins that support PWM**. To determine if a pin supports PWM, you can either check if "PWM" appears next to its number on your board's silkscreen, or look for it -- cgit v1.2.3 From 0988f2ac6bd83a58f4d674860d5e0b94e84dbd37 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 23 May 2011 14:17:03 -0400 Subject: RET6 Edition docs typo. --- source/hardware/maple-ret6.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index b8970e4..5bd00f1 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -54,7 +54,7 @@ the jumper to the desired selector before reconnecting power. You can also power the Maple via the pin labeled "Vin" on the lower header. However, don't do this while simultaneously powering the -board from another source, or you could damage the it. +board from another source, or you could damage the board. Using the Built-in Battery Charger ---------------------------------- -- cgit v1.2.3 From ab913f35eb7d4ac944d86f48b41208b5632e9439 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 23 May 2011 14:29:23 -0400 Subject: Generifying maple-ide-install.rst. In line with some changes made earlier today to the maple-ide repo, the master libmaple branch no longer points to a particular IDE release as "current", since there's no way it can know. From now on, only release branches will contain the blessed download links. --- source/maple-ide-install.rst | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 98a5fcc..2818bfb 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -17,25 +17,31 @@ us directly`_\ ! Download -------- -Maple IDE 0.0.10 Beta is now available. Choose the correct version -for your operating system: - -.. list-table:: - :widths: 15 30 50 - :header-rows: 1 - - * - Platform - - Status - - IDE Package - * - Windows - - Tested on 32bit Windows XP - - `maple-ide-0.0.10beta-windowsxp32.zip `_ (about 75mb) - * - Linux - - Tested on Ubuntu 10.04 (32bit) - - `maple-ide-0.0.10beta-linux32.tgz `_ (about 30mb) - * - Mac OSX - - Tested on Snow Leopard (10.6) - - `maple-ide-0.0.10beta-macosx-10_6.dmg `_ (about 40mb) +.. FIXME [0.0.11] Update this for the release. + +This documentation was built from a development version of libmaple. +See the formally released `LeafLabs documentation +`_ for more information about the current +Maple IDE release. + +.. Choose the correct version for your operating system: + +.. .. list-table:: +.. :widths: 15 30 50 +.. :header-rows: 1 + +.. * - Platform +.. - Status +.. - IDE Package +.. * - Windows +.. - Tested on 32-bit Windows XP +.. - `maple-ide-0.0.10-windowsxp32.zip `_ (about 75 MB) +.. * - Linux +.. - Tested on Ubuntu 10.04 (32-bit) +.. - `maple-ide-0.0.10-linux32.tgz `_ (about 30MB) +.. * - Mac OSX +.. - Tested on Snow Leopard (10.6) +.. - `maple-ide-0.0.10-macosx-10_6.dmg `_ (about 40 MB) The package bundles together a compiler, an upload utility, a software library, and a simple GUI text editor. All this software is `free and -- cgit v1.2.3 From fdec8d0ad40c81758e42afd21448a73064433115 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 23 May 2011 16:29:50 -0400 Subject: Docs: maple-ret6.rst touchups. --- source/hardware/maple-ret6.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 5bd00f1..9ee46d2 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -329,6 +329,8 @@ This section lists known issues and warnings for the Maple RET6 Edition. that of the Maple Rev 5, which wasn't designed for use with these STM32F103RET6-only peripherals. +.. _maple-ret6-dac-ch2: + * **DAC channel 2 on BOARD_LED_PIN**: The Maple Rev 5 connects PA5 to the board's built-in LED; this is the same GPIO bit which is connected to the DAC's channel 2 output. This is also due to the @@ -336,8 +338,8 @@ This section lists known issues and warnings for the Maple RET6 Edition. .. _maple-ret6-nrst-pb4: -* **Reset and PB4 tied together**: The Maple's reset line is also - connected to PB4, which is labeled on the silkscreen as pin 43. +* **Reset and PB4 tied together**: The RET6 Edition's reset line is + also connected to PB4, which is labeled on the silkscreen as pin 43. Thus, attempting to use pin 43 as a GPIO may reset your board. This has other implications. Since PB4 is also the JTAG NJTRST line, this prevents the :ref:`JTAG ` "reset halt" command from -- cgit v1.2.3 From af79aed36057c8cd3b1d87689b738bed6c4ad46e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 23 May 2011 17:55:11 -0400 Subject: Docs: libmaple overview.rst fixes. --- source/libmaple/overview.rst | 54 ++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 30 deletions(-) diff --git a/source/libmaple/overview.rst b/source/libmaple/overview.rst index 9bce564..345769b 100644 --- a/source/libmaple/overview.rst +++ b/source/libmaple/overview.rst @@ -5,9 +5,9 @@ Overview ======== -This page is a general overview of the low-level aspects of libmaple -proper. It provides a general perspective of the library's goals and -design. Examples are given from the libmaple sources. +This page is a general overview of libmaple proper. It provides a +general perspective of the library's goals and design. Examples are +given from libmaple's sources. .. contents:: Contents :local: @@ -22,10 +22,10 @@ on the STM32 line. Let's start with the basics. If you're interested in low-level details on the STM32, then you're going to spend a lot of quality time wading through `ST RM0008 -`_. -RM0008 is the single most important tool in your toolbox. It is the -authoritative documentation for the capabilities and low-level -programming interfaces of ST's line of ARM Cortex M3 microcontrollers. +`_. +That document is the single most important tool in your toolbox. It +is the authoritative documentation for the capabilities and register +interfaces of the STM32 line. Perhaps you haven't read it in detail, but maybe you've at least thumbed through a few of the sections, trying to gain some @@ -33,11 +33,9 @@ understanding of what's going on. If you've done that (and if you haven't, just take our word for it), then you know that underneath the covers, *everything* is controlled by messing with bits in the seemingly endless collections of registers specific to every -peripheral. The `USARTs `_ have -data registers; (some of the) the `timers -`_ have capture/compare -registers, the `GPIOs `_ have -output data registers, etc. +peripheral. The :ref:`USARTs ` have data registers; (some of +the) the :ref:`timers ` have capture/compare registers, the +:ref:`GPIOs ` have output data registers, etc. For the most part, Wirish does everything it can to hide this truth from you. That's because when you really just want to get your robot @@ -107,10 +105,10 @@ The timers on the STM32 line are more involved than the ADCs, so a /** Timer device type */ typedef struct timer_dev { - timer_reg_map_union regs; - rcc_clk_id clk_id; - timer_type type; - voidFuncPtr handlers[]; + timer_reg_map regs; /**< Register map */ + rcc_clk_id clk_id; /**< RCC clock information */ + timer_type type; /**< Timer's type */ + voidFuncPtr handlers[]; /**< User IRQ handlers */ } timer_dev; However, as you can see, both ADC and timer devices are named @@ -223,7 +221,7 @@ you want? That depends on if there's more than one xxx or not. If there's only one xxx, then libmaple guarantees there will be a ``#define`` that looks like like this:: - #define XXX_BASE ((xxx_reg_map*)0xDEADBEEF) + #define XXX_BASE ((struct xxx_reg_map*)0xDEADBEEF) That is, you're guaranteed there will be a pointer to the (only) ``xxx_reg_map`` you want, and it will be called @@ -231,9 +229,9 @@ That is, you're guaranteed there will be a pointer to the (only) the fixed location in memory where the register map begins). Here's a concrete example from ``dac.h``:: - #define DAC_BASE ((dac_reg_map*)0x40007400) + #define DAC_BASE ((struct dac_reg_map*)0x40007400) -How can you use these? This is perhaps best explained by example. +How can you use these? This is perhaps best explained by example. * In order to write 2048 to the channel 1 12-bit left-aligned data holding register (RM0008: DAC_DHR12L1), you could write:: @@ -252,24 +250,20 @@ That covers the case where there's a single xxx peripheral. If there's more than one (say, if there are *n*), then ``xxx.h`` provides the following:: - #define XXX1_BASE ((xxx_reg_map*)0xDEADBEEF) - #define XXX2_BASE ((xxx_reg_map*)0xF00DF00D) + #define XXX1_BASE ((struct xxx_reg_map*)0xDEADBEEF) + #define XXX2_BASE ((struct xxx_reg_map*)0xF00DF00D) ... - #define XXXn_BASE ((xxx_reg_map*)0x13AF1AB5) + #define XXXn_BASE ((struct xxx_reg_map*)0x13AF1AB5) -Here's a concrete example from ``adc.h``:: +Here are some examples from ``adc.h``:: - /** ADC1 register map base pointer. */ - #define ADC1_BASE ((adc_reg_map*)0x40012400) - /** ADC2 register map base pointer. */ - #define ADC2_BASE ((adc_reg_map*)0x40012800) - /** ADC3 register map base pointer. */ - #define ADC3_BASE ((adc_reg_map*)0x40013C00) + #define ADC1_BASE ((struct adc_reg_map*)0x40012400) + #define ADC2_BASE ((struct adc_reg_map*)0x40012800) In order to read from the ADC1's regular data register (where the results of ADC conversion are stored), you might write:: - uint32 converted_result = ADC1->DR; + uint32 converted_result = ADC1_BASE->DR; Register Bit Definitions ------------------------ -- cgit v1.2.3 From 704449695b26e6cf73a7599dc0ecaa61a6ff2716 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 23 May 2011 20:10:01 -0400 Subject: Docs: troubleshooting.rst touchups --- source/troubleshooting.rst | 56 +++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index bf1b129..b5f496e 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -133,35 +133,35 @@ files. If you recompile everything, it should be fine. .. _troubleshooting-upload: -======================== - Common upload problems -======================== +====================== +Common upload problems +====================== My program is too large! ------------------------ -First, make sure you're using the FLASH target instead of RAM; there -is several times more FLASH memory available for user programs. +First, make sure you're using the Flash target instead of RAM; there +is several times more Flash memory available for user programs. ``No DFU capable USB device found`` ----------------------------------- -This probably means you don't have a Maple plugged in or powered on. -Try unplugging and plugging your Maple or pressing the RESET button. +This probably means the Maple isn't plugged in or powered on. Try +unplugging and plugging back in, or pressing the RESET button. This can also happen if you disable the USB peripheral, e.g. using :ref:`SerialUSB.end() `. -I have multiple Maples installed; how do I know which one will get flashed? ---------------------------------------------------------------------------- +I have multiple boards plugged in; how do I know which one will get programmed? +------------------------------------------------------------------------------- Because the Maple IDE uses DFU to upload programs, you can't select a -particular Maple from the Serial Port menu to upload to a particular -board. There's no solution to this problem for now: you'll have to -just plug in the Maples one at a time. If this is a real problem let -us know and we'll see if we can come up with a better solution. +particular board to upload to. There's no solution to this problem +for now: you'll have to just plug in your boards one at a time. If +this is a real problem, let us know, and we'll see if we can come up +with a better solution. -My flash programs don't seem to stick; they behave like they are RAM! +My Flash programs don't seem to stick; they behave like they are RAM! --------------------------------------------------------------------- If you have uploaded a program to RAM, this will take priority over @@ -171,15 +171,15 @@ by unplugging your Maple to clear the contents of RAM, then plugging it back in. If you are using the :ref:`Unix toolchain `, Make sure -you :command:`make clean` when switching between FLASH and RAM -targets; :command:`make` isn't smart enough to rebuild everything that -needs to be for the new target. +you :command:`make clean` when switching between Flash and RAM +targets; our Makefile isn't smart enough to rebuild everything for the +new target. .. _troubleshooting-shell: -===================== - Command-line issues -===================== +=================== +Command-Line Issues +=================== [Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` ----------------------------------------------------- @@ -188,26 +188,26 @@ This is a nasty one! It means that all 32 possible CDC_ACM serial devices (:file:`/dev/ttyACM25`, etc.) have been used up. The usual cause is using a serial port monitor and not closing it -before restarting the Maple or uploading a new program. The operating -system doesn't like that, and locks up that device. After reset the -Maple comes back up as a new device. If you develop heavily and don't -restart you'll blow right through all 32 devices. +before restarting the board or uploading a new program. The operating +system doesn't like that, and locks up that device. After reset, the +board comes back up as a new device. If you develop heavily and don't +restart, you'll blow right through all 32 devices. The lazy solution is to always close the monitor before restarting, and if you get this error in :file:`dmesg` after a dfu-util "Not Found" error, restart you machine. The hacker solution is to restart your cdc_acm kernel module. On -Ubuntu 09.10, this goes a little something like:: +Ubuntu 9.10, this goes a little something like:: $ sudo rmmod cdc-acm $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko .. _troubleshooting-tips-tricks: -================= - Tips and Tricks -================= +=============== +Tips and Tricks +=============== .. _troubleshooting-perpetual-bootloader: -- cgit v1.2.3 From 8fa6698d79054cf9b8a25fb0c91584415a152359 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 24 May 2011 22:32:01 -0400 Subject: Docs: lang/api/constants.rst touchups Mostly, make it less pedantic. Also some stylistic and content fixes. --- source/lang/api/constants.rst | 94 ++++++++++++++++++++----------------------- 1 file changed, 44 insertions(+), 50 deletions(-) diff --git a/source/lang/api/constants.rst b/source/lang/api/constants.rst index 3ba99f0..6f69dfe 100644 --- a/source/lang/api/constants.rst +++ b/source/lang/api/constants.rst @@ -62,7 +62,7 @@ pin is configured as an ``INPUT`` (using :ref:`pinMode() `, the microcontroller will report ``HIGH`` if a voltage of 3 volts or more is present at the pin. -When a pin is configured to ``OUTPUT`` with pinMode, and set to +When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to ``HIGH`` with :ref:`digitalWrite() `, the pin is at 3.3 volts. In this state it can *source* current, e.g. light an LED that is connected through a series resistor to ground, or to another @@ -82,9 +82,9 @@ pin. When a pin is configured to ``OUTPUT`` with ``pinMode()``, and set to ``LOW`` with :ref:`digitalWrite() `, the -microcontroller will attempt to keep that pin's voltage at 0V. In this +microcontroller will attempt to keep that pin's voltage at 0 V. In this state it can *sink* current, e.g. light an LED that is connected -through a series resistor to +3.3V, or to another pin configured as an +through a series resistor to +3.3 V, or to another pin configured as an output, and set to ``HIGH``. Pin Modes @@ -104,11 +104,11 @@ modes, see the :ref:`pinMode() ` reference page. INPUT ^^^^^ -Maple (STM32) pins configured as ``INPUT`` are said to be in a -high-impedance state. One way of explaining this is that pins -configured as ``INPUT`` make extremely small demands on the circuit -that they are sampling. This makes them useful for reading a sensor, -but not powering an LED. +Pins configured as ``INPUT`` are said to be in a *high-impedance +state*. One way of explaining this is that pins configured as +``INPUT`` make very few demans on circuit that they are connected +to. This makes them useful for reading a sensor, but not powering an +LED. .. _lang-constants-output: @@ -117,31 +117,31 @@ OUTPUT Pins configured as ``OUTPUT`` with :ref:`pinMode() ` are said to be in a low-impedance state. This means that they can provide -a substantial amount of current to other circuits. STM32 pins can -source (provide positive current) or sink (provide negative current) -up to 50 mA (milliamps) of current to other devices/circuits. This -makes them useful for powering LEDs, but useless for reading sensors. +a substantial amount of current to other circuits. Pins can source +(provide positive current) or sink (provide negative current) up to 50 +mA (milliamps) of current to other devices/circuits. This makes them +useful for powering LEDs, but useless for reading sensors. Pins configured as outputs can also be damaged or destroyed if short -circuited to either ground or 3.3V power rails. The amount of current -provided by an STM32 pin is also not enough to power most relays or -motors, and some interface circuitry will be required. +circuited to either ground or power supplies. The amount of current +provided by a pin is also not enough to power most relays or motors, +and some interface circuitry will be required. .. _lang-constants-integers: Integer Constants ----------------- -Integer constants (or more properly speaking, integer *literals*) are -numbers used directly in a sketch, like ``123``. By default, an -integer literal is treated as a (signed) :ref:`int `, but -you can change this with the U and L modifiers (see :ref:`below -`). You can specify negative numbers by -putting a minus sign in front, like ``-123``. +Integer constants are numbers used directly in a sketch, like +``123``. By default, an integer constant is treated as a (signed) +:ref:`int `, but you can change this with the U and L +modifiers (see :ref:`below `). You can +specify negative numbers by putting a minus sign in front, like +``-123``. -Normally, integer literals are treated as base 10 (decimal) integers, +Normally, integer constants are treated as base 10 (decimal) integers, but special notation (formatters) may be used to enter numbers in -other bases. These are summarized in the following table: +other bases. These are explained in the following table: .. list-table:: :header-rows: 1 @@ -172,8 +172,8 @@ other bases. These are summarized in the following table: - Characters 0-9, A-F (or a-f) valid Binary constants (like ``B1111011``) for values between 0 and 255 are -supported for compatibility with Arduino only. Their use in new -programs is discouraged. +supported for compatibility with Arduino only. You shouldn't use them +in new programs. .. _lang-constants-integers-dec: @@ -187,8 +187,7 @@ For example, the decimal literal ``101`` is one hundred and one: 1×10\ .. _lang-constants-integers-bin: **Binary** is base two. Only characters 0 and 1 are valid. Binary -literals are indicated by the prefix ``0b`` (this is a :ref:`GCC -` extension; it's not standard C++). +literals are indicated by the prefix ``0b``. For example, the binary literal ``0b101`` is five: 1×2\ :sup:`2` + 0×2\ :sup:`1` + 1×2\ :sup:`0` = 5. @@ -203,19 +202,19 @@ For example, the octal literal ``0101`` is sixty five: 1×8\ :sup:`2` + .. warning:: Bugs sometimes result by (unintentionally) including a leading "0" before an integer literal, which makes the compiler - interpret it in octal. + treat it as an octal number. .. _lang-constants-integers-hex: **Hexadecimal** (or "hex") is base sixteen. Valid characters are 0 through 9 and letters A through F; A has the value 10, B is 11, up to -F, which is 15. Hex values are indicated by the prefix ``0x``. A-F -may be typed in upper or lower case (a-f). +F, which is 15. Hex values are indicated by the prefix ``0x``. A-F +can be typed in upper or lower case (a-f). -For example, the hexadecimal literal ``0x101`` is two hundred fifty +For example, the hexadecimal constant ``0x101`` is two hundred fifty seven: 1×16\ :sup:`2` + 0×16\ :sup:`1` + 1×16\ :sup:`0` = 257. -The hexadecimal literal ``0xCF2`` is three thousand, three hundred +The hexadecimal constant ``0xCF2`` is three thousand, three hundred fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314. (Remember that in hex, ``A`` means 10, and counting up, ``B``\ =11, so @@ -226,10 +225,10 @@ fourteen: 12×16\ :sup:`2` + 15×16\ :sup:`1` + 2×16\ :sup:`0` = 3314. U and L Suffixes ^^^^^^^^^^^^^^^^ -By default, an integer constant is treated as an :ref:`int -`, with the attendant :ref:`limitations in values -`. To specify an integer constant with another data -type, follow it with: +By default, an integer constant is treated as an :ref:`int ` +(and must be in the int type's :ref:`range limits +`). To specify an integer constant with another +data type, follow it with: - a ``u`` or ``U`` to interpret the constant as an unsigned value. For example, ``33U`` is an :ref:`unsigned int `. @@ -253,17 +252,12 @@ type, follow it with: Floating-Point Constants ------------------------ -Similar to integer literals, floating point constants (properly: -floating-point *literals*) are used to make code more readable. -Floating point literals are swapped at compile time for the value to -which the expression evaluates. - -A floating point literal is any number which includes a decimal point. -For instance, ``3.0`` is a floating-point literal for the number 3. -By default, a floating-point literal is a :ref:`double `. -In order for the literal to be interpreted as a :ref:`float -`, you can write ``f`` directly after it. For example, -``3.0f`` is a floating-point literal with type ``float``. +A floating point constant is any number which includes a decimal +point. For instance, ``3.0`` is a floating-point constant for the +number 3. By default, a floating-point constant is a :ref:`double +`. In order for the constant to be interpreted as a +:ref:`float `, you can write ``f`` directly after it. For +example, ``3.0f`` is a floating-point constant with type ``float``. Floating point constants can also be expressed in a variety of scientific notation. ``E`` and ``e`` are both accepted as valid @@ -273,7 +267,7 @@ exponent indicators. Some examples are given in the following table: .. list-table:: :header-rows: 1 - * - Floating-point literal + * - Floating-point constant - Evaluates to - Alternate expression @@ -297,8 +291,8 @@ Board-Specific Constants There are several :ref:`board-specific constants ` whose value depends on which LeafLabs board you have. If you use them, it will help make sure that your code will work well on all -LeafLabs boards, not just the one you have. This will make it much -easier to share your code with others. +LeafLabs boards, not just the one you have. This will make it easier +to share your code with others. For example, the pin number connected to the board's built-in LED is different on the different boards, but the board-specific constant -- cgit v1.2.3 From c10885c4b682ea91d700c257bd71dbeb204199ba Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 24 May 2011 22:43:29 -0400 Subject: Docs: fix and standardize Maple and RET6 hardware pages. Pick a standard layout for the information and fix mistakes. Looks like some of these errors were copy-pasted in from the old HTML documentation, some crept in due to API changes, and some were just wrong. I've checked all the claims against the datasheets and source code, so we should be in good shape now. --- source/hardware/maple-ret6.rst | 307 ++++++++++++++++++++++---------------- source/hardware/maple.rst | 331 ++++++++++++++++++++++++----------------- 2 files changed, 372 insertions(+), 266 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 9ee46d2..2f636d7 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -5,56 +5,60 @@ Maple RET6 Edition ================== +This page is a general resource for information specific to the Maple +RET6 Edition. The Maple RET6 Edition is a "beta" board released as a +simple way to get a more powerful chip than the one on the base Maple +(the STM32F103RET6, hence the name) in the hands of Maple developers. + .. contents:: Contents :local: +.. TODO [dma.rst] Ref to dma.rst in sequel instead of libmaple-dma +.. TODO [dac.rst] Ref to dac.rst in sequel instead of libmaple-dac +.. TODO [nvic.rst] Ref to nvic.rst in sequel + Technical Specifications ------------------------ - * MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor - * Clock Speed: **72 MHz** - * **512KB Flash** and **64KB SRAM** - * 43 Digital I/O Pins (:ref:`GPIO `) - * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC - `) - * Built-in, 2 channel **DAC** at 12 bit resolution - (:ref:`libmaple-dac`). - * 19 **PWM** pins at 16-bit resolution (:ref:`PWM `) - * Dedicated **USB** port for programming and communications - (:ref:`USB`) - * External **JTAG** interface (:ref:`JTAG `) - * 64 Channel nested vector interrupt handler (including - :ref:`external interrupt ` on GPIOs) - * Integrated **SPI** (:ref:`SPI `) - * Integrated **SDIO** - * Integrated **I2C** and **I2S** (:ref:`I2C `) - * 12 Channels of Direct Memory Access (**DMA**) - (:ref:`libmaple-dma`) - * 3 **USART** and 2 **UART** devices (:ref:`USART `) - * Two advanced control, four general purpose, two basic **timers** - (:ref:`timers`) - * Supplies up to 500mA @ 3.3v (with separate 250 mA digital and - analog regulators) - * Support for low power, sleep, and standby modes (<500uA) - * Operating Voltage: 3.3V - * Input Voltage (recommended): 3V-12V - * Dimensions are 2.05″x2.1″ +* MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor +* Clock Speed: **72 MHz** +* **512 KB Flash** and **64 KB SRAM** +* 43 Digital I/O Pins (:ref:`gpio`) +* 18 **PWM** pins at 16 bit resolution (:ref:`pwm`) +* 15 analog input pins, 12 bit **ADC** resolution (:ref:`adc`) +* Built-in, 2 channel **DAC** at 12 bit resolution (:ref:`libmaple-dac`). +* 2 **SPI** peripherals with **I2S** support (:ref:`spi`) +* 2 **I2C** peripherals (:ref:`i2c`) +* 12 Channels of Direct Memory Access (**DMA**) + (:ref:`libmaple-dma`) with 2 DMA controllers +* 3 **USART** devices (:ref:`usart`) +* 2 advanced, 4 general-purpose, and 2 basic **timers** (:ref:`timers`) +* Dedicated **USB** port for programming and communications (:ref:`usb`) +* **JTAG** (:ref:`jtag`) +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt ` on GPIOs) +* Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital + and analog regulators ` for low-noise analog + performance +* :ref:`Four layer design ` +* Support for low power, sleep, and standby modes (<500 μA) +* Operating Voltage: 3.3 V +* Input Voltage (recommended): 4 V — 12 V +* Dimensions are 2.05″ × 2.1″ .. _maple-ret6-powering: Powering the Maple RET6 Edition ------------------------------- -The Maple RET6 Edition's power source is determined by the header to -the left of the "LeafLabs" label on the silkscreen. The RET6 Edition -can be powered from the barrel jack connector, USB, or a LiPo battery. -We ship the RET6 Edition with a jumper on the USB selector. In order -to power it off of an alternative source, unplug the board, then move -the jumper to the desired selector before reconnecting power. +The Maple RET6 Edition is powered in the :ref:`same way as the +standard Maple `. -You can also power the Maple via the pin labeled "Vin" on the lower -header. However, don't do this while simultaneously powering the -board from another source, or you could damage the board. +.. warning:: The RET6 Edition silkscreen falsely indicates that the + barrel jack accepts up to 18 V. We recommend a barrel jack input + voltage **no greater than 12 V**. + + See :ref:`this erratum ` for more information. Using the Built-in Battery Charger ---------------------------------- @@ -84,7 +88,8 @@ It is thus mainly useful as an :ref:`input `. The pin will :ref:`read ` ``HIGH`` when the :ref:`button is pressed `. -More GPIOs (numbered ``D39``\ --``D42``) are available if you use the +More GPIOs (numbered ``D39``\ --``D42`` on the back of the RET6 +Edition's silkscreen) are available if you use the :ref:`lang-disabledebugports` function; see the :ref:`board-specific debug pin constants ` for more information. (See :ref:`this erratum ` for information about @@ -97,57 +102,58 @@ the pin numbered ``43`` on the silkscreen). Master Pin Map ^^^^^^^^^^^^^^ -This table shows the available functionality on every GPIO pin, by -peripheral type. The "STM32" column refers to the port and number that -the header is connected to on the microcontroller. The "5V?" column -documents whether or not the pin is 5 volt tolerant. +This table shows a summary of the available functionality on every +GPIO pin, by peripheral type. The "5 V?" column documents whether or +not the pin is 5 volt tolerant. .. csv-table:: - :header: Pin, STM32, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5v? - - D0, PA3, ADC3, TIM2_CH4, -, USART2_RX, -, - - D1, PA2, ADC2, TIM2_CH3, -, USART2_TX, -, - - D2, PA0, ADC0, TIM2_CH1_ETR, -, USART2_CTS, -, - - D3, PA1, ADC1, TIM2_CH2, -, USART2_RTS, -, - - D4, PB5, -, -, ISC1_SMBA, -, SPI3_MOSI, - - D5, PB6, -, TIM4_CH1, I2C1_SCL, -, -, Yes - D6, PA8, -, TIM1_CH1, -, USART1_CK, -, Yes - D7, PA9, -, TIM1_CH2, -, USART1_TX, -, Yes - D8, PA10, -, TIM1_CH3, -, USART1_RX, -, Yes - D9, PB7, -, TIM4_CH2, I2C1_SDA, -, -, Yes - D10, PA4, ADC4, -, -, USART2_CK, SPI1_NSS, - - D11, PA7, ADC7, TIM3_CH2, -, -, SPI1_MOSI, - - D12, PA6, ADC6, TIM3_CH1, -, -, SPI1_MISO, - - D13, PA5, ADC5, -, -, -, SPI1_SCK, - - D14, PB8, -, TIM4_CH3, -, -, -, Yes - D15, PC0, ADC10, -, -, -, -, - - D16, PC1, ADC11, -, -, -, -, - - D17, PC2, ADC12, -, -, -, -, - - D18, PC3, ADC13, -, -, -, -, - - D19, PC4, ADC14, -, -, -, -, - - D20, PC5, ADC15, -, -, -, -, - - D21, PC13, -, -, -, -, -, - - D22, PC14, -, -, -, -, -, - - D23, PC15, -, -, -, -, -, - - D24, PB9, -, TIM4_CH4, -, -, -, Yes - D25, PD2, -, TIM3_ETR, -, -, UART5_RX, Yes - D26, PC10, -, -, -, -, UART4_TX, Yes - D27, PB0, ADC8, TIM3_CH3, -, -, -, - - D28, PB1, ADC9, TIM3_CH4, -, -, -, - - D29, PB10, -, -, I2C2_SCL, USART3_TX, -, Yes - D30, PB11, -, -, I2C2_SDA, USART3_RX, -, Yes - D31, PB12, -, TIM1_BKIN, I2C2_SMBA, USART3_CK, SPI2_NSS, Yes - D32, PB13, -, TIM1_CH1N, -, USART3_CTS, SPI2_SCK, Yes - D33, PB14, -, TIM1_CH2N, -, USART3_RTS, SPI2_MISO, Yes - D34, PB15, -, TIM1_CH3N, -, -, SPI2_MOSI, Yes - D35, PC6, -, TIM8_CH1, -, -, -, Yes - D36, PC7, -, TIM8_CH2, -, -, -, Yes - D37, PC8, -, TIM8_CH3, -, -, -, Yes - D38, PC9, -, TIM8_CH4, -, -, -, Yes - D39, PA13, -, -, -, -, -, Yes - D40, PA14, -, -, -, -, -, Yes - D41, PA15, -, -, -, -, SPI3_NSS, Yes - D42, PB3, -, -, -, -, SPI3_SCK, Yes + :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART/USART `, :ref:`SPI `, 5 V? + + D0, PA3, CH3, 2_CH4, -, 2_RX, -, - + D1, PA2, CH2, 2_CH3, -, 2_TX, -, - + D2, PA0, CH0, 2_CH1_ETR, -, 2_CTS, -, - + D3, PA1, CH1, 2_CH2, -, 2_RTS, -, - + D4, PB5, -, -, 1_SMBA, -, 3_MOSI, - + D5, PB6, -, 4_CH1, 1_SCL, -, -, Yes + D6, PA8, -, 1_CH1, -, 1_CK, -, Yes + D7, PA9, -, 1_CH2, -, 1_TX, -, Yes + D8, PA10, -, 1_CH3, -, 1_RX, -, Yes + D9, PB7, -, 4_CH2, 1_SDA, -, -, Yes + D10, PA4, CH4, -, -, 2_CK, 1_NSS, - + D11, PA7, CH7, 3_CH2, -, -, 1_MOSI, - + D12, PA6, CH6, 3_CH1, -, -, 1_MISO, - + D13, PA5, CH5, -, -, -, 1_SCK, - + D14, PB8, -, 4_CH3, -, -, -, Yes + D15, PC0, CH10, -, -, -, -, - + D16, PC1, CH11, -, -, -, -, - + D17, PC2, CH12, -, -, -, -, - + D18, PC3, CH13, -, -, -, -, - + D19, PC4, CH14, -, -, -, -, - + D20, PC5, CH15, -, -, -, -, - + D21, PC13, -, -, -, -, -, - + D22, PC14, -, -, -, -, -, - + D23, PC15, -, -, -, -, -, - + D24, PB9, -, 4_CH4, -, -, -, Yes + D25, PD2, -, 3_ETR, -, -, 5_RX, Yes + D26, PC10, -, -, -, -, 4_TX, Yes + D27, PB0, CH8, 3_CH3, -, -, -, - + D28, PB1, CH9, 3_CH4, -, -, -, - + D29, PB10, -, -, 2_SCL, 3_TX, -, Yes + D30, PB11, -, -, 2_SDA, 3_RX, -, Yes + D31, PB12, -, 1_BKIN, 2_SMBA, 3_CK, 2_NSS, Yes + D32, PB13, -, 1_CH1N, -, 3_CTS, 2_SCK, Yes + D33, PB14, -, 1_CH2N, -, 3_RTS, 2_MISO, Yes + D34, PB15, -, 1_CH3N, -, -, 2_MOSI, Yes + D35, PC6, -, 8_CH1, -, -, -, Yes + D36, PC7, -, 8_CH2, -, -, -, Yes + D37, PC8, -, 8_CH3, -, -, -, Yes + D38, PC9, -, 8_CH4, -, -, -, Yes + D39, PA13, -, -, -, -, -, Yes + D40, PA14, -, -, -, -, -, Yes + D41, PA15, -, -, -, -, 3_NSS, Yes + D42, PB3, -, -, -, -, 3_SCK, Yes + +.. _maple-ret6-timer-map: Timer Pin Map ^^^^^^^^^^^^^ @@ -188,7 +194,7 @@ The following table shows which pins connect to which :ref:`EXTI lines * - EXTI2 - 1, 17, 25 * - EXTI3 - - 0, 18 + - 0, 18, 42 * - EXTI4 - 10, 19 * - EXTI5 @@ -208,11 +214,11 @@ The following table shows which pins connect to which :ref:`EXTI lines * - EXTI12 - 31 * - EXTI13 - - 21, 32 + - 21, 32, 39 * - EXTI14 - - 22, 33 + - 22, 33, 40 * - EXTI15 - - 23, 34 + - 23, 34, 41 .. _maple-ret6-usart-map: @@ -220,9 +226,8 @@ USART Pin Map ^^^^^^^^^^^^^ The Maple RET6 Edition has three serial ports whose pins are broken -out to headers (also known as a UARTs or USARTs): ``Serial1``, -``Serial2``, and ``Serial3``. They communicate using the pins -summarized in the following table: +out to headers (also known as :ref:`USARTs `). They communicate +using the pins summarized in the following table: .. csv-table:: :header: Serial Port, TX, RX, CK, CTS, RTS @@ -233,7 +238,18 @@ summarized in the following table: ``Serial3`` | 29 | 30 | 31 | 32 | 33 Unfortunately, :ref:`UART4 and UART5 aren't completely available -`. +`. + +.. _maple-ret6-adc-bank: + +Low-Noise ADC Pins +^^^^^^^^^^^^^^^^^^ + +The six pins at the bottom right of the board (D15—D20) generally +offer lower-noise ADC performance than other pins on the board. If +you’re concerned about getting good ADC readings, we recommend using +one of these pins to take your measurements. More details in the +:ref:`Maple hardware documentation `. Board-Specific Values --------------------- @@ -244,24 +260,28 @@ values `. - ``CYCLES_PER_MICROSECOND``: 72 - ``BOARD_BUTTON_PIN``: 38 - ``BOARD_LED_PIN``: 13 -- ``BOARD_NR_GPIO_PINS``: 44 -- ``BOARD_NR_PWM_PINS``: 16 -- ``boardPWMPins``: 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 25, 27, 28 +- ``BOARD_NR_GPIO_PINS``: 44 (however, :ref:`pin D43 is not usable + `) +- ``BOARD_NR_PWM_PINS``: 18 +- ``boardPWMPins``: 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 27, 28, + 35, 36, 37 - ``BOARD_NR_ADC_PINS``: 15 -- ``boardADCPins``: 0, 1, 2, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 +- ``boardADCPins``: 0, 1, 2, 3, 10, 11, 12, 15, 16, 17, 18, 19, 20, 27, 28 - ``BOARD_NR_USED_PINS``: 7 - ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN``, ``BOARD_JTMS_SWDIO_PIN``, ``BOARD_JTCK_SWCLK_PIN``, ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``, ``BOARD_NJTRST_PIN`` -- ``BOARD_NR_USARTS``: 3 (unfortunately, due to the Maple Rev 5 - design, UARTs 4 and 5 have pins which are not broken out) +- ``BOARD_NR_USARTS``: 3 (unfortunately, :ref:`due to the Maple Rev 5 + design `, UARTs 4 and 5 have pins which are not + broken out). - ``BOARD_USART1_TX_PIN``: 7 - ``BOARD_USART1_RX_PIN``: 8 - ``BOARD_USART2_TX_PIN``: 1 - ``BOARD_USART2_RX_PIN``: 0 - ``BOARD_USART3_TX_PIN``: 29 - ``BOARD_USART3_RX_PIN``: 30 -- ``BOARD_NR_SPI``: 3 +- ``BOARD_NR_SPI``: 2 (unfortunately, :ref:`due to the Maple Rev 5 + design `, SPI3 is unavailable). - ``BOARD_SPI1_NSS_PIN``: 10 - ``BOARD_SPI1_MOSI_PIN``: 11 - ``BOARD_SPI1_MISO_PIN``: 12 @@ -270,21 +290,19 @@ values `. - ``BOARD_SPI2_MOSI_PIN``: 34 - ``BOARD_SPI2_MISO_PIN``: 33 - ``BOARD_SPI2_SCK_PIN``: 32 -- ``BOARD_SPI3_NSS_PIN``: 41 -- ``BOARD_SPI3_MOSI_PIN``: 4 -- ``BOARD_SPI3_MISO_PIN``: 43 -- ``BOARD_SPI3_SCK_PIN``: 42 - ``BOARD_JTMS_SWDIO_PIN``: 39 - ``BOARD_JTCK_SWCLK_PIN``: 40 - ``BOARD_JTDI_PIN``: 41 - ``BOARD_JTDO_PIN``: 42 -- ``BOARD_NJTRST_PIN``: 43 +- ``BOARD_NJTRST_PIN``: :ref:`43 ` + +.. _maple-ret6-hardware: Hardware Design Files --------------------- The hardware schematics and board layout files are available in the -`Maple Github repository `_. Other +`Maple GitHub repository `_. Other than the processor used, the design files for the Maple RET6 edition are identical to the Maple Rev 5, which are in the ``maple-r5`` subdirectory of the Maple repository. A schematic for a JTAG adapter @@ -293,7 +311,7 @@ directory. From the GitHub repository main page, you can download the entire repository by clicking the "Download" button. If you are familiar -with `git `_, you can also clone the repository +with `Git `_, you can also clone the repository at the command line with :: $ git clone git://github.com/leaflabs/maple.git @@ -315,48 +333,81 @@ damage your board permanently. Errata ------ -This section lists known issues and warnings for the Maple RET6 Edition. +This section lists known issues and warnings for the Maple RET6 +Edition. Some of these are simply due to the RET6 Edition using the +Maple's circuit board, which was not designed to accomodate extra +features only available on the STM32F103RET6. -* **Power Supply Marketing Mistake**: We originally sold the Maple +.. _maple-ret6-barrel-jack: + +* **Barrel jack power supply voltage mistake**: The silkscreen next to + the barrel jack connector incorrectly indicates that up to an 18 V + input voltage is allowed. **We do not recommend exceeding 12 V**. + + See this :ref:`Maple erratum ` for more + information. + +* **Power supply marketing mistake**: We originally sold the Maple RET6 Edition advertising that it was capable of supplying up to 800 mA; the correct value is 500 mA. -.. _maple-ret6-uart-errata: +.. _maple-ret6-uarts: * **UART4, UART5 GPIOs unavailable**: Pins related to UARTs 4 and 5 are not broken out to headers (specifically, PC11/UART4_RX and - PC12/UART5_TX). The RET6 Edition's hardware layout is identical to - that of the Maple Rev 5, which wasn't designed for use with these - STM32F103RET6-only peripherals. + PC12/UART5_TX). This is due to the RET6 Edition's board layout + being that of the Maple Rev 5, which was not designed with these + RET6-specific features in mind. .. _maple-ret6-dac-ch2: * **DAC channel 2 on BOARD_LED_PIN**: The Maple Rev 5 connects PA5 to the board's built-in LED; this is the same GPIO bit which is connected to the DAC's channel 2 output. This is also due to the - RET6 Edition's board layout being copied from the base Maple Rev 5. + RET6 Edition's board layout being that of the Maple Rev 5. The DAC + output channel is still available, and (if you use libmaple) its + output is buffered by default, so this may not significantly + interfere with its functionality. .. _maple-ret6-nrst-pb4: * **Reset and PB4 tied together**: The RET6 Edition's reset line is also connected to PB4, which is labeled on the silkscreen as pin 43. - Thus, attempting to use pin 43 as a GPIO may reset your board. This + Thus, attempting to use pin 43 as a GPIO can reset your board. This has other implications. Since PB4 is also the JTAG NJTRST line, this prevents the :ref:`JTAG ` "reset halt" command from working properly. Also, since PB4 is SPI3_MISO, the SPI3 peripheral is not fully usable. +.. _maple-ret6-sdio: + +* **SDIO lines not broken out**: The RET6 Edition's SDIO peripheral is + not usable, as some of its data lines are either not broken out or + used for other purposes. This is also due to the RET6 Edition's + board layout being that of the Maple Rev 5. + +.. _maple-ret6-adc-led: + +* **ADC on BOARD_LED_PIN**: We originally sold the Maple RET6 Edition + advertising 16 analog input lines. However, one of them (the one on + pin 13) is also connected to the built-in LED. The voltage drop + across the LED means that the analog to digital converter on that + pin is not really useful. While it is still usable, its readings + will be incorrect. + Recommended Reading ------------------- -* STMicro documentation for STM32F103RE microcontroller: - - * `Datasheet - `_ (PDF) - * `Reference Manual - `_ (PDF) - * `Programming Manual - `_ - (PDF; assembly language and register reference) - * `ST's STM32F103RE reference page - `_ +STMicro documentation for STM32F103RE microcontroller: + +* `Datasheet + `_ + (PDF); covers STM32F103xC, STM32F103xD, STM32F103xE. +* `Reference Manual RM0008 + `_ + (PDF); general, definitive resource for STM32F1 line. +* `Programming Manual PM0056 + `_ + (PDF); assembly language and register reference. +* `STM32F103RE `_ + overview page with links to further references. diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index bb4bf35..b6950e0 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -5,36 +5,39 @@ Maple ===== +This page is a general resource for information specific to the Maple. + .. contents:: Contents :local: +.. TODO [dma.rst] Ref to dma.rst in sequel instead of libmaple-dma +.. TODO [nvic.rst] Ref to nvic.rst in sequel + Technical Specifications ------------------------ - * MCU: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor - * Clock Speed: **72 MHz** - * **128KB Flash** and **20KB SRAM** - * 43 Digital I/O Pins (:ref:`GPIO `) - * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC - `) - * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) - * Dedicated **USB** port for programming and communications - (:ref:`USB `) - * External **JTAG** interface (:ref:`JTAG `) - * 64 Channel nested vector interrupt handler (including - :ref:`external interrupt ` on GPIOs) - * Integrated **SPI** (:ref:`SPI `) - * Integrated **I2C** (:ref:`I2C `) - * 7 Channels of Direct Memory Access (**DMA**) - (:ref:`libmaple-dma`) - * 3 **USART** divices (:ref:`USART `) - * Four 4-channel **timers** (:ref:`Timers `) - * Supplies up to 500mA @ 3.3v (with separate 250 mA digital and - analog regulators) - * Support for low power, sleep, and standby modes (<500uA) - * Operating Voltage: 3.3V - * Input Voltage (recommended): 3V-12V - * Dimensions are 2.05″x2.1″ +* MCU: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor +* Clock Speed: **72 MHz** +* **128 KB Flash** and **20 KB SRAM** +* 43 Digital I/O Pins (:ref:`gpio`) +* 15 **PWM** pins at 16 bit resolution (:ref:`pwm`) +* 15 analog input pins, 12-bit **ADC** resolution (:ref:`adc`) +* 2 **SPI** peripherals (:ref:`spi`) +* 2 **I2C** peripherals (:ref:`i2c`) +* 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) +* 3 **USART** peripherals (:ref:`usart`) +* One advanced and three general-purpose **timers** (:ref:`timers`) +* Dedicated **USB** port for programming and communications (:ref:`usb`) +* **JTAG** (:ref:`jtag`) +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt ` on GPIOs) +* Supplies up to 500 mA at 3.3 V, with separate 250 mA digital and + analog regulators for low-noise analog performance +* :ref:`Four layer design ` +* Support for low power, sleep, and standby modes (<500 μA) +* Operating Voltage: 3.3 V +* Input Voltage (recommended): 4 V — 12 V +* Dimensions: 2.05″ × 2.1″ .. _maple-identify-rev: @@ -49,7 +52,7 @@ Rev. Rev 5 ^^^^^ -These boards went on sale in November 2010. They have white buttons, +These boards went on sale in November 2010. They have white buttons and "r5" in small print near the "LeafLabs Maple" text next to the "infinity leaf" logo. The Maple Rev 5 repositioned the double header on the right hand side to better fit 0.1 inch pitch breadboard. This @@ -96,8 +99,16 @@ it off of an alternative source, unplug the Maple, then move the jumper to the desired selector before reconnecting power. You can also power the Maple via the pin labeled "Vin" on the lower -header. However, don't do this while simultaneously powering the -Maple from another source, or you could damage the board. +header. This pin feeds into both the digital and analog voltage +regulators. However, don't do this while simultaneously powering the +board from another source, or you could damage it. + +.. warning:: Silkscreens on Maples up through Rev 5s manufactured in + Spring 2011 falsely indicated that the barrel jack could be + supplied by up to 18 V. We recommend a barrel jack input voltage + **no greater than 12 V**. + + See :ref:`this erratum ` for more information. Using the Built-in Battery Charger ---------------------------------- @@ -127,11 +138,12 @@ It is thus mainly useful as an :ref:`input `. The pin will :ref:`read ` ``HIGH`` when the :ref:`button is pressed `. -More GPIOs (numbered ``D39``\ --``D42``) are available if you use the -:ref:`lang-disabledebugports` function; see the :ref:`board-specific -debug pin constants ` for more information. -(See :ref:`this erratum ` for information about the -pin numbered ``43`` on the silkscreen). +More GPIOs (numbered ``D39``\ --``D42`` on the back of the Maple's +silkscreen) are available if you use the :ref:`lang-disabledebugports` +function; see the :ref:`board-specific debug pin constants +` for more information. (See :ref:`this +erratum ` for information about the pin numbered +``43`` on the silkscreen). .. TODO [0.1.0] silkscreen pictures which expand abbreviations @@ -140,57 +152,58 @@ pin numbered ``43`` on the silkscreen). Master Pin Map ^^^^^^^^^^^^^^ -This table shows the available functionality on every GPIO pin, by -peripheral type. The "STM32" column refers to the port and number that -the header is connected to on the microcontroller. The "5V?" column -documents whether or not the pin is 5 volt tolerant. +This table shows a summary of the available functionality on every +GPIO pin, by peripheral type. The "5 V?" column documents whether or +not the pin is 5 volt tolerant. .. csv-table:: - :header: Pin, STM32, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5v? - - D0, PA3, ADC3, TIM2_CH4, -, USART2_RX, -, - - D1, PA2, ADC2, TIM2_CH3, -, USART2_TX, -, - - D2, PA0, ADC0, TIM2_CH1_ETR, -, USART2_CTS, -, - - D3, PA1, ADC1, TIM2_CH2, -, USART2_RTS, -, - - D4, PB5, -, -, ISC1_SMBA, -, -, - - D5, PB6, -, TIM4_CH1, I2C1_SCL, -, -, Yes - D6, PA8, -, TIM1_CH1, -, USART1_CK, -, Yes - D7, PA9, -, TIM1_CH2, -, USART1_TX, -, Yes - D8, PA10, -, TIM1_CH3, -, USART1_RX, -, Yes - D9, PB7, -, TIM4_CH2, I2C1_SDA, -, -, Yes - D10, PA4, ADC4, -, -, USART2_CK, SPI1_NSS, - - D11, PA7, ADC7, TIM3_CH2, -, -, SPI1_MOSI, - - D12, PA6, ADC6, TIM3_CH1, -, -, SPI1_MISO, - - D13, PA5, ADC5, -, -, -, SPI1_SCK, - - D14, PB8, -, TIM4_CH3, -, -, -, Yes - D15, PC0, ADC10, -, -, -, -, - - D16, PC1, ADC11, -, -, -, -, - - D17, PC2, ADC12, -, -, -, -, - - D18, PC3, ADC13, -, -, -, -, - - D19, PC4, ADC14, -, -, -, -, - - D20, PC5, ADC15, -, -, -, -, - - D21, PC13, -, -, -, -, -, - - D22, PC14, -, -, -, -, -, - - D23, PC15, -, -, -, -, -, - - D24, PB9, -, TIM4_CH4, -, -, -, Yes - D25, PD2, -, TIM3_ETR, -, -, -, Yes - D26, PC10, -, -, -, -, -, Yes - D27, PB0, ADC8, TIM3_CH3, -, -, -, - - D28, PB1, ADC9, TIM3_CH4, -, -, -, - - D29, PB10, -, -, I2C2_SCL, USART3_TX, -, Yes - D30, PB11, -, -, I2C2_SDA, USART3_RX, -, Yes - D31, PB12, -, TIM1_BKIN, I2C2_SMBA, USART3_CK, SPI2_NSS, Yes - D32, PB13, -, TIM1_CH1N, -, USART3_CTS, SPI2_SCK, Yes - D33, PB14, -, TIM1_CH2N, -, USART3_RTS, SPI2_MISO, Yes - D34, PB15, -, TIM1_CH3N, -, -, SPI2_MOSI, Yes - D35, PC6, -, -, -, -, -, Yes - D36, PC7, -, -, -, -, -, Yes - D37, PC8, -, -, -, -, -, Yes - D38, PC9, -, -, -, -, -, Yes - D39, PA13, -, -, -, -, -, Yes - D40, PA14, -, -, -, -, -, Yes - D41, PA15, -, -, -, -, -, Yes - D42, PB3, -, -, -, -, -, Yes + :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? + + D0, PA3, CH3, 2_CH4, -, 2_RX, -, - + D1, PA2, CH2, 2_CH3, -, 2_TX, -, - + D2, PA0, CH0, 2_CH1_ETR, -, 2_CTS, -, - + D3, PA1, CH1, 2_CH2, -, 2_RTS, -, - + D4, PB5, -, -, 1_SMBA, -, -, - + D5, PB6, -, 4_CH1, 1_SCL, -, -, Yes + D6, PA8, -, 1_CH1, -, 1_CK, -, Yes + D7, PA9, -, 1_CH2, -, 1_TX, -, Yes + D8, PA10, -, 1_CH3, -, 1_RX, -, Yes + D9, PB7, -, 4_CH2, 1_SDA, -, -, Yes + D10, PA4, CH4, -, -, 2_CK, 1_NSS, - + D11, PA7, CH7, 3_CH2, -, -, 1_MOSI, - + D12, PA6, CH6, 3_CH1, -, -, 1_MISO, - + D13, PA5, CH5, -, -, -, 1_SCK, - + D14, PB8, -, 4_CH3, -, -, -, Yes + D15, PC0, CH10, -, -, -, -, - + D16, PC1, CH11, -, -, -, -, - + D17, PC2, CH12, -, -, -, -, - + D18, PC3, CH13, -, -, -, -, - + D19, PC4, CH14, -, -, -, -, - + D20, PC5, CH15, -, -, -, -, - + D21, PC13, -, -, -, -, -, - + D22, PC14, -, -, -, -, -, - + D23, PC15, -, -, -, -, -, - + D24, PB9, -, 4_CH4, -, -, -, Yes + D25, PD2, -, 3_ETR, -, -, -, Yes + D26, PC10, -, -, -, -, -, Yes + D27, PB0, CH8, 3_CH3, -, -, -, - + D28, PB1, CH9, 3_CH4, -, -, -, - + D29, PB10, -, -, 2_SCL, 3_TX, -, Yes + D30, PB11, -, -, 2_SDA, 3_RX, -, Yes + D31, PB12, -, -, 2_SMBA, 3_CK, 2_NSS, Yes + D32, PB13, -, -, -, 3_CTS, 2_SCK, Yes + D33, PB14, -, -, -, 3_RTS, 2_MISO, Yes + D34, PB15, -, -, -, -, 2_MOSI, Yes + D35, PC6, -, -, -, -, -, Yes + D36, PC7, -, -, -, -, -, Yes + D37, PC8, -, -, -, -, -, Yes + D38, PC9, -, -, -, -, -, Yes + D39, PA13, -, -, -, -, -, Yes + D40, PA14, -, -, -, -, -, Yes + D41, PA15, -, -, -, -, -, Yes + D42, PB3, -, -, -, -, -, Yes + +.. _maple-timer-map: Timer Pin Map ^^^^^^^^^^^^^ @@ -228,7 +241,7 @@ The following table shows which pins connect to which :ref:`EXTI lines * - EXTI2 - 1, 17, 25 * - EXTI3 - - 0, 18 + - 0, 18, 42 * - EXTI4 - 10, 19 * - EXTI5 @@ -248,20 +261,20 @@ The following table shows which pins connect to which :ref:`EXTI lines * - EXTI12 - 31 * - EXTI13 - - 21, 32 + - 21, 32, 39 * - EXTI14 - - 22, 33 + - 22, 33, 40 * - EXTI15 - - 23, 34 + - 23, 34, 41 .. _maple-usart-map: USART Pin Map ^^^^^^^^^^^^^ -The Maple has three serial ports (also known as a UARTs or USARTs): -``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the -pins summarized in the following table: +The Maple has three serial ports (also known as USARTs): ``Serial1``, +``Serial2``, and ``Serial3``. They communicate using the pins +summarized in the following table: .. csv-table:: :header: Serial Port, TX, RX, CK, CTS, RTS @@ -271,6 +284,24 @@ pins summarized in the following table: ``Serial2`` | 1 | 0 | 10 | 2 | 3 ``Serial3`` | 29 | 30 | 31 | 32 | 33 +.. _maple-adc-bank: + +Low-Noise ADC Pins +^^^^^^^^^^^^^^^^^^ + +The six pins at the bottom right of the board (D15—D20) generally +offer lower-noise ADC performance than other pins on the board. If +you’re concerned about getting good ADC readings, we recommend using +one of these pins to take your measurements. + +Maple has an electrically isolated analog power plane with its own +regulator, and a geometrically isolated ground plane. Pins D15—D20 are +laid out to correspond with these analog planes, and our measurements +indicate that they generally have the lowest noise of all the analog +lines. However, analog performance may vary depending upon the +activity of the other GPIOs. Consult the :ref:`Maple hardware design +files ` for more details. + Board-Specific Values --------------------- @@ -280,11 +311,12 @@ This section lists the Maple's :ref:`board-specific values - ``CYCLES_PER_MICROSECOND``: 72 - ``BOARD_BUTTON_PIN``: 38 - ``BOARD_LED_PIN``: 13 -- ``BOARD_NR_GPIO_PINS``: 44 -- ``BOARD_NR_PWM_PINS``: 16 -- ``boardPWMPins``: 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 25, 27, 28 +- ``BOARD_NR_GPIO_PINS``: 44 (however, :ref:`pin D43 is not usable + `) +- ``BOARD_NR_PWM_PINS``: 15 +- ``boardPWMPins``: 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 27, 28 - ``BOARD_NR_ADC_PINS``: 15 -- ``boardADCPins``: 0, 1, 2, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 +- ``boardADCPins``: 0, 1, 2, 3, 10, 11, 12, 15, 16, 17, 18, 19, 20, 27, 28 - ``BOARD_NR_USED_PINS``: 7 - ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN``, ``BOARD_JTMS_SWDIO_PIN``, ``BOARD_JTCK_SWCLK_PIN``, @@ -309,13 +341,15 @@ This section lists the Maple's :ref:`board-specific values - ``BOARD_JTCK_SWCLK_PIN``: 40 - ``BOARD_JTDI_PIN``: 41 - ``BOARD_JTDO_PIN``: 42 -- ``BOARD_NJTRST_PIN``: 43 +- ``BOARD_NJTRST_PIN``: :ref:`43 ` + +.. _maple-hardware: Hardware Design Files --------------------- The hardware schematics and board layout files are available in the -`Maple Github repository `_. The +`Maple GitHub repository `_. The design files for Rev 1, Rev 3, and Rev 5 are respectively in the ``maple-r1``, ``maple-r3``, and ``maple-r5`` subdirectories. A schematic for a JTAG adapter suitable for use with Maple is available @@ -323,7 +357,7 @@ in the ``jtagadapter`` directory. From the GitHub repository main page, you can download the entire repository by clicking the "Download" button. If you are familiar -with `git `_, you can also clone the repository +with `Git `_, you can also clone the repository at the command line with :: $ git clone git://github.com/leaflabs/maple.git @@ -340,18 +374,66 @@ permanently. * **High voltage on non-tolerant pins**: not all header pins are 5V compatible; so e.g. connecting certain serial devices in the wrong way could over-voltage the pins. The :ref:`pin-mapping master table - ` details which pins are 5V-tolerant. + ` details which pins are 5 V tolerant. Errata ------ +This section documents design flaws and other errors. + General ^^^^^^^ -* **Power Supply Marketing Mistake**: We originally sold the Maple +.. _maple-barrel-jack: + +* **Barrel jack power supply voltage mistake**: The acceptable voltage + range given next to the barrel jack on the Maple through Rev 5s + manufactured in Spring 2011 is **incorrect**. The given range is 7 + V — 18 V. In fact, **18 V is too high** and should not be supplied + to your board. The recommended maximum voltage you should apply is + **12 V**. + + The original voltage regulators used on the Maple were rated up to + 18 V. However, the voltage regulators on current Maple Revs are + rated up to 16 V. Our tests indicate that they operate correctly + through 12 V. We do not recommend higher input voltages. + +.. _maple-nrst-pb4: + +* **Reset and PB4 tied together**: The Maple's reset line is also + connected to PB4, which is labeled on the silkscreen as pin 43. + Thus, attempting to use pin 43 as a GPIO can reset your board. This + has other implications. Since PB4 is also the JTAG NJTRST line, + this prevents the :ref:`JTAG ` "reset halt" command from + working properly. + +.. _maple-power-supply: + +* **Power supply marketing mistake**: We originally sold the Maple advertising that it was capable of supplying up to 800 mA; the correct value is 500 mA. +.. _maple-pwm-marketing: + +* **PWM marketing mistake**: We originally advertised the Maple as + having 22 PWM-capable pins; the correct number is 15. + +.. _maple-adc-marketing: + +* **ADC marketing mistake**: We originally advertised the Maple as + having 16 analog input pins. Due to :ref:`the following issue + `, the correct number is 15. + +.. _maple-adc-led: + +* **ADC on BOARD_LED_PIN**: We originally sold the Maple RET6 Edition + advertising 16 analog input lines. However, one of them (the one on + pin 13) is also connected to the built-in LED. The voltage drop + across the LED means that the analog to digital converter on that + pin is not really useful. While it is still usable, its readings + will be incorrect. + + By Rev ^^^^^^ @@ -366,15 +448,6 @@ Rev 5 from its silkscreen. This mistake was fixed in later manufacturing runs. -.. _maple-nrst-pb4: - -* **Reset and PB4 tied together**: The Maple's reset line is also - connected to PB4, which is labeled on the silkscreen as pin 43. - Thus, attempting to use pin 43 as a GPIO may reset your board. This - has other implications. Since PB4 is also the JTAG NJTRST line, - this prevents the :ref:`JTAG ` "reset halt" command from - working properly. - Rev 3 ~~~~~ @@ -417,16 +490,6 @@ Rev 3 number 38 (actually 38 is connected to the BUT button). We manually sharpied over both of these mistakes. -* **PWM Marketing Mistake**: We originally sold the Maple advertising - 22 channels of 16-bit hardware PWM; actually the Maple only has 15. - -* **Reset and NJTRST tied together**: The MCU's reset pin is tied to - PB4, the NJTRST pin, which is pin 43. Thus, attempting to use pin - 43 as a GPIO will reset your board (and also prevents the JTAG - "reset halt") command from working properly. It's possible to cut - the trace, but doing so will damage your board, so we *do not - recommend it* unless you're very sure about what you're doing. - Rev 1 ~~~~~ @@ -435,7 +498,7 @@ Rev 1 connected to a computer). This issue was resolved in Rev 3 with a 4-layer design and a - geometrically isolated ADC V\ :sub:`ref` plane. + :ref:`geometrically isolated ADC Vref plane `. * **Resistors on pins 0 and 1**: these header pins, which are RX/TX on USART2 (:ref:`Serial2 `), have resistors in-line @@ -458,30 +521,22 @@ Rev 1 appropriate MCU pin to Vcc; see `this forum posting `_. -* **PWM Marketing Mistake**: We originally sold the Maple advertising - 22 channels of 16-bit hardware PWM; the correct number is 15. - -* **Reset and NJTRST tied together**: The MCU's reset pin is tied to - PB4, the NJTRST pin, which is pin 43. Thus, attempting to use pin - 43 as a GPIO will reset your board (and also prevents the JTAG - "reset halt") command from working properly. It's possible to cut - the trace, but doing so will damage your board, so we *do not - recommend it* unless you're very sure about what you're doing. - Recommended Reading ------------------- -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet - `_ - (PDF) - * `Reference Manual - `_ - (PDF) - * `Programming Manual - `_ - (PDF; assembly language and register reference) +STMicro documentation for STM32F103RB microcontroller: + +* `Datasheet + `_ + (PDF); covers STM32F103x8, STM32F103xB. +* `Reference Manual RM0008 + `_ + (PDF); general, definitive resource for STM32F1 line. +* `Programming Manual PM0056 + `_ + (PDF); assembly language and register reference. +* `STM32F103RB `_ + overview page with links to further references. .. rubric:: Footnotes -- cgit v1.2.3 From 6432343170fc6f7d24e75220948c5d4c38394476 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 25 May 2011 01:14:33 -0400 Subject: Docs: Add Maple Mini information Flesh out and uncomment maple-mini.rst. Add links to pieces of it in various appropriate places throughout the rest of the documentation. --- source/adc.rst | 53 ++++--- source/external-interrupts.rst | 9 +- source/gpio.rst | 6 +- source/hardware/maple-mini.rst | 342 +++++++++++++++++++++++++++++++++++++++- source/index.rst | 6 +- source/lang/api/hardwarespi.rst | 2 +- source/timers.rst | 16 +- source/usart.rst | 4 +- 8 files changed, 396 insertions(+), 42 deletions(-) diff --git a/source/adc.rst b/source/adc.rst index f3d5f55..a749201 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -20,31 +20,42 @@ number of techniques must be used to get good precision and accuracy. Noise and Bias -------------- -.. FIXME [0.0.11, Maple form factor-specific] - -The biggest issues with analog-digital conversion are noise and bias. -With the Maple, we have tried to isolate the ADC pins and traces from -strong noise sources, but there are always trade--offs between noise, -additional functionality, cost, and package size. - -The 6 ADC pins in a bank (D15--D20) generally have the least -noise, and should be used for fine measurements. If the input voltage -changes relatively slowly, a number of samples can be taken in -succession and averaged together, or the same voltage can even be -sampled by multiple ADC pins at the same time. - -An important factor when taking a voltage reading is the reference -voltages that the sample is being compared against. In the case of the -Maple, the high reference is |vcc| and the low reference is ground. -This means that noise or fluctuations on either |vcc| or ground will -affect the measurement. It also means that the voltage you are trying -to sample must be between ground and 3.3V. +.. FIXME [0.0.12, Maple Native] + +The biggest issues with analog to digital conversion are noise and +bias. With the Maple line, we have tried to isolate the ADC pins and +traces from strong noise sources, but there are always trade-offs +between noise, additional functionality, cost, and package size. +We've tried to enable good analog performance by isolating as many ADC +pins as possible from digital noise on each board. + +More information on these isolated pins is available in each board's +hardware documentation: + +* :ref:`Maple ` +* :ref:`Maple RET6 Edition ` +* :ref:`Maple Mini ` + +.. :ref:`Maple Native ` + +That said, there are a number of more general things you can do to try +to get good readings. If your input voltage changes relatively +slowly, a number of samples can be taken in succession and averaged +together, or the same voltage can even be sampled by multiple ADC pins +at the same time. + +Another important factor when taking a voltage reading is the +reference voltages that the sample is being compared against. In the +case of the Maple, the high reference is |vcc| and the low reference +is ground. This means that noise or fluctuations on either |vcc| or +ground will affect the measurement. It also means that the voltage you +are trying to sample must be between ground and 3.3 V. .. _adc-range: In the case of a variable reading, it is best if the voltage varies -over the entire range of 0--3.3V; otherwise, only a fraction of the -sensitivity is being leveraged. Some basic tools to accomplish this +over the entire range of 0 through 3.3 V; otherwise, only a fraction +of the sensitivity is being used. Some basic tools to accomplish this are `resistor dividers `_ and `Zener diodes `_\ diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index ac065a4..ccb9afd 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -37,17 +37,20 @@ means that every pin on the Maple connects to what is called an *EXTI line*, and within an EXTI line, only one of the pins that connects to it can be used to detect external interrupts at a time. +.. TODO [0.0.12] Maple Native links + The EXTI Line Pin Map for your board lists which pins connect to which EXTI lines: * :ref:`Maple ` * :ref:`Maple RET6 Edition ` +* :ref:`Maple Mini ` .. note:: - You should set the :ref:`pin mode ` of your - desired pin to an input mode (e.g ``INPUT`` or ``INPUT_FLOATING``, - ``INPUT_PULLUP``, ``INPUT_PULLDOWN``). + You should set the :ref:`pin mode ` of your desired + pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``, + ``INPUT_PULLDOWN``). Function Reference ------------------ diff --git a/source/gpio.rst b/source/gpio.rst index 74be3d4..64ad494 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -20,19 +20,19 @@ Pin Maps The hardware documentation for your board lists each pin's capabilities, by pin number: -.. TODO [0.1.0] Uncomment Mini and Native GPIO links +.. TODO [0.0.12] Native link * :ref:`Maple ` * :ref:`Maple RET6 Edition ` +* :ref:`Maple Mini ` -.. * :ref:`Maple Mini ` .. * :ref:`Maple Native ` The current and voltage limitations were determined using the STM32 datasheets. In particular, only some GPIO pins are **5V tolerant**, which means that applying 5 volts to a pin and reading it as input or allowing it to drain to ground will not damage that pin. Connecting a -voltage higher than 3.3V to a non-5V tolerant pin may damage your +voltage higher than 3.3 V to a non-5 V tolerant pin may damage your board. .. _gpio-modes: diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index a8a4186..3e79ed0 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -1,6 +1,344 @@ -.. _hardware-maple-mini: +.. _maple-mini: Maple Mini ========== -Stub. +This page is a general resource for information specific to the Maple +Mini. The Maple Mini is a smaller version of the Maple that fits on a +breadboard. + +.. contents:: Contents + :local: + +.. TODO [dma.rst] Ref to dma.rst in sequel instead of libmaple-dma + +Technical Specifications +------------------------ + +* MCU: **STM32F103RCBT6**, a 32-bit ARM Cortex M3 microprocessor +* Clock Speed: **72 MHz** +* **128 KB Flash** and **20 KB SRAM** +* 34 Digital I/O Pins (:ref:`gpio`) +* 12 **PWM** pins at 16 bit resolution (:ref:`pwm`) +* 9 analog input pins, 12 bit **ADC** resolution (:ref:`adc`) +* 2 **SPI** peripherals (:ref:`spi`) +* 2 **I2C** peripherals (:ref:`i2c`) +* 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) +* 3 **USART** peripherals (:ref:`usart`) +* 1 advanced and 3 general-purpose **timers** (:ref:`timers`) +* Dedicated **USB** port for programming and communications (:ref:`usb`) +* **JTAG** (:ref:`jtag`) +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt ` on GPIOs) +* Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital + and analog regulators ` for low-noise analog + performance +* :ref:`Four layer design ` +* Support for low power, sleep, and standby modes (<500 μA) +* Operating Voltage: 3.3 V +* Input Voltage (recommended): 3 V — 12 V +* Dimensions: 2.02″ × 0.72″ + +.. _maple-mini-powering: + +Powering the Maple Mini +----------------------- + +You can power the Maple Mini via the USB plug or by powering Vin +directly. + +.. warning:: The silkscreen on the Maple Mini suggests it will accept + an input voltage up to 16 V. We recommend applying **no greater + than 12 V**. + + See :ref:`this erratum ` for more information. + +.. _maple-mini-gpios: + +GPIO Information +---------------- + +The Maple Mini features 34 total input/output pins, numbered ``D0`` +through ``D33``. These numbers correspond to the numeric values next +to each header on the Maple Mini's silkscreen. However, some of them +have special uses by default [#fusedpins]_. + +.. _maple-mini-usb-pins: + +Pin ``D23`` is the :ref:`USB ` D+ line, and ``D24`` is the USB D- +line. To use them as GPIOs, your program will need to :ref:`disable +SerialUSB ` first. Be aware, however, that +disabling SerialUSB means that the :ref:`bootloader ` +won't work properly, and you'll need to use +:ref:`troubleshooting-perpetual-bootloader` to make your next upload. + +.. _maple-mini-but: + +Pin ``D32`` is the Mini's :ref:`button pin `. +It is thus mainly useful as an :ref:`input `. The +pin will :ref:`read ` ``HIGH`` when the :ref:`button +is pressed `. + +.. _maple-mini-led: + +Pin ``D33`` is the Mini's :ref:`LED pin `. It +is thus mainly useful as an :ref:`output `. The LED +will glow when ``HIGH`` is :ref:`written ` to it. +(It also supports :ref:`pwm`, for finer-grained brightness control). + +.. TODO [0.1.0] silkscreen pictures which expand abbreviations + +.. _maple-mini-pin-map-master: + +Master Pin Map +^^^^^^^^^^^^^^ + +This table shows a summary the available functionality on every GPIO +pin, by peripheral type. The "5 V?" column documents whether or not +the pin is 5 volt tolerant. + +.. csv-table:: + :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? + + D0, PB11, -, -, 2_SDA, 3_RX, -, Yes + D1, PB10, -, -, 2_SCL, 3_TX, -, Yes + D2, PB2, -, -, -, -, -, Yes + D3, PB0, CH8, 3_CH3, -, -, -, - + D4, PA7, CH7, 3_CH2, -, -, 1_MOSI, - + D5, PA6, CH6, 3_CH1, -, -, 1_MISO, - + D6, PA5, CH5, -, -, -, 1_SCK, - + D7, PA4, CH4, -, -, 2_CK, 1_NSS, - + D8, PA3, CH3, 2_CH4, -, 2_RX, -, - + D9, PA2, CH2, 2_CH3, -, 2_TX, -, - + D10, PA1, CH1, 2_CH2, -, 2_RTS, -, - + D11, PA0, CH0, 2_CH1_ETR, -, 2_CTS, -, - + D12, PC15, -, -, -, -, -, - + D13, PC14, -, -, -, -, -, - + D14, PC13, -, -, -, -, -, - + D15, PB7, -, 4_CH2, 1_SDA, -, -, Yes + D16, PB6, -, 4_CH1, 2_SCL, -, -, Yes + D17, PB5, -, -, 1_SMBA, -, -, - + D18, PB4, -, -, -, -, -, Yes + D19, PB3, -, -, -, -, -, Yes + D20, PA15, -, -, -, -, -, Yes + D21, PA14, -, -, -, -, -, Yes + D22, PA13, -, -, -, -, -, Yes + D23, PA12, -, 1_ETR, -, 1_RTS, -, Yes + D24, PA11, -, 1_CH4, -, 1_CTS, -, Yes + D25, PA10, -, 1_CH3, -, 1_RX, -, Yes + D26, PA9, -, 1_CH2, -, 1_TX, -, Yes + D27, PA8, -, 1_CH1, -, 1_CK, -, Yes + D28, PB15, -, -, -, -, 2_MOSI, Yes + D29, PB14, -, -, -, 3_RTS, 2_MISO, Yes + D30, PB13, -, -, -, 3_CTS, 2_SCK, Yes + D31, PB12, -, 1_BKIN, 2_SMBA, 3_CK, 2_NSS, Yes + D32, PB8, -, 4_CH3, -, -, -, Yes + D33, PB1, CH9, 3_CH4, -, -, -, - + +.. _maple-mini-timer-map: + +Timer Pin Map +^^^^^^^^^^^^^ + +The following table shows what pins are associated with a particular +timer's capture/compare channels. + +.. csv-table:: + :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4 + :delim: | + + 1 | D27 | D26 | D25 | D24 + 2 | D11 | D10 | D9 | D8 + 3 | D5 | D4 | D3 | :ref:`D33 ` + 4 | D16 | D15 | :ref:`D32 ` | + +.. _maple-mini-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +` on the Maple. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - 3, 11 + * - EXTI1 + - 10, 33 + * - EXTI2 + - 2, 9 + * - EXTI3 + - 8, 19 + * - EXTI4 + - 7, 18 + * - EXTI5 + - 6, 17 + * - EXTI6 + - 5, 16 + * - EXTI7 + - 4, 15 + * - EXTI8 + - 27, 32 + * - EXTI9 + - 26 + * - EXTI10 + - 1, 25 + * - EXTI11 + - 0, 24 + * - EXTI12 + - 23, 31 + * - EXTI13 + - 14, 22, 30 + * - EXTI14 + - 13, 21, 29 + * - EXTI15 + - 12, 20, 28 + +.. _maple-mini-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +The Maple RET6 Edition has three serial ports whose pins are broken +out to headers (also known as :ref:`USARTs `). They communicate +using the pins summarized in the following table: + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | 26 | 25 | 27 | 24 | 23 + ``Serial2`` | 9 | 8 | 7 | 11 | 10 + ``Serial3`` | 1 | 0 | 31 | 30 | 29 + +.. _maple-mini-adc-bank: + +Low-Noise ADC Pins +^^^^^^^^^^^^^^^^^^ + +Analog input pins D4 — D11 on the Maple Mini generally offer +lower-noise ADC performance than D3. If you’re concerned about +getting good ADC readings, we recommend using one of these pins to +take your measurements. + +Maple Mini has an electrically isolated analog power plane with its +own regulator, and a geometrically isolated ground plane, connected to +the digital plane by an inductor. Pins D4 — D11 are laid out to +correspond with these analog planes, and our measurements indicate +that they generally have the lowest noise of all the analog lines. +However, analog performance may vary depending upon the activity of +the other GPIOs. Consult the :ref:`Maple Mini hardware design files +` for more details. + +.. _maple-mini-board-values: + +Board-Specific Values +--------------------- + +This section lists the Maple Mini's :ref:`board-specific values +`. + +- ``CYCLES_PER_MICROSECOND``: 72 +- ``BOARD_BUTTON_PIN``: 32 +- ``BOARD_LED_PIN``: 33 +- ``BOARD_NR_GPIO_PINS``: 34 +- ``BOARD_NR_PWM_PINS``: 12 +- ``boardPWMPins``: 3, 4, 5, 8, 9, 10, 11, 15, 16, 25, 26, 27 +- ``BOARD_NR_ADC_PINS``: 9 +- ``boardADCPins``: 3, 4, 5, 6, 7, 8, 9, 10, 11 +- ``BOARD_NR_USED_PINS``: 4 +- ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN``, 23, 24 + (23 and 24 are used by :ref:`USB `) +- ``BOARD_NR_USARTS``: 3 +- ``BOARD_USART1_TX_PIN``: 26 +- ``BOARD_USART1_RX_PIN``: 25 +- ``BOARD_USART2_TX_PIN``: 9 +- ``BOARD_USART2_RX_PIN``: 8 +- ``BOARD_USART3_TX_PIN``: 1 +- ``BOARD_USART3_RX_PIN``: 0 +- ``BOARD_NR_SPI``: 2 +- ``BOARD_SPI1_NSS_PIN``: 7 +- ``BOARD_SPI1_MOSI_PIN``: 4 +- ``BOARD_SPI1_MISO_PIN``: 5 +- ``BOARD_SPI1_SCK_PIN``: 6 +- ``BOARD_SPI2_NSS_PIN``: 31 +- ``BOARD_SPI2_MOSI_PIN``: 28 +- ``BOARD_SPI2_MISO_PIN``: 29 +- ``BOARD_SPI2_SCK_PIN``: 30 +- ``BOARD_JTMS_SWDIO_PIN``: 22 +- ``BOARD_JTCK_SWCLK_PIN``: 21 +- ``BOARD_JTDI_PIN``: 20 +- ``BOARD_JTDO_PIN``: 19 +- ``BOARD_NJTRST_PIN``: 18 + +.. _maple-mini-hardware: + +Hardware Design Files +--------------------- + +The hardware schematics and board layout files are available in the +`Maple Mini GitHub repository `_ + +From the GitHub repository main page, you can download the entire +repository by clicking the "Download" button. If you are familiar +with `Git `_, you can also clone the repository +at the command line with :: + + $ git clone git://github.com/leaflabs/maplemini.git + +Failure Modes +------------- + +The following known failure modes apply to all Maple boards. The +failure modes aren't design errors, but are easy ways to break or +damage your board permanently. + +* **High voltage on non-tolerant pins**: not all header pins are 5 V + compatible; so e.g. connecting certain serial devices in the wrong + way could over-voltage the pins. The :ref:`pin-mapping master table + ` details which pins are 5 V-tolerant. + +Errata +------ + +This section lists known issues and warnings for the Maple Mini Rev 2 +(the first Rev sold to the public). + +.. _maple-mini-vin: + +* **Silkscreen Vin voltage mistake**: The silkscreen on the Maple Mini + falsely indicates that Vin may be supplied with up to 16 V. We + recommend an input voltage **no greater than 12 V**. + + The voltage regulator on the Mini is rated up to 16 V. However, our + tests indicate that as its input voltage approaches 16 V, its output + begins to rise to levels higher than those recommended by ST for + supplying the STM32F103CB. The limit of 12 V keeps the voltage + supplied to the processor at safe levels. + +Recommended Reading +------------------- + +STMicro documentation for STM32F103CB microcontroller: + +* `Datasheet + `_ + (PDF); covers STM32F103x8, STM32F103xB. +* `Reference Manual RM0008 + `_ + (PDF); general, definitive resource for STM32F1 line. +* `Programming Manual PM0056 + `_ + (PDF); assembly language and register reference. +* `STM32F103CB `_ + overview page with links to further references. + +.. rubric:: Footnotes + +.. [#fusedpins] See :ref:`boardUsedPins ` + for more information. diff --git a/source/index.rst b/source/index.rst index ce3985f..d17c4db 100644 --- a/source/index.rst +++ b/source/index.rst @@ -67,11 +67,7 @@ Have fun! hardware/maple.rst hardware/maple-ret6.rst + hardware/maple-mini.rst .. TODO write/include these upon Mini and Native release - -.. .. toctree:: -.. :hidden: - -.. hardware/maple-mini.rst .. hardware/maple-native.rst diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst index a80e429..054d1a8 100644 --- a/source/lang/api/hardwarespi.rst +++ b/source/lang/api/hardwarespi.rst @@ -43,7 +43,7 @@ Turning the SPI Port On Now it's time to turn your SPI port on. Do this with the ``begin()`` function (an example is given below). -.. FIXME [0.0.11] Breathe doesn't include the class; fix & submit pull req +.. FIXME [Breathe] Output doesn't include the class; fix & submit pull req .. doxygenfunction:: HardwareSPI::begin diff --git a/source/timers.rst b/source/timers.rst index 403193f..e23579d 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -77,11 +77,17 @@ your program. PWM Conflicts ^^^^^^^^^^^^^ -Because PWM functionality on a given pin depends on -the configuration of the timer and channel, you must chose your -channels carefully if you want to use both timer interrupts and PWM in -the same program. Refer to your board's :ref:`Timer Pin Map -` to match up timer channels and pin numbers. +Because PWM functionality on a given pin depends on the configuration +of the timer and channel, you must chose your channels carefully if +you want to use both timer interrupts and PWM in the same program. +Refer to your board's timer pin map to match up timer channels and pin +numbers: + +.. TODO [0.0.12] Native links + +* :ref:`Maple ` +* :ref:`Maple RET6 Edition ` +* :ref:`Maple Mini ` Overhead ^^^^^^^^ diff --git a/source/usart.rst b/source/usart.rst index b3e1ea1..8766e3f 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -9,8 +9,7 @@ USART Hardware/Circuit Design ----------------------- -.. FIXME [0.0.12/Maple Native] UART4 and UART5, Native links -.. FIXME [0.0.11] Mini info and links +.. TODO [0.0.12/Maple Native] UART4 and UART5, Native links Each LeafLabs board has at least 3 separate USART devices. In the most simple use case, the RX and TX pins are used to send data at a @@ -24,6 +23,7 @@ available here: * :ref:`Maple ` * :ref:`Maple RET6 Edition ` +* :ref:`Maple Mini ` If you use a particular serial port, you cannot also use its communication pins for other purposes at the same time. -- cgit v1.2.3 From 376e1c98b4e1d34c216dba4b8c320b0c083a7a1c Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 25 May 2011 01:53:29 -0400 Subject: Docs: Move toggleLED() and waitForButtonPress() examples. These two examples from board-values.rst really belong in the documentation for the functions they reference. --- source/lang/api/board-values.rst | 42 +++++++++++----------------------- source/lang/api/toggleled.rst | 22 +++++++++++++++++- source/lang/api/waitforbuttonpress.rst | 28 +++++++++++++++++++++-- 3 files changed, 60 insertions(+), 32 deletions(-) diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst index 7198407..11b86a8 100644 --- a/source/lang/api/board-values.rst +++ b/source/lang/api/board-values.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _lang-board-values: Board-Specific Values @@ -122,8 +124,9 @@ Constants default (i.e., they are in :ref:`boardUsedPins `). However, they can be used as ordinary GPIOs if you call the :ref:`lang-disabledebugports` - function. (Be careful with this on the Maple, as writing to - ``BOARD_NJTRST_PIN`` may cause your board to reset!). + function. (Be careful with this on the Maple and Maple RET6 + Edition, as writing to ``BOARD_NJTRST_PIN`` :ref:`may cause your + board to reset `\ !). .. _lang-board-values-pwm-pins: @@ -161,33 +164,14 @@ Examples :ref:`BOARD_LED_PIN ` On the Maple, the built-in LED is connected to pin 13. On the Maple Mini, however, it is connected to pin 33. You can write a "blinky" program that works -on all LeafLabs boards using ``BOARD_LED_PIN`` and :ref:`toggleLED() -`:: - - void setup() { - pinMode(BOARD_LED_PIN, OUTPUT); - } - - void loop() { - toggleLED(); - delay(100); - } - -:ref:`BOARD_BUTTON_PIN `: Similarly, you can -write a single program that prints a message whenever the button is -pressed which will work on all LeafLabs boards using -``BOARD_BUTTON_PIN`` and :ref:`isButtonPressed() -`:: - - void setup() { - pinMode(BOARD_BUTTON_PIN, INPUT); - } - - void loop() { - if (isButtonPressed()) { - SerialUSB.println("You pressed the button!"); - } - } +on both boards using :ref:`this example `. + +:ref:`BOARD_BUTTON_PIN `: On the Maple, the +built-in button is connected to pin 38. On the Maple Mini, however, +it is connected to pin 32. :ref:`This example +` shows how you can write a program +that prints a message whenever the button is pressed which will work +on all LeafLabs boards. See Also -------- diff --git a/source/lang/api/toggleled.rst b/source/lang/api/toggleled.rst index 54a7d64..cad347f 100644 --- a/source/lang/api/toggleled.rst +++ b/source/lang/api/toggleled.rst @@ -1,15 +1,35 @@ +.. highlight:: cpp + .. _lang-toggleled: toggleLED() =========== -Switches the LED from off to on, or on to off. +*Toggle* the built-in LED: switch it from off to on, or on to off. Library Documentation --------------------- .. doxygenfunction:: toggleLED +Example +------- + +.. _lang-toggleled-example: + +This example sets up the board's LED pin for output, then toggles the +LED every 100 milliseconds:: + + void setup() { + pinMode(BOARD_LED_PIN, OUTPUT); + } + + void loop() { + toggleLED(); + delay(100); + } + + See Also -------- diff --git a/source/lang/api/waitforbuttonpress.rst b/source/lang/api/waitforbuttonpress.rst index a5bd45c..0e0fbaf 100644 --- a/source/lang/api/waitforbuttonpress.rst +++ b/source/lang/api/waitforbuttonpress.rst @@ -1,16 +1,40 @@ +.. highlight:: cpp + .. _lang-waitforbuttonpress: waitForButtonPress() ==================== -Wait for the board's built-in button (labeled BUT on the silkscreen) -to be pressed, possibly with timeout. +Wait for the board's built-in button to be pressed, possibly with +timeout. The button is labeled "BUT" on the board's silkscreen. Its +pin number is the constant :ref:`BOARD_BUTTON_PIN +`. Library Documentation --------------------- .. doxygenfunction:: waitForButtonPress + +Example +------- + +.. _lang-waitforbuttonpress-example: + +This example sets up the board's button pin as an input, then prints a +message very time the button is pressed. + +:: + + void setup() { + pinMode(BOARD_BUTTON_PIN, INPUT); + } + + void loop() { + waitForButtonPress(); + SerialUSB.println("You pressed the button!"); + } + See Also -------- -- cgit v1.2.3 From 42243a0c7315c508bd6b5f2d60e8c987f908aeff Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 26 May 2011 01:55:18 -0400 Subject: Make docs say their version is 'custom-build'. This should get changed on each release branch when the time comes. A FIXME comment has been added to that effect. --- source/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 63f109f..975ad1e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -59,7 +59,8 @@ copyright = u'2010, LeafLabs, LLC' # The short X.Y version. version = '0.0' # The full version, including alpha/beta/rc tags. -release = '0.0.10beta' +# FIXME [0.0.11] update this for the release +release = 'custom-build' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From b49a13adf1d71566b203464197b5f35fc9cb2fa1 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 26 May 2011 01:55:37 -0400 Subject: Docs: board-values.rst touchup. --- source/lang/api/board-values.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst index 11b86a8..d944c8d 100644 --- a/source/lang/api/board-values.rst +++ b/source/lang/api/board-values.rst @@ -16,9 +16,6 @@ it easier to share your code with other people who have different boards. Some example usages are given :ref:`below `. -The actual values for each board are given in the :ref:`Board Hardware -Documentation `. - .. contents:: Contents :local: -- cgit v1.2.3 From 9416f0052a7806ff4174a144e8d3449d4e834edb Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 26 May 2011 21:21:43 -0400 Subject: Fix millis() example. --- source/lang/api/millis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/lang/api/millis.rst b/source/lang/api/millis.rst index db0531c..b6fbf55 100644 --- a/source/lang/api/millis.rst +++ b/source/lang/api/millis.rst @@ -29,7 +29,7 @@ once per second:: SerialUSB.print("Time: "); time = millis(); // prints time since program started - Serial.println(time); + SerialUSB.println(time); // wait a second so as not to send massive amounts of data delay(1000); -- cgit v1.2.3 From dfdfebd03321db66ff522f8c21225b2ae2c9be52 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 15:53:02 -0400 Subject: Docs: Fix ADC voltage source error. Vdda, not Vcc. --- source/adc.rst | 10 +++++----- source/prolog.rst | 3 ++- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/source/adc.rst b/source/adc.rst index a749201..18c54ab 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -45,11 +45,11 @@ together, or the same voltage can even be sampled by multiple ADC pins at the same time. Another important factor when taking a voltage reading is the -reference voltages that the sample is being compared against. In the -case of the Maple, the high reference is |vcc| and the low reference -is ground. This means that noise or fluctuations on either |vcc| or -ground will affect the measurement. It also means that the voltage you -are trying to sample must be between ground and 3.3 V. +reference voltages that the sample is being compared against. For +Maple, the high reference is |vdda| and the low reference is ground. +This means that noise or fluctuations on either |vdda| or ground will +affect the measurement. It also means that the voltage you are trying +to sample must be between ground and 3.3 V. .. _adc-range: diff --git a/source/prolog.rst b/source/prolog.rst index 2823947..8606555 100644 --- a/source/prolog.rst +++ b/source/prolog.rst @@ -3,5 +3,6 @@ .. recommended by the Sphinx people, who have other ways of doing it. .. Common substitutions -.. |vcc| replace:: V\ :sub:`cc` +.. |vcc| replace:: V\ :sub:`CC` +.. |vdda| replace:: V\ :sub:`DDA` .. |i2c| replace:: I\ :sup:`2`\ C -- cgit v1.2.3 From 70042297aee9ce4bc5e0066036e9c80e28cad8ac Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 15:59:19 -0400 Subject: Docs: Include D3 in low-noise analog pins on Mini. --- source/hardware/maple-mini.rst | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index 3e79ed0..743bf1d 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -221,19 +221,14 @@ using the pins summarized in the following table: Low-Noise ADC Pins ^^^^^^^^^^^^^^^^^^ -Analog input pins D4 — D11 on the Maple Mini generally offer -lower-noise ADC performance than D3. If you’re concerned about -getting good ADC readings, we recommend using one of these pins to -take your measurements. - Maple Mini has an electrically isolated analog power plane with its own regulator, and a geometrically isolated ground plane, connected to -the digital plane by an inductor. Pins D4 — D11 are laid out to -correspond with these analog planes, and our measurements indicate -that they generally have the lowest noise of all the analog lines. -However, analog performance may vary depending upon the activity of -the other GPIOs. Consult the :ref:`Maple Mini hardware design files -` for more details. +the digital plane by an inductor. Its analog input pins, D3 — D11, +are laid out to correspond with these analog planes, and our +measurements indicate that they generally offer low noise ADC +performance. However, analog performance may vary depending upon the +activity of the other GPIOs. Consult the :ref:`Maple Mini hardware +design files ` for more details. .. _maple-mini-board-values: -- cgit v1.2.3 From 7d9cb855e3b710d92670379a7ba0b1a9c5184b06 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 16:01:37 -0400 Subject: Docs: Fix implication that Maple Rev 1 didn't have a battery charger. It did, but there was no jumper to cut power from the charging circuit, resulting in weird blinky behavior that was fixed in Rev 3. --- source/hardware/maple.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index b6950e0..fe2cae7 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -70,7 +70,6 @@ Rev 3 This batch of boards went on sale beginning in May 2010. They have a darker red silkscreen and the "infinity leaf" logo. The Maple Rev 3 was the first version which includes the built-in button, labeled BUT. -It also includes a built-in LiPo battery charger. .. figure:: /_static/img/maple_rev3.png :align: center -- cgit v1.2.3 From b74f9add390ec4b6200fefd234a6a5c470c9d0d6 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 18:55:57 -0400 Subject: Docs: Correct i2c.rst errors. 10-bit addressing has now been implemented. Slave mode is unimplemented, however. --- source/i2c.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/source/i2c.rst b/source/i2c.rst index 31976ac..8f1b26f 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -7,17 +7,18 @@ two wires/channels for communication between many devices. Every message passed on the bus is between a *master* (who initiates the message) and a *slave* device. Slaves are addressed using 7-bit -addresses (up to 127 unique devices); 10-bit addressing is possible, -but currently unimplemented. Every message consists of an arbitrary -combination of 8-bit reads and writes as requested by the master. -Higher level functionality, such as reading a particular register -value, is achieved by writing to set the memory location then reading -to pull out the data. +addresses (up to 127 unique devices); 10-bit addressing is also +possible. Every message consists of an arbitrary combination of 8-bit +reads and writes as requested by the master. Higher level +functionality, such as reading a particular register value, is +achieved by writing to set the memory location then reading to pull +out the data. Note that the master/slave designation is on a message-by-message basis. Maple can act as both a master (messages initiated by user code) and slave device (responding to requests via configurable -interrupt handlers) at the same time. +interrupt handlers) at the same time (though slave mode is currently +unimplemented). .. contents:: Contents :local: @@ -28,10 +29,10 @@ Hardware/Circuit Design .. FIXME [0.1.0] Link to board-specific values (BOARD_I2C1_SDA_PIN, etc.) Maple boards have two |i2c| ports. Maples reliably communicate with -up to a 400kHz clock speed; this doesn't translate into a 400kbps data -rate except in extreme cases because of addressing and protocol +up to a 400kHz clock speed; this doesn't translate into a 400kbps +data rate except in extreme cases because of addressing and protocol overhead. We have tested clock speeds up to a megahertz and have had -mixed results; in theory it could be possible to achieve even higher +mixed results; in theory, it could be possible to achieve even higher rates, but signal quality degrades rapidly, and the bus becomes unreliable. -- cgit v1.2.3 From 40ae21ac7d79197577ebfd324e2c9e266000e33a Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 20:57:54 -0400 Subject: Docs: Updating pinmode.rst Convert to board-specific values; make the language friendlier. --- source/lang/api/pinmode.rst | 47 ++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/source/lang/api/pinmode.rst b/source/lang/api/pinmode.rst index 8cee3e5..643e26e 100644 --- a/source/lang/api/pinmode.rst +++ b/source/lang/api/pinmode.rst @@ -20,26 +20,29 @@ Library Documentation Discussion ---------- -``pinMode()`` is usually called within :ref:`lang-setup` in order to +pinMode() is usually called within :ref:`lang-setup` in order to configure a pin for a certain usage (although it may be called anywhere). Example ------- -:: +This example uses pinMode() to set up the pin connected to the +built-in LED as an output. Once this is done, +:ref:`lang-digitalwrite` can be used to turn the pin ``HIGH`` and +``LOW``, which turn the LED on and off. - int ledPin = 13; // LED connected to digital pin 13 +:: void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output + pinMode(BOARD_LED_PIN, OUTPUT); // sets the LED pin as output } void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, LOW); // sets the LED off + delay(1000); // waits for a second } Arduino Compatibility @@ -48,17 +51,16 @@ Arduino Compatibility .. TODO check out Arduino vs. Maple static discilpline cutoffs to .. ensure accuracy of following: -The libmaple implementation of ``pinMode()`` supports the ``INPUT`` -and ``OUTPUT`` modes with semantics identical to that of the Arduino -function (however, be advised that the Maple, as a 3.3V device, will -only drive 3.3V to an ``OUTPUT`` pin that has been set ``HIGH``). +On Maple, pinMode() supports the ``INPUT`` and ``OUTPUT`` modes in the +same way as Arduino (however, remember that the Maple, as a 3.3V +device, will only drive 3.3V to an ``OUTPUT`` pin that has been set +``HIGH``, instead of 5V like on Arduino). -``INPUT_ANALOG`` and ``PWM`` modes were added because the Maple does -not distinguish between analog and digital pins the same way the -Arduino does. Unlike the Arduino, you **must call** ``pinMode()`` to -set up a pin for these purposes before a call to, e.g., -:ref:`lang-analogRead`. In practice, this should only add a few lines -to your :ref:`lang-setup` function. +``INPUT_ANALOG`` and ``PWM`` modes were added because the Maple +doesn't separate the analog and digital pins the same way Arduino +does. Unlike on Arduino, you **must call** pinMode() to set up a pin +for these purposes before a call to, e.g., :ref:`lang-analogRead`. +This should only add a few lines to your :ref:`lang-setup` function. .. TODO [0.1.0] verify following before putting it in: @@ -69,9 +71,10 @@ to your :ref:`lang-setup` function. See Also -------- -- :ref:`lang-constants` -- :ref:`lang-digitalwrite` -- :ref:`lang-digitalread` -- Maple :ref:`GPIO ` reference page +- :ref:`lang-board-values` +- :ref:`lang-constants` +- :ref:`lang-digitalwrite` +- :ref:`lang-digitalread` +- :ref:`gpio` .. include:: /arduino-cc-attribution.txt -- cgit v1.2.3 From 97031fa55615777864319e051ab9afc57312c4e8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 22:08:39 -0400 Subject: Docs: Update gpio.rst. Add a section about GPIO ports, since that existed nowhere. Made a ref for 5V tolerance. Other clarifications and improvements. --- source/gpio.rst | 106 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 65 insertions(+), 41 deletions(-) diff --git a/source/gpio.rst b/source/gpio.rst index 64ad494..af1de20 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -7,18 +7,67 @@ Each LeafLabs board comes with ready-to-use General Purpose Input/Output (GPIO) pins, which are numbered starting from zero. These numbers are listed on your board's silkscreen, next to where the pin is broken out to a header. Many pins may additionally be used for -special features or peripheral functions. +special features or interfacing with other hardware. .. contents:: Contents :local: +.. _gpio-modes: + +GPIO Modes +---------- + +Each GPIO pin can be configured using :ref:`lang-pinmode` to behave in +a number of ways: as a digital output pin, as an analog input pin, +etc. + +A :ref:`WiringPinMode ` value specifies +the complete set of possible configurations; not every pin can have +all of these modes. For example, on the Maple, pin 15 may have mode +``INPUT_ANALOG``, but not ``PWM``. See your board's :ref:`pin maps +` and its silkscreen for more information on what +functionality is available on each pin. + +Function Reference +------------------ + +- :ref:`lang-pinmode` + +- :ref:`lang-digitalread` + +- :ref:`lang-digitalwrite` + +- :ref:`lang-analogread` + +- :ref:`lang-pwmwrite` (Maple's equivalent to ``analogWrite()``; see + :ref:`lang-analogwrite` for differences from the Arduino version). + +.. _gpio-ports: + +GPIO Ports +---------- + +Normally, you'll interact with pins using just their number (or a +constant like :ref:`BOARD_LED_PIN ` which +stands for a number). However, behind the scenes, the STM32 +microcontroller on your board separates the pins into groups called +*GPIO ports*. Each GPIO port is given a letter, so for example, +there's GPIO port A, port B, and so on\ [#fnumports]_. The pins on a +GPIO port are given *bit numbers*, which go from 0 to 15. In ST's +documentation, a pin is given by the letter "P", followed by its port +letter and bit number. For instance, "PA4" is GPIO port A, bit 4. + .. _gpio-pin-maps: Pin Maps -------- -The hardware documentation for your board lists each pin's -capabilities, by pin number: +Part of :ref:`Maple IDE's ` job is to convert normal pin numbers +into the corresponding GPIO port and bit when you call functions like +:ref:`lang-pinmode`. It does this using a *pin map*, which lists the +GPIO port and bit for each pin number. The GPIO documentation for +your board includes its pin map, which also lists the other +peripherals by pin number: .. TODO [0.0.12] Native link @@ -28,46 +77,15 @@ capabilities, by pin number: .. * :ref:`Maple Native ` +.. _gpio-5v-tolerant: + The current and voltage limitations were determined using the STM32 datasheets. In particular, only some GPIO pins are **5V tolerant**, which means that applying 5 volts to a pin and reading it as input or allowing it to drain to ground will not damage that pin. Connecting a -voltage higher than 3.3 V to a non-5 V tolerant pin may damage your +voltage higher than 3.3V to a non-5V tolerant pin may damage your board. -.. _gpio-modes: - -GPIO Modes ----------- - -Each of the GPIO pins on a Maple board may be configured using -pinMode() to behave in a number of ways: as a digital output pin, -or as an analog input pin, etc., depending on the particular pin. - -A ``WiringPinMode`` value specifies the complete set of possible -configurations; not every pin can have all of these modes. For -example, on the Maple, pin 15 may have mode ``INPUT_ANALOG``, but not -``PWM``. See your :ref:`board's pin maps ` and its -silkscreen for more information on what functionality is available on -each pin. - -.. doxygenenum:: WiringPinMode - -Function Reference ------------------- - -- :ref:`pinMode() ` - -- :ref:`digitalRead() ` - -- :ref:`digitalWrite() ` - -- :ref:`analogRead() ` - -- :ref:`pwmWrite() ` (Maple's equivalent to - ``analogWrite()``; see the :ref:`analogWrite() reference - ` for differences from the Arduino version). - .. _gpio-recommended-reading: Recommended Reading @@ -75,9 +93,15 @@ Recommended Reading * ST Documentation for the STM32F103 series of microcontrollers: - * `Reference Manual `_ (pdf) + * `Reference Manual RM0008 + `_ + (PDF); general, definitive resource for STM32F1 line. + * `Programming Manual PM0056 + `_ + (PDF); assembly language and register reference. - * `Programming Manual - `_ - (PDF; assembly language and register reference) +.. rubric:: Footnotes +.. [#fnumports] The total number of GPIO ports depends on what board + you have. For example, Maple Mini has three: ports A, B, and C. + Maple Native has seven: ports A through G. -- cgit v1.2.3 From 4c56cdc2926472992fcf3e6720b5100160547b2a Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 22:41:57 -0400 Subject: Docs: Making boards pages point to "5V tolerant" definition. --- source/hardware/maple-mini.rst | 5 +++-- source/hardware/maple-ret6.rst | 5 +++-- source/hardware/maple.rst | 5 +++-- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index 743bf1d..dfad559 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -95,7 +95,7 @@ Master Pin Map This table shows a summary the available functionality on every GPIO pin, by peripheral type. The "5 V?" column documents whether or not -the pin is 5 volt tolerant. +the pin is :ref:`5 volt tolerant `. .. csv-table:: :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? @@ -296,7 +296,8 @@ damage your board permanently. * **High voltage on non-tolerant pins**: not all header pins are 5 V compatible; so e.g. connecting certain serial devices in the wrong way could over-voltage the pins. The :ref:`pin-mapping master table - ` details which pins are 5 V-tolerant. + ` details which pins are :ref:`5 + V-tolerant `. Errata ------ diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 2f636d7..d419d62 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -104,7 +104,7 @@ Master Pin Map This table shows a summary of the available functionality on every GPIO pin, by peripheral type. The "5 V?" column documents whether or -not the pin is 5 volt tolerant. +not the pin is :ref:`5 volt tolerant `. .. csv-table:: :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART/USART `, :ref:`SPI `, 5 V? @@ -328,7 +328,8 @@ damage your board permanently. * **High voltage on non-tolerant pins**: not all header pins are 5V compatible; so e.g. connecting certain serial devices in the wrong way could over-voltage the pins. The :ref:`pin-mapping master table - ` details which pins are 5V-tolerant. + ` details which pins are + :ref:`5V-tolerant `. Errata ------ diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index fe2cae7..a06c222 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -153,7 +153,7 @@ Master Pin Map This table shows a summary of the available functionality on every GPIO pin, by peripheral type. The "5 V?" column documents whether or -not the pin is 5 volt tolerant. +not the pin is :ref:`5 volt tolerant `. .. csv-table:: :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? @@ -373,7 +373,8 @@ permanently. * **High voltage on non-tolerant pins**: not all header pins are 5V compatible; so e.g. connecting certain serial devices in the wrong way could over-voltage the pins. The :ref:`pin-mapping master table - ` details which pins are 5 V tolerant. + ` details which pins are :ref:`5 V tolerant + `. Errata ------ -- cgit v1.2.3 From 8c764834d8166e03122703bc4ad4b9623225898e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 22:43:00 -0400 Subject: Docs: Improve external-interrupts.rst. Make the language friendlier; point to GPIO port definition for an explanation of the EXTI line definition. --- source/external-interrupts.rst | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index ccb9afd..9089d77 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -5,8 +5,8 @@ External Interrupts =================== -External interrupts can be used to trigger routines to run in response -to changes in voltage on a pin. Each :ref:`GPIO pin ` can be +External interrupts can be used to make a voltage change on a pin +cause a function to be called. Each :ref:`GPIO pin ` can be used to detect transitions, such as when the voltage goes from :ref:`LOW ` to :ref:`HIGH `, or from ``HIGH`` to ``LOW``. This can be used to avoid checking for @@ -20,22 +20,21 @@ Overview -------- External interrupts are often used to detect when events happen -outside of the microcontroller. These can be used to tell Maple when -events happen, such as when a sensor has data ready to be read, or -when a button has been pushed. When such an event happens, an -interrupt is raised, and the Maple can react to it with a preset -*interrupt handler*, which is a function that gets called whenever the -event occurs. +outside of the Maple. These can be used to tell Maple when events +happen, such as when a sensor has data ready to be read, or when a +button has been pushed. When such an event happens, an interrupt is +raised, and the Maple stops whatever it was doing to react to it by +calling a function (called an *interrupt handler*) which you specify +using :ref:`lang-attachinterrupt`. .. _external-interrupts-exti-line: -Every GPIO pin can generate an external interrupt, subject to certain -constraints. There can be a maximum of 16 different external -interrupts set up at a time. This is because the external interrupt -lines on the STM32 are shared between GPIO ports. In effect, this -means that every pin on the Maple connects to what is called an *EXTI -line*, and within an EXTI line, only one of the pins that connects to -it can be used to detect external interrupts at a time. +Every pin can generate an external interrupt, but there are some +restrictions. At most 16 different external interrupts can be used at +one time. Further, you can't just pick any 16 pins to use. This is +because every pin on the Maple connects to what is called an *EXTI +line*, and only one pin per EXTI line can be used for external +interrupts at a time [#fextisports]_. .. TODO [0.0.12] Maple Native links @@ -65,3 +64,13 @@ Recommended Reading `_ (PDF), Chapter 9, "General-purpose and alternate-function I/Os", and Chapter 10, "Interrupts and Events". + +.. rubric:: Footnotes + +.. [#fextisports] The underlying reason for this restriction is that + the external interrupt lines on the STM32 are shared between + :ref:`GPIO ports `. There can be only one external + interrupt on each GPIO bit, out of all of the ports. That is, if + PA4 has an external interrupt on it, then PB4 can't have one, too. + Since the GPIO bit numbers only go from 0 to 15, there can only be + 16 external interrupts at a time. -- cgit v1.2.3 From c9993d6929e48b62097f08358c578983702f6185 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 22:59:24 -0400 Subject: Docs: Improve i2c.rst. Slightly reorganize to keep it consistent with the rest of the docs. --- source/i2c.rst | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/source/i2c.rst b/source/i2c.rst index 8f1b26f..670b91d 100644 --- a/source/i2c.rst +++ b/source/i2c.rst @@ -4,15 +4,25 @@ ===== |i2c| is a crude and easy-to-hack serial protocol that requires only -two wires/channels for communication between many devices. Every -message passed on the bus is between a *master* (who initiates the -message) and a *slave* device. Slaves are addressed using 7-bit -addresses (up to 127 unique devices); 10-bit addressing is also -possible. Every message consists of an arbitrary combination of 8-bit -reads and writes as requested by the master. Higher level -functionality, such as reading a particular register value, is -achieved by writing to set the memory location then reading to pull -out the data. +two wires/channels for communication between Maple and many other +devices. + +.. contents:: Contents + :local: + +Overview +-------- + +Communication via |i2c| is broken up into messages. Every message is +between a *master* device, which initiates the message, and a *slave* +device, which responds. + +Slaves are addressed using 7-bit addresses (up to 127 unique devices); +10-bit addressing is also possible. Every message consists of an +arbitrary combination of 8-bit reads and writes as requested by the +master. Higher level functionality, such as reading a particular +register value, is achieved by writing to set the memory location then +reading to pull out the data. Note that the master/slave designation is on a message-by-message basis. Maple can act as both a master (messages initiated by user @@ -20,9 +30,6 @@ code) and slave device (responding to requests via configurable interrupt handlers) at the same time (though slave mode is currently unimplemented). -.. contents:: Contents - :local: - Hardware/Circuit Design ----------------------- -- cgit v1.2.3 From c2d042ff66dad8e6d21b8101a5b4d30465a559d8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 27 May 2011 23:56:38 -0400 Subject: Docs: Improve analogwrite.rst. Make the note warning against its usage more direct. Add a blurb introducing its purpose and links in See Also to related board-specific values. --- source/lang/api/analogwrite.rst | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst index b553d8b..0169976 100644 --- a/source/lang/api/analogwrite.rst +++ b/source/lang/api/analogwrite.rst @@ -8,21 +8,23 @@ analogWrite() ============= +analogWrite() is used to create a :ref:`PWM ` wave on a pin. + .. note:: On the Maple, calling analogWrite() is the same as calling - :ref:`lang-pwmwrite`\ ; we recommend using that function directly - instead. + :ref:`lang-pwmwrite`. We recommend writing pwmWrite() instead of + analogWrite(). - This is because PWM is not true analog output (i.e., is not the - output of a `DAC + This is because PWM is not true analog output (it's not the output + of a `DAC `_\ ), so - the function is badly named. For instance, analogWrite() **has - absolutely nothing to do with** :ref:`lang-analogread`\ , which is - potentially confusing. + the function is very badly named. For instance, **analogWrite() + has nothing to do with** :ref:`lang-analogread`\ , which can be + confusing. - The alias of analogWrite() to pwmWrite() is provided for the sake - of compatibility with Arduino only. + We provide analogWrite() for the sake of compatibility with Arduino + only. .. contents:: Contents :local: @@ -67,7 +69,7 @@ for more information. Another fix is to consult your board's :ref:`pin maps ` to find the timer which controls PWM on the pin you're using, then set -that Timer's overflow to 255. Subsequent calls to analogWrite() +that timer's overflow to 255. Subsequent calls to analogWrite() should work as on the Arduino (with the same loss of precision). Note, however, that that affects the overflow for the **entire timer**, so other code relying on that timer (such as any @@ -162,6 +164,9 @@ See Also -------- - :ref:`pwm` +- :ref:`lang-pwmwrite` +- :ref:`BOARD_NR_PWM_PINS ` +- :ref:`boardPWMPins ` .. rubric:: Footnotes -- cgit v1.2.3 From d104f3b2dad7c315cebb9dc6e8eaeddcb209dafe Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 28 May 2011 00:16:12 -0400 Subject: Docs: Simplify and clarify usart.rst. Make the language a little friendlier, say the words "serial port", and let them know that baud rate is a speed. --- source/usart.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/source/usart.rst b/source/usart.rst index 8766e3f..e65821d 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -3,19 +3,25 @@ USART ===== +A USART is more commonly known a *serial port*. It's used to transmit +information between Maple and another device (like your computer, +another Maple, etc.). + .. contents:: Contents :local: Hardware/Circuit Design ----------------------- +.. TODO [0.0.12] Add some more information here (like how you should +.. connect TX_a to RX_b and RX_a to TX_b). + .. TODO [0.0.12/Maple Native] UART4 and UART5, Native links Each LeafLabs board has at least 3 separate USART devices. In the most simple use case, the RX and TX pins are used to send data at a -predetermined baud rate with the line voltage level relative to -ground. Their usage is documented in the :ref:`Serial Ports -` language reference page. +predetermined speed (or *baud rate*). Their usage is documented in +the :ref:`Serial Ports ` language reference page. Which pins correspond to the USART TX and RX pins are given on your board's silkscreen, and also in the board-specific USART pin maps -- cgit v1.2.3 From 184da40c6dc0509d27a423866a48f707fcb1b370 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 28 May 2011 00:25:05 -0400 Subject: Docs: Tweak disabling JTAG debugging information. --- source/arduino-compatibility.rst | 17 +++++++++-------- source/lang/api/disabledebugports.rst | 6 ++++-- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/source/arduino-compatibility.rst b/source/arduino-compatibility.rst index e6852a0..c200411 100644 --- a/source/arduino-compatibility.rst +++ b/source/arduino-compatibility.rst @@ -26,12 +26,12 @@ EABI target (:command:`arm-non-eabi-gcc`). A (preliminary) reference on :ref:`using arm-none-eabi-gcc ` is available. The bitwidth of the processor means that the Maple can process 32-bit -operations (like adding two 32-bit integers) in a single instruction, -while an Arduino processor would have to split up large operations -into several smaller ones. In a lot of cases 8-bit operations are -plenty (integers 0-255, single characters of text, etc.), but if -you're dealing with higher resolution data, the speed up could be -significant. +operations (like adding or multiplying two 32-bit integers) in a +single instruction, while an Arduino processor would have to split up +large operations into several smaller ones. In a lot of cases 8-bit +operations are plenty (integers 0-255, single characters of text, +etc.), but if you're dealing with higher resolution data, the speed up +could be significant. A trade-off is that code could be larger as well; program instructions and memory locations can be up to 32 bits each. However, removal of @@ -45,8 +45,9 @@ Header Numbering and Incompatibilities The numbering of headers is different; on the Maple each GPIO has a unique number: 0, 1, 2, all the way up to 37 (actually, there are -:ref:`a few more `...). On the Arduino, the analog pins are -numbered separately (A0-A5) from the digital pins (D0\ -D13). +:ref:`a few more `...). On the Arduino, the +analog pins are numbered separately (A0-A5) from the digital pins (D0\ +-D13). The incompatible hardware differences are: diff --git a/source/lang/api/disabledebugports.rst b/source/lang/api/disabledebugports.rst index 43ac337..283cdbf 100644 --- a/source/lang/api/disabledebugports.rst +++ b/source/lang/api/disabledebugports.rst @@ -22,10 +22,12 @@ Example } void loop() { - // Now you can use the debug port pins as ordinary pins + // Now you can use the debug port pins (the pins on the JTAG + // header on the Maple) as ordinary pins. } See Also -------- -* :ref:`lang-enabledebugports` +- :ref:`lang-enabledebugports` +- :ref:`Important erratum on Maple pin 43 ` -- cgit v1.2.3 From 2f92b5e2c66f5422eca76882a3e23d498e7c618d Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 1 Jun 2011 13:25:40 -0400 Subject: Docs: Update release FIXMEs for 0.0.12. This is a pretty brain-dead way to manage these pre-release preparations. Should figure out the done thing and use that instead. --- source/conf.py | 2 +- source/maple-ide-install.rst | 13 +++++-------- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/source/conf.py b/source/conf.py index 975ad1e..005a988 100644 --- a/source/conf.py +++ b/source/conf.py @@ -59,7 +59,7 @@ copyright = u'2010, LeafLabs, LLC' # The short X.Y version. version = '0.0' # The full version, including alpha/beta/rc tags. -# FIXME [0.0.11] update this for the release +# FIXME [0.0.12] update this for the release release = 'custom-build' # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 2818bfb..bc8bc18 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -17,7 +17,7 @@ us directly`_\ ! Download -------- -.. FIXME [0.0.11] Update this for the release. +.. FIXME [0.0.12] Update this for the release. This documentation was built from a development version of libmaple. See the formally released `LeafLabs documentation @@ -27,21 +27,18 @@ Maple IDE release. .. Choose the correct version for your operating system: .. .. list-table:: -.. :widths: 15 30 50 +.. :widths: 15 30 .. :header-rows: 1 .. * - Platform .. - Status .. - IDE Package -.. * - Windows +.. * - `Windows XP `_ .. - Tested on 32-bit Windows XP -.. - `maple-ide-0.0.10-windowsxp32.zip `_ (about 75 MB) -.. * - Linux +.. * - `Linux `_ .. - Tested on Ubuntu 10.04 (32-bit) -.. - `maple-ide-0.0.10-linux32.tgz `_ (about 30MB) -.. * - Mac OSX +.. * - `Mac OS X `_ .. - Tested on Snow Leopard (10.6) -.. - `maple-ide-0.0.10-macosx-10_6.dmg `_ (about 40 MB) The package bundles together a compiler, an upload utility, a software library, and a simple GUI text editor. All this software is `free and -- cgit v1.2.3 From d53081c1bf6a4fdfcc248e164d9db078605ffd09 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 3 Jun 2011 15:42:29 -0400 Subject: Docs: Various tweaks and fixups. Thanks to forum user AndyH for the corrections. --- source/maple-ide-install.rst | 7 ++++--- source/maple-quickstart.rst | 12 ++++++------ source/unix-toolchain.rst | 10 +++++----- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index bc8bc18..d3079c4 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -137,10 +137,11 @@ Make sure you have a Java runtime (JRE) installed; if you can run :command:`java` from the shell, you should be fine. Next, run the script :file:`install-udev-rules.sh` in the extracted -IDE directory. It will ask for root permissions. You now need to -restart udev:: +IDE directory. It will ask for root permissions (you will be prompted +with something along the lines of ``[sudo] password for +:``). You now need to restart udev:: - sudo /etc/init.d/udev restart + $ sudo restart udev This will grant members of the group ``plugdev`` read/write access to Maple devices over USB. Make sure that you are in that group. (For diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index c7596ce..38b7fff 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -178,12 +178,12 @@ select Examples > Stubs > HelloWorld (similarly to when you selected the Blink program), and make sure the correct board and serial port targets are selected from the Tools menu. -Open the Serial Monitor window (on the far right of the toolbar) and -make sure the 9600 baud speed is selected. Then go back to the code -editing window and upload your program (Upload will recompile your -code automatically if there's been any change since the last -Verify). You should get text spit at you over the serial monitor right -after the program is uploaded. Shout back! We can hear you! +Open the Serial Monitor window (on the far right of the toolbar). Then +go back to the code editing window and upload your program (Upload +will recompile your code automatically if there's been any change +since the last Verify). You should get text spit at you over the +serial monitor right after the program is uploaded. Shout back! We +can hear you! Go forth exuberantly! --------------------- diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index fddb529..1084ecc 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -65,7 +65,7 @@ your system down too much. `Git `_ is a distributed code versioning system we use to track changes in our source code; ``git-core`` is the -corresponding package. +corresponding package. ``wget`` is a simple tool to download files over http from the command line; installing it is optional (you could pull in the required @@ -123,7 +123,7 @@ From the libmaple directory, :: $ groups # make sure it includes plugdev; if not add, yourself to it $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules - $ sudo /etc/init.d/udev restart + $ sudo restart udev As a security precaution on Linux, unknown USB devices can only be accessed by root. This udev script identifies the Maple based on its @@ -356,7 +356,7 @@ To exit the screen session, type :kbd:`C-a C-\\` (control-a, followed by control-backslash) on Mac, or :kbd:`C-a k` (control-a k) on Linux, and type ``y`` when prompted if you're sure. -.. note:: +.. note:: Using ``screen`` sometimes messes up your terminal session on OS X. If your shell starts acting funny after you exit ``screen``, you @@ -373,7 +373,7 @@ Starting your own projects -------------------------- So everything worked, and you want to start your own project? Great! -There are two ways to go about it. +There are two ways to go about it. If your project is small, all you have to do is replace :file:`~/libmaple/main.cpp` with your own code, and you're free to use @@ -393,7 +393,7 @@ To create an archive, use the ``library`` Makefile target:: This will produce a build-time library in the file :file:`~/libmaple/build/libmaple.a`. To use it, make sure that you link against that library, and that the libmaple sources are in your -include path. +include path. At a minimum, your include path should contain the directories :file:`~/libmaple/libmaple` and :file:`~/libmaple/wirish/`. If you -- cgit v1.2.3 From c5d35517757433ea505a735159e9e9de1653189f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 3 Jun 2011 17:24:28 -0400 Subject: Docs: Correct "Github" -> "GitHub" --- source/libmaple/contributing.rst | 8 ++++---- source/libmaple/overview.rst | 2 +- source/unix-toolchain.rst | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/libmaple/contributing.rst b/source/libmaple/contributing.rst index ded25f8..bb4d550 100644 --- a/source/libmaple/contributing.rst +++ b/source/libmaple/contributing.rst @@ -12,7 +12,7 @@ function, etc.), feel free to just make a `forum post If your changes are larger (you wrote a new library, you added support for a new peripheral, etc.), we'd prefer you submit a pull request on -Github or send us a nicely-formatted patch via email. +GitHub or send us a nicely-formatted patch via email. .. contents:: Contents :local: @@ -37,7 +37,7 @@ released under the `Lesser GPL `_ may be accepted for Wirish, but will almost certainly be rejected for libmaple proper. We will not accept patches released under the `GPL -`_. +`_. **We're not against the GPL**! It just doesn't suit our purposes for libmaple. If you're interested in a GPLed library for ST @@ -48,11 +48,11 @@ fine, we just don't want any core libmaple or Wirish code to be GPLed. .. _libmaple-faq-patches-github: -Submitting Via Github Pull Request (Preferred) +Submitting Via GitHub Pull Request (Preferred) ---------------------------------------------- The most convenient way for you to contribute patches is to submit a -pull request on `Github `_. Github provides +pull request on `GitHub `_. Github provides excellent code review interfaces, which will make it easy for us at LeafLabs to communicate with you (and each other) about your patch. It also makes it easy for us to merge your patch into the libmaple diff --git a/source/libmaple/overview.rst b/source/libmaple/overview.rst index 345769b..d18bfe2 100644 --- a/source/libmaple/overview.rst +++ b/source/libmaple/overview.rst @@ -327,7 +327,7 @@ What Next? After you've read this page, you can proceed to the :ref:`libmaple API listing `. From there, you can read documentation and follow links to the current source code for those files on `libmaple's -Github page `_. +GitHub page `_. .. rubric:: Footnotes diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 1084ecc..b8382c4 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -418,7 +418,7 @@ IDE updates will have corresponding library updates. Our `blog releases; an `RSS feed `_ is available. -You can sign up for a free `Github `_ +You can sign up for a free `GitHub `_ account and `watch libmaple `_ to receive notifications about bleeding-edge development. -- cgit v1.2.3 From a2f4a145b2349638cf68e03efa4553055bd50315 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 6 Jun 2011 13:39:32 -0400 Subject: Docs: add note on adding self to plugdev group. Thanks to forum user AndyH for the suggestion. --- source/maple-ide-install.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index d3079c4..67171dd 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -144,9 +144,11 @@ with something along the lines of ``[sudo] password for $ sudo restart udev This will grant members of the group ``plugdev`` read/write access to -Maple devices over USB. Make sure that you are in that group. (For -more information on why this is part of the install process, see the -:ref:`Unix toolchain quickstart `). +Maple devices over USB. Make sure that you are in that group by +running ``$ sudo adduser plugdev`` (which will ensure +access to the Maple, but may report that you are already a member of +that group). (For more information on why this is part of the install +process, see the :ref:`Unix toolchain quickstart `). To run the Maple IDE, run :command:`maple-ide` from the shell, or double-click on it if your window system supports it. -- cgit v1.2.3 From 036c04bbe6c75f71a66fad90530ac1dec5e47b53 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 10 Jun 2011 09:10:03 -0400 Subject: Docs: Use "BOARD_LED_PIN" instead of "13". Fix examples where pin 13 was used explicitly instead of BOARD_LED_PIN. Also change an AVR-specific example in docs/lang/cpp/booleanvariables.rst to Maple conventions. --- source/lang/api/delay.rst | 13 ++++++------- source/lang/api/digitalwrite.rst | 7 ++++--- source/lang/cpp/bitwisemath.rst | 10 +++++----- source/lang/cpp/booleanvariables.rst | 19 +++++++------------ source/lang/cpp/define.rst | 6 +++--- source/lang/cpp/if.rst | 14 +++++++------- source/lang/cpp/int.rst | 4 ++-- source/lang/cpp/unsignedint.rst | 4 ++-- 8 files changed, 36 insertions(+), 41 deletions(-) diff --git a/source/lang/api/delay.rst b/source/lang/api/delay.rst index 9ef06a0..30bd436 100644 --- a/source/lang/api/delay.rst +++ b/source/lang/api/delay.rst @@ -42,17 +42,16 @@ Example :: - int ledPin = 13; // LED connected to pin 13 - void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output + // set up the built-in LED pin for output: + pinMode(BOARD_LED_PIN, OUTPUT); } void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, LOW); // sets the LED off + delay(1000); // waits for a second } .. _lang-delay-seealso: diff --git a/source/lang/api/digitalwrite.rst b/source/lang/api/digitalwrite.rst index 376cbc3..bae8db9 100644 --- a/source/lang/api/digitalwrite.rst +++ b/source/lang/api/digitalwrite.rst @@ -28,9 +28,10 @@ more slowly as an output than the other pins. Example ------- -The following example sets pin 13 to ``HIGH``, makes a one-second-long -delay, sets the pin back to ``LOW``, and delays again, causing a -blinking pattern (you could also use :ref:`lang-toggleled`):: +The following example sets the built-in LED pin to ``HIGH``, makes a +one-second-long delay, sets the pin back to ``LOW``, and delays again, +causing a blinking pattern (you could also use +:ref:`lang-toggleled`):: void setup() { pinMode(BOARD_LED_PIN, OUTPUT); // sets the digital pin as output diff --git a/source/lang/cpp/bitwisemath.rst b/source/lang/cpp/bitwisemath.rst index 59794ba..cfe34f2 100644 --- a/source/lang/cpp/bitwisemath.rst +++ b/source/lang/cpp/bitwisemath.rst @@ -109,21 +109,21 @@ The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 to 0) some of the bits in an integer expression. In a bitwise OR operation if there is a 1 in the mask bit, that bit is inverted; if there is a 0, the bit is not inverted and stays the same. Below is a -program to blink digital pin 13 (the LED pin on Maple):: +program to toggle the built-in LED pin (you can also accomplish this +with :ref:`lang-toggleled`):: - // Blink Maple LED pin + // Toggle built-in LED pin - int led_pin = 13; int toggle = 0; // demo for Exclusive OR void setup(){ - pinMode(led_pin, OUTPUT); + pinMode(BOARD_LED_PIN, OUTPUT); } void loop(){ toggle = toggle ^ 1; - digitalWrite(led_pin, toggle); + digitalWrite(BOARD_LED_PIN, toggle); delay(100); } diff --git a/source/lang/cpp/booleanvariables.rst b/source/lang/cpp/booleanvariables.rst index 0d76a12..e032c74 100644 --- a/source/lang/cpp/booleanvariables.rst +++ b/source/lang/cpp/booleanvariables.rst @@ -21,25 +21,20 @@ Example :: - int ledPin = 13; // LED on pin 13 - int switchPin = 12; // momentary switch on 12, other side connected to ground - // running is a boolean variable: bool running = false; void setup() { - pinMode(ledPin, OUTPUT); - pinMode(switchPin, INPUT); - digitalWrite(switchPin, HIGH); // turn on pullup resistor + pinMode(BOARD_LED_PIN, OUTPUT); + pinMode(BOARD_BUTTON_PIN, INPUT); } void loop() { - if (digitalRead(switchPin) == LOW) { - // switch is pressed - pullup keeps pin high normally - delay(100); // delay to debounce switch - running = !running; // toggle running variable - digitalWrite(ledPin, running) // indicate via LED - } + if (isButtonPressed()) { + // button is pressed + running = !running; // toggle running variable + digitalWrite(BOARD_LED_PIN, running) // indicate via LED + } } See Also diff --git a/source/lang/cpp/define.rst b/source/lang/cpp/define.rst index bdf7283..b22085f 100644 --- a/source/lang/cpp/define.rst +++ b/source/lang/cpp/define.rst @@ -43,9 +43,9 @@ Example :: - #define LED_PIN 13 - // The compiler will replace any mention of LED_PIN with - // the value 3 at compile time. + #define MAPLE_LED_PIN 13 + // The compiler will replace any mention of MAPLE_LED_PIN with + // the value 13 at compile time. See Also -------- diff --git a/source/lang/cpp/if.rst b/source/lang/cpp/if.rst index d57b9f1..f248b05 100644 --- a/source/lang/cpp/if.rst +++ b/source/lang/cpp/if.rst @@ -43,28 +43,28 @@ conditional. If this is done, the next line (which ends in a semicolon) becomes the only line in the body. The following three ``if`` statements all do the same thing:: - if (x > 120) digitalWrite(ledPin, HIGH); + if (x > 120) digitalWrite(pin, HIGH); if (x > 120) - digitalWrite(ledPin, HIGH); + digitalWrite(pin, HIGH); if (x > 120) { - digitalWrite(ledPin, HIGH); + digitalWrite(pin, HIGH); } However, the following two examples are different:: // example 1: two lines of code in the if body if (x > 120) { - digitalWrite(ledPin1, HIGH); - digitalWrite(ledPin2, HIGH); + digitalWrite(pin1, HIGH); + digitalWrite(pin2, HIGH); } // example 2: one line of code in the if body, and // another line of code after the if statement if (x > 120) - digitalWrite(ledPin1, HIGH); // this is in the if body - digitalWrite(ledPin2, HIGH); // this is NOT in the if body + digitalWrite(pin1, HIGH); // this is in the if body + digitalWrite(pin2, HIGH); // this is NOT in the if body In the first example, since the body is enclosed in curly braces, both lines are included. In the second example, since the curly braces are diff --git a/source/lang/cpp/int.rst b/source/lang/cpp/int.rst index 3e96b69..fa63946 100644 --- a/source/lang/cpp/int.rst +++ b/source/lang/cpp/int.rst @@ -28,10 +28,10 @@ dealing with the :ref:`bitshift right operator (>>) The ``long`` type is a synonym for ``int``. -Here is an example of declaring an ``int`` variable named ``ledPin``, +Here is an example of declaring an ``int`` variable named ``pin``, then giving it value 13:: - int ledPin = 13; + int pin = 13; The general syntax for declaring an ``int`` variable named ``var``, then giving it value ``val``, looks like:: diff --git a/source/lang/cpp/unsignedint.rst b/source/lang/cpp/unsignedint.rst index b7d9716..f8ea473 100644 --- a/source/lang/cpp/unsignedint.rst +++ b/source/lang/cpp/unsignedint.rst @@ -36,9 +36,9 @@ that an ``unsigned int`` will "underflow" at 0, and "overflow" at The ``unsigned long`` type is a synonym for ``unsigned int``. Here is an example of declaring an ``unsigned int`` variable named -``ledPin``, then giving it value 13:: +``pin``, then giving it value 13:: - unsigned int ledPin = 13; + unsigned int pin = 13; The general syntax for declaring an ``unsigned int`` variable named ``var``, then giving it value ``val``, looks like:: -- cgit v1.2.3 From cd9b275805d98f9fa20ae19a59c6c9cdadb39af8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 10 Jun 2011 10:04:06 -0400 Subject: Docs: Generalize throb()-related troubleshooting item. The FAQ entry which explains the throbbing LED behavior is insufficiently general. Rewrite it so users can tell that throbbing generally indicates a failed assertion or some other error. --- source/troubleshooting.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index b5f496e..3174f14 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -14,17 +14,15 @@ This page documents common problems and their solutions. Hardware problems =================== -The status LED is throbbing and I can't upload my program! ----------------------------------------------------------- +The LED is throbbing and my program is stopped! +----------------------------------------------- The LED throbs when there has been a failed software :ref:`assertion -`. +` or some other error. -You can still reprogram by resetting the board and uploading during -the short window when the bootloader waits for a program. - -To make this window longer (it can be hard to get the timing right), -use :ref:`perpetual bootloader mode +There are a few issues with the bootloader which mean you might not be +able to upload your program when this happens. You can still +reprogram by using :ref:`perpetual bootloader mode `. My board is bricked! I can't upload via the bootloader no matter what! -- cgit v1.2.3 From 3a5fcafcd6eadafa5ffadb30f4c2de6ecdf05023 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 10 Jun 2011 10:25:17 -0400 Subject: Docs: move ASSERT() to its own page. ASSERT() was previously documented in language.rst. Move it to a new lang/api/assert.rst. --- source/jtag.rst | 12 +++++------ source/lang/api/assert.rst | 30 ++++++++++++++++++++++++++ source/language.rst | 53 ++++++++++------------------------------------ source/timers.rst | 9 ++++---- source/troubleshooting.rst | 2 +- 5 files changed, 51 insertions(+), 55 deletions(-) create mode 100644 source/lang/api/assert.rst diff --git a/source/jtag.rst b/source/jtag.rst index 4151a53..0558a29 100644 --- a/source/jtag.rst +++ b/source/jtag.rst @@ -2,9 +2,8 @@ .. _jtag: -====== - JTAG -====== +JTAG +==== .. FIXME [0.1.0] Updated adapter schematic, better information @@ -17,10 +16,9 @@ and hardware peripherals (we use it when working on :ref:`libmaple `) or to flash a new bootloader. Note that the STM32 on the Maple has a built-in low level serial -debugger which could also be used to flash bootloaders, and that the -:ref:`ASSERT ` framework allows basic debugging over -a USART serial channel. We expect only fairly advanced users to use -this feature. +debugger which could also be used to flash bootloaders, and +:ref:`lang-assert` allows basic debugging over a USART serial channel. +We expect only fairly advanced users to use this feature. .. contents:: Contents :local: diff --git a/source/lang/api/assert.rst b/source/lang/api/assert.rst new file mode 100644 index 0000000..76330b6 --- /dev/null +++ b/source/lang/api/assert.rst @@ -0,0 +1,30 @@ +.. highlight:: cpp + +.. _lang-assert: + +``ASSERT(...)`` +=============== + +ASSERT() can be very useful for basic program debugging. It accepts a +boolean; for example:: + + ASSERT(state == WAIT); + +Zero is false and any other number is true. If the boolean is true, +the assertion passes and the program continues as usual. If it is +false, the assertion fails: the program is halted, debug information +is printed to USART2, and the status LED begins to throb (it's +noticeably different from blinking). The debug information is printed +at 9600 baud and consists of the filename and line number where the +ASSERT() failed. + +Including assertions in a program increases the program size. When +using libmaple **from the command line only**, they can be disabled by +making the definition :: + + #define DEBUG_LEVEL DEBUG_NONE + +before including either wirish.h or libmaple.h. In this case, all +assertions will pass without any lost clock cycles. Note that this +will **not work in the IDE**; even with this definition, assertions +will still be enabled. diff --git a/source/language.rst b/source/language.rst index 3ecbe43..be085f2 100644 --- a/source/language.rst +++ b/source/language.rst @@ -12,8 +12,7 @@ language used to program the `Arduino `_ boards. .. TODO [0.2.0?] Wiring tutorial -C or C++ programmers curious about the differences between the Wiring -language and C++ may wish to skip to the +C or C++ programmers may wish to skip to the :ref:`arduino_c_for_c_hackers`. .. contents:: Contents @@ -21,8 +20,7 @@ language and C++ may wish to skip to the .. admonition:: **Looking for Something Else?** - - See the :ref:`libraries` for extra built-in libraries for dealing - with different kinds of hardware. + - See the :ref:`libraries` for extra built-in libraries. - If you're looking for something from the C standard library (like ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler @@ -31,17 +29,17 @@ language and C++ may wish to skip to the use of any of its header files. However, dynamic memory allocation (``malloc()``, etc.) is not available. - - If you're looking for pointers to low-level details, see this page's - :ref:`Recommended Reading `. + - If you're looking for pointers to low-level details, see + :ref:`libmaple` and this page's :ref:`Recommended Reading + `. .. _language-lang-docs: Maple Language Reference ------------------------ -The following table summarizes the most important core language -features. An exhaustive index is available at the -:ref:`language-index`. +This table is a summary of the most important language features. See +the :ref:`language-index` for a complete listing. +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | @@ -68,7 +66,7 @@ features. An exhaustive index is available at the | | | | |* :ref:`continue ` |**Data Types** |* :ref:`analogRead() ` | | | | | -|* :ref:`return ` | The size of each datatype, in bytes, is |* :ref:`pwmWrite() ` | +|* :ref:`return ` | The size of each data type, in bytes, is |* :ref:`pwmWrite() ` | | | given in parentheses where appropriate. | (:ref:`analogWrite() ` is | |* :ref:`goto ` | | also available, though its use is discouraged) | | | *Note*: The ``word`` type is (deliberately) | | @@ -144,7 +142,7 @@ features. An exhaustive index is available at the | | | | |* :ref:`& reference operator |* :ref:`sizeof() ` |* :ref:`bitClear() ` | | ` | | | -| | |* :ref:`bit() ` | +| |* :ref:`ASSERT() ` |* :ref:`bit() ` | | | | | |**Bitwise Operators** | | | | | |**External Interrupts** | @@ -205,35 +203,6 @@ features. An exhaustive index is available at the | | | | +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ -.. _language-assert: - -``ASSERT(...)`` ---------------- - -The ``ASSERT()`` function can be very useful for basic program -debugging. It accepts a boolean; for example:: - - ASSERT(state == WAIT); - -Zero is false and any other number is true. If the boolean is true, the -assertion passes and the program continues as usual. If it is false, -the assertion fails: the program is halted, debug information is -printed to USART2, and the status LED begins to throb in intensity -(it's noticeably different from blinking). The debug information is -printed at 9600 baud and consists of the filename and line number -where the particular assertion failed. - -Including assertions in a program increases the program size. When -using libmaple **from the command line only**, they can be disabled by -making the definition :: - - #define DEBUG_LEVEL DEBUG_NONE - -before including either wirish.h or libmaple.h. In this case, all -assertions will pass without any lost clock cycles. Note that this -will **not work in the IDE**; even with this definition, assertions -will still be enabled. - .. _language-missing-features: Missing Arduino Features @@ -301,7 +270,7 @@ Note for C/C++ Hackers This is a note for programmers comfortable with C or C++ who want a better understanding of the differences between C++ and the Wiring -language. +language. The good news is that the differences are relatively few; Wiring is just a thin wrapper around C++. Some potentially better news is that @@ -378,7 +347,7 @@ behaves roughly like:: // Call user loop() forever. while (true) { - loop(); + loop(); } } diff --git a/source/timers.rst b/source/timers.rst index e23579d..b6c0886 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -66,11 +66,10 @@ Working with timers and interrupts can be tricky; they are a somewhat "advanced" topic. The following subsections explain some common problems associated with using timers and timer interrupts. -In general: start simple, test with :ref:`ASSERT() `, -and don't try to do too much in your interrupt handlers! Make sure -that what you're trying to do in a handler isn't going to block other -interrupts from firing, if those other interrupts are important for -your program. +In general: start simple, test with :ref:`lang-assert`, and don't try +to do too much in your interrupt handlers! Make sure that what you're +trying to do in a handler isn't going to block other interrupts from +firing, if those other interrupts are important for your program. .. _timers-pwm-conflicts: diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 3174f14..b679b9c 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -18,7 +18,7 @@ The LED is throbbing and my program is stopped! ----------------------------------------------- The LED throbs when there has been a failed software :ref:`assertion -` or some other error. +` or some other error. There are a few issues with the bootloader which mean you might not be able to upload your program when this happens. You can still -- cgit v1.2.3 From 12a146df4f1a2cd4e83869a610562a83a96027de Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 10 Jun 2011 10:37:42 -0400 Subject: Docs: Update "my board is bricked!" troubleshooting item. --- source/troubleshooting.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index b679b9c..da6fb40 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -28,11 +28,18 @@ reprogram by using :ref:`perpetual bootloader mode My board is bricked! I can't upload via the bootloader no matter what! ---------------------------------------------------------------------- -Use the hardcoded serial STM32 serial bootloader to :ref:`re-flash the -bootloader `. +Don't panic. First, make sure that the board is plugged in correctly +for program upload, using the instructions given in the +:ref:`quickstart `. If that doesn't work, +try using :ref:`perpetual bootloader mode +`. + +If that doesn't work, then you've got a problem. All is not lost, +however! You can always try to :ref:`re-flash the bootloader +` over serial (or :ref:`JTAG `). -If it really is bricked, and you think it's our fault, `contact us -`_\ ! +If your board really is bricked, and you think it's our fault, +`contact us `_\ ! My 5v peripheral doesn't work! (I2C, SPI, USART, etc) ----------------------------------------------------- -- cgit v1.2.3 From 810d5c0b6bf3d254c8c85a6217c7ef3413c2370d Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 10 Jun 2011 10:42:36 -0400 Subject: Docs: Update quickstart for Mini. --- source/maple-quickstart.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 38b7fff..976eecf 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -73,14 +73,16 @@ window, and then a confirmation message will appear: Upload that program! -------------------- -.. FIXME [0.1.0 Maple-specific image; add one for Native] - -Now it's time to plug in your Maple. Use a Mini-B cable, making sure -that the :ref:`power source jumper ` is on the USB -header first. We ship Maples with the power source jumper configured -that way, so you shouldn't have to do anything. For reference, it -should look like this (don't worry if a jumper is hanging half off of -the CHRG header): +.. FIXME [Maple Native: add note about power select jumper] + +Now it's time to plug in your Maple. Use a USB Mini-B cable (mini, +not micro). + +On the Maple, make sure that the :ref:`power source jumper +` is on the USB header first. We ship Maples with the +power source jumper configured that way, so you shouldn't have to do +anything. For reference, it should look like this (don't worry if a +jumper is hanging half off of the CHRG header): .. image:: /_static/img/plugged-in-maple.png :align: center -- cgit v1.2.3 From 4e0c342d149e5da664ae7c573b9ea3b14df4db83 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 10 Jun 2011 23:24:32 -0400 Subject: Docs: Add GPIO port pin maps. --- source/hardware/maple-mini.rst | 27 +++++++++++++++++++++++++++ source/hardware/maple-ret6.rst | 28 ++++++++++++++++++++++++++++ source/hardware/maple.rst | 28 ++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index dfad559..b142e77 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -135,6 +135,33 @@ the pin is :ref:`5 volt tolerant `. D32, PB8, -, 4_CH3, -, -, -, Yes D33, PB1, CH9, 3_CH4, -, -, -, - +.. _maple-mini-gpio-port-map: + +GPIO Port Pin Map +^^^^^^^^^^^^^^^^^ +The following table shows what pins are associated with each +:ref:`GPIO port `. + +.. csv-table:: + :header: GPIOA, GPIOB, GPIOC + + PA0: D11, PB0: D3, PC0: - + PA1: D10, PB1: D33, PC1: - + PA2: D9, PB2: D2, PC2: - + PA3: D8, PB3: D19, PC3: - + PA4: D7, PB4: D18, PC4: - + PA5: D6, PB5: D17, PC5: - + PA6: D5, PB6: D16, PC6: - + PA7: D4, PB7: D15, PC7: - + PA8: D27, PB8: D32, PC8: - + PA9: D26, PB9: -, PC9: - + PA10: D25, PB10: D1, PC10: - + PA11: D24, PB11: D0, PC11: - + PA12: D23, PB12: D31, PC12: - + PA13: D22, PB13: D30, PC13: D14 + PA14: D21, PB14: D29, PC14: D13 + PA15: D20, PB15: D28, PC15: D12 + .. _maple-mini-timer-map: Timer Pin Map diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index d419d62..1de2465 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -153,6 +153,34 @@ not the pin is :ref:`5 volt tolerant `. D41, PA15, -, -, -, -, 3_NSS, Yes D42, PB3, -, -, -, -, 3_SCK, Yes +.. _maple-ret6-gpio-port-map: + +GPIO Port Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows what pins are associated with each +:ref:`GPIO port `. + +.. csv-table:: + :header: GPIOA, GPIOB, GPIOC + + PA0: D2, PB0: D27, PC0: D15 + PA1: D3, PB1: D28, PC1: D16 + PA2: D1, PB2: -, PC2: D17 + PA3: D0, PB3: D42, PC3: D18 + PA4: D10, PB4: D43, PC4: D19 + PA5: D13, PB5: D4, PC5: D20 + PA6: D12, PB6: D5, PC6: D35 + PA7: D11, PB7: D9, PC7: D36 + PA8: D6, PB8: D14, PC8: D37 + PA9: D7, PB9: D24, PC9: D38 + PA10: D8, PB10: D29, PC10: D26 + PA11: -, PB11: D30, PC11: - + PA12: -, PB12: D31, PC12: - + PA13: D39, PB13: D32, PC13: D21 + PA14: D40, PB14: D33, PC14: D22 + PA15: D41, PB15: D34, PC15: D23 + .. _maple-ret6-timer-map: Timer Pin Map diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index a06c222..91198f2 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -202,6 +202,34 @@ not the pin is :ref:`5 volt tolerant `. D41, PA15, -, -, -, -, -, Yes D42, PB3, -, -, -, -, -, Yes +.. _maple-gpio-port-map: + +GPIO Port Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows what pins are associated with each +:ref:`GPIO port `. + +.. csv-table:: + :header: GPIOA, GPIOB, GPIOC + + PA0: D2, PB0: D27, PC0: D15 + PA1: D3, PB1: D28, PC1: D16 + PA2: D1, PB2: -, PC2: D17 + PA3: D0, PB3: D42, PC3: D18 + PA4: D10, PB4: D43, PC4: D19 + PA5: D13, PB5: D4, PC5: D20 + PA6: D12, PB6: D5, PC6: D35 + PA7: D11, PB7: D9, PC7: D36 + PA8: D6, PB8: D14, PC8: D37 + PA9: D7, PB9: D24, PC9: D38 + PA10: D8, PB10: D29, PC10: D26 + PA11: -, PB11: D30, PC11: - + PA12: -, PB12: D31, PC12: - + PA13: D39, PB13: D32, PC13: D21 + PA14: D40, PB14: D33, PC14: D22 + PA15: D41, PB15: D34, PC15: D23 + .. _maple-timer-map: Timer Pin Map -- cgit v1.2.3 From 97a63a4d6ea57ed39f82d60529b2fef01d8eed35 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 11 Jun 2011 20:21:59 -0400 Subject: Initial version separate leaflabs-docs repository. This repository previously lived in the libmaple/ repository, but that didn't make much sense, since it covers Maple IDE as well. --- .gitignore | 1 + Doxyfile | 1639 -------------------------------------------------------- Makefile | 39 +- README | 55 +- source/conf.py | 6 +- 5 files changed, 62 insertions(+), 1678 deletions(-) create mode 100644 .gitignore delete mode 100644 Doxyfile diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..567609b --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/Doxyfile b/Doxyfile deleted file mode 100644 index a441c4f..0000000 --- a/Doxyfile +++ /dev/null @@ -1,1639 +0,0 @@ -# Doxyfile 1.7.1 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all -# text before the first occurrence of this tag. Doxygen uses libiconv (or the -# iconv built into libc) for the transcoding. See -# http://www.gnu.org/software/libiconv for the list of possible encodings. - -DOXYFILE_ENCODING = UTF-8 - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = libmaple - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = custom-build - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = ./doxygen - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, -# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English -# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, -# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, -# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. - -OUTPUT_LANGUAGE = English - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = "The $name class" \ - "The $name widget" \ - "The $name file" \ - is \ - provides \ - specifies \ - contains \ - represents \ - a \ - an \ - the - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = YES - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments -# (thus requiring an explicit @brief command for a brief description.) - -JAVADOC_AUTOBRIEF = YES - -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) - -QT_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 4 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = "sideeffect=\par Side Effects:\n" - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = YES - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for -# Java. For instance, namespaces will be presented as packages, qualified -# scopes will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources only. Doxygen will then generate output that is more tailored for -# Fortran. - -OPTIMIZE_FOR_FORTRAN = NO - -# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for -# VHDL. - -OPTIMIZE_OUTPUT_VHDL = NO - -# Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given extension. -# Doxygen has a built-in mapping, but you can override or extend it using this -# tag. The format is ext=language, where ext is a file extension, and language -# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, -# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions -# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. - -EXTENSION_MAPPING = - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -BUILTIN_STL_SUPPORT = NO - -# If you use Microsoft's C++/CLI language, you should set this option to YES to -# enable parsing support. - -CPP_CLI_SUPPORT = NO - -# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. -# Doxygen will parse them like normal C++ but will assume all classes use public -# instead of private inheritance when no explicit protection keyword is present. - -SIP_SUPPORT = NO - -# For Microsoft's IDL there are propget and propput attributes to indicate getter -# and setter methods for a property. Setting this option to YES (the default) -# will make doxygen to replace the get and set methods by a property in the -# documentation. This will only work if the methods are indeed getting or -# setting a simple type. If this is not the case, or you want to show the -# methods anyway, you should set this option to NO. - -IDL_PROPERTY_SUPPORT = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum -# is documented as struct, union, or enum with the name of the typedef. So -# typedef struct TypeS {} TypeT, will appear in the documentation as a struct -# with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically -# be useful for C code in case the coding convention dictates that all compound -# types are typedef'ed and only the typedef is referenced, never the tag name. - -TYPEDEF_HIDES_STRUCT = YES - -# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to -# determine which symbols to keep in memory and which to flush to disk. -# When the cache is full, less often used symbols will be written to disk. -# For small to medium size projects (<1000 input files) the default value is -# probably good enough. For larger projects a too small cache size can cause -# doxygen to be busy swapping symbols to and from disk most of the time -# causing a significant performance penality. -# If the system has enough physical memory increasing the cache will improve the -# performance by keeping more symbols in memory. Note that the value works on -# a logarithmic scale so increasing the size by one will rougly double the -# memory usage. The cache size is given by this formula: -# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, -# corresponding to a cache size of 2^16 = 65536 symbols - -SYMBOL_CACHE_SIZE = 0 - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = NO - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = YES - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If this flag is set to YES, the members of anonymous namespaces will be -# extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base -# name of the file that contains the anonymous namespace. By default -# anonymous namespace are hidden. - -EXTRACT_ANON_NSPACES = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = NO - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen -# will list include files with double quotes in the documentation -# rather than with sharp brackets. - -FORCE_LOCAL_INCLUDES = NO - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen -# will sort the (brief and detailed) documentation of class members so that -# constructors and destructors are listed first. If set to NO (the default) -# the constructors will appear in the respective orders defined by -# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. -# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO -# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. - -SORT_MEMBERS_CTORS_1ST = YES - -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the -# hierarchy of group names into alphabetical order. If set to NO (the default) -# the group names will appear in their defined order. - -SORT_GROUP_NAMES = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = NO - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = NO - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is NO. - -SHOW_DIRECTORIES = YES - -# Set the SHOW_FILES tag to NO to disable the generation of the Files page. -# This will remove the Files entry from the Quick Index and from the -# Folder Tree View (if specified). The default is YES. - -SHOW_FILES = YES - -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the -# Namespaces page. This will remove the Namespaces entry from the Quick Index -# and from the Folder Tree View (if specified). The default is YES. - -SHOW_NAMESPACES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from -# the version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed -# by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. The create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. -# You can optionally specify a file name after the option, if omitted -# DoxygenLayout.xml will be used as the name of the layout file. - -LAYOUT_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = YES - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = YES - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = YES - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = "$file:$line: $text" - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = ../libmaple/ \ - ../wirish/ \ - ../libraries/ - -# This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is -# also the default input encoding. Doxygen uses libiconv (or the iconv built -# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for -# the list of possible encodings. - -INPUT_ENCODING = UTF-8 - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 - -FILE_PATTERNS = *.h *.c - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = YES - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -# FIXME The USB thing needs to get redone (ST code stripped out, -# etc.). Until then, just ignore it. -EXCLUDE = ../libmaple/usb/ - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names -# (namespaces, classes, functions, etc.) that should be excluded from the -# output. The symbol name can be a fully qualified name, a word, or if the -# wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test - -EXCLUDE_SYMBOLS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = * - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = NO - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = YES - -# If the REFERENCED_BY_RELATION tag is set to YES -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = NO - -# If the REFERENCES_RELATION tag is set to YES -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = NO - -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. Otherwise they will link to the documentation. - -REFERENCES_LINK_SOURCE = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = - -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. -# Doxygen will adjust the colors in the stylesheet and background images -# according to this color. Hue is specified as an angle on a colorwheel, -# see http://en.wikipedia.org/wiki/Hue for more information. -# For instance the value 0 represents red, 60 is yellow, 120 is green, -# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. -# The allowed range is 0 to 359. - -HTML_COLORSTYLE_HUE = 220 - -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of -# the colors in the HTML output. For a value of 0 the output will use -# grayscales only. A value of 255 will produce the most vivid colors. - -HTML_COLORSTYLE_SAT = 100 - -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to -# the luminance component of the colors in the HTML output. Values below -# 100 gradually make the output lighter, whereas values above 100 make -# the output darker. The value divided by 100 is the actual gamma applied, -# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, -# and 100 does not change the gamma. - -HTML_COLORSTYLE_GAMMA = 80 - -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting -# this to NO can help when comparing the output of multiple runs. - -HTML_TIMESTAMP = YES - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML -# documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). - -HTML_DYNAMIC_SECTIONS = NO - -# If the GENERATE_DOCSET tag is set to YES, additional index files -# will be generated that can be used as input for Apple's Xcode 3 -# integrated development environment, introduced with OSX 10.5 (Leopard). -# To create a documentation set, doxygen will generate a Makefile in the -# HTML output directory. Running make will produce the docset in that -# directory and running "make install" will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find -# it at startup. -# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. - -GENERATE_DOCSET = NO - -# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the -# feed. A documentation feed provides an umbrella under which multiple -# documentation sets from a single provider (such as a company or product suite) -# can be grouped. - -DOCSET_FEEDNAME = "Doxygen generated docs" - -# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that -# should uniquely identify the documentation set bundle. This should be a -# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen -# will append .docset to the name. - -DOCSET_BUNDLE_ID = org.doxygen.Project - -# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify -# the documentation publisher. This should be a reverse domain-name style -# string, e.g. com.mycompany.MyDocSet.documentation. - -DOCSET_PUBLISHER_ID = org.doxygen.Publisher - -# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. - -DOCSET_PUBLISHER_NAME = Publisher - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING -# is used to encode HtmlHelp index (hhk), content (hhc) and project file -# content. - -CHM_INDEX_ENCODING = - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated -# that can be used as input for Qt's qhelpgenerator to generate a -# Qt Compressed Help (.qch) of the generated HTML documentation. - -GENERATE_QHP = NO - -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can -# be used to specify the file name of the resulting .qch file. -# The path specified is relative to the HTML output folder. - -QCH_FILE = - -# The QHP_NAMESPACE tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#namespace - -QHP_NAMESPACE = org.doxygen.Project - -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#virtual-folders - -QHP_VIRTUAL_FOLDER = doc - -# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to -# add. For more information please see -# http://doc.trolltech.com/qthelpproject.html#custom-filters - -QHP_CUST_FILTER_NAME = - -# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see -# -# Qt Help Project / Custom Filters. - -QHP_CUST_FILTER_ATTRS = - -# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's -# filter section matches. -# -# Qt Help Project / Filter Attributes. - -QHP_SECT_FILTER_ATTRS = - -# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can -# be used to specify the location of Qt's qhelpgenerator. -# If non-empty doxygen will try to run qhelpgenerator on the generated -# .qhp file. - -QHG_LOCATION = - -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files -# will be generated, which together with the HTML files, form an Eclipse help -# plugin. To install this plugin and make it available under the help contents -# menu in Eclipse, the contents of the directory containing the HTML and XML -# files needs to be copied into the plugins directory of eclipse. The name of -# the directory within the plugins directory should be the same as -# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before -# the help appears. - -GENERATE_ECLIPSEHELP = NO - -# A unique identifier for the eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have -# this name. - -ECLIPSE_DOC_ID = org.doxygen.Project - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. -# If the tag value is set to YES, a side panel will be generated -# containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). -# Windows users are probably better off using the HTML help feature. - -GENERATE_TREEVIEW = NO - -# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, -# and Class Hierarchy pages using a tree view instead of an ordered list. - -USE_INLINE_TREES = NO - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open -# links to external symbols imported via tag files in a separate window. - -EXT_LINKS_IN_WINDOW = NO - -# Use this tag to change the font size of Latex formulas included -# as images in the HTML documentation. The default is 10. Note that -# when you change the font size after a successful doxygen run you need -# to manually remove any form_*.png images from the HTML output directory -# to force them to be regenerated. - -FORMULA_FONTSIZE = 10 - -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are -# not supported properly for IE 6.0, but are supported on all modern browsers. -# Note that when changing this option you need to delete any form_*.png files -# in the HTML output before the changes have effect. - -FORMULA_TRANSPARENT = YES - -# When the SEARCHENGINE tag is enabled doxygen will generate a search box -# for the HTML output. The underlying search engine uses javascript -# and DHTML and should work on any modern browser. Note that when using -# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets -# (GENERATE_DOCSET) there is already a search function so this one should -# typically be disabled. For large projects the javascript based search engine -# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. - -SEARCHENGINE = YES - -# When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a PHP enabled web server instead of at the web client -# using Javascript. Doxygen will generate the search PHP script and index -# file to put on the web server. The advantage of the server -# based approach is that it scales better to large projects and allows -# full text search. The disadvances is that it is more difficult to setup -# and does not have live searching capabilities. - -SERVER_BASED_SEARCH = NO - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = latex - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. -# Note that when enabling USE_PDFLATEX this option is only used for -# generating bitmaps for formulas in the HTML output, but not in the -# Makefile that is written to the output directory. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = a4wide - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = YES - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = YES - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -# If LATEX_SOURCE_CODE is set to YES then doxygen will include -# source code with syntax highlighting in the LaTeX output. -# Note that which sources are shown also depends on other settings -# such as SOURCE_BROWSER. - -LATEX_SOURCE_CODE = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = rtf - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = man - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = .3 - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = YES - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = YES - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = YES - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = __attribute__()= \ - __cplusplus \ - STM32_MEDIUM_DENSITY - STM32_HIGH_DENSITY - STM32_XL_DENSITY - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = NO - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = /usr/bin/perl - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = NO - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see -# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = YES - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = NO - -# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is -# allowed to run in parallel. When set to 0 (the default) doxygen will -# base this on the number of processors available in the system. You can set it -# explicitly to a value larger than 0 to get control over the balance -# between CPU load and processing speed. - -DOT_NUM_THREADS = 0 - -# By default doxygen will write a font called FreeSans.ttf to the output -# directory and reference it in all dot files that doxygen generates. This -# font does not include all possible unicode characters however, so when you need -# these (or just want a differently looking font) you can specify the font name -# using DOT_FONTNAME. You need need to make sure dot is able to find the font, -# which can be done by putting it in a standard location or by setting the -# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory -# containing the font. - -DOT_FONTNAME = FreeSans.ttf - -# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. -# The default size is 10pt. - -DOT_FONTSIZE = 10 - -# By default doxygen will tell dot to use the output directory to look for the -# FreeSans.ttf font (which doxygen will put there itself). If you specify a -# different font using DOT_FONTNAME you can set the path where dot -# can find it using this tag. - -DOT_FONTPATH = - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = NO - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = NO - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = NO - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = NO - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT options are set to YES then -# doxygen will generate a call dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable call graphs -# for selected functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then -# doxygen will generate a caller dependency graph for every global function -# or class method. Note that enabling this option will significantly increase -# the time of a run. So in most cases it will be better to enable caller -# graphs for selected functions only using the \callergraph command. - -CALLER_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of -# nodes that will be shown in the graph. If the number of nodes in a graph -# becomes larger than this value, doxygen will truncate the graph, which is -# visualized by representing a node as a red box. Note that doxygen if the -# number of direct children of the root node in a graph is already larger than -# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note -# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. - -DOT_GRAPH_MAX_NODES = 50 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that the size of a graph can be further restricted by -# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not -# seem to support this out of the box. Warning: Depending on the platform used, -# enabling this option may lead to badly anti-aliased labels on the edges of -# a graph (i.e. they become hard to read). - -DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES diff --git a/Makefile b/Makefile index eb14c90..5255525 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ -# Makefile for Sphinx documentation -# +# Makefile for LeafLabs documentation (automatically generated by +# Sphinx). # You can set these variables from the command line. SPHINXOPTS = @@ -12,7 +12,7 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest doxygen +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest help: @echo "Please use \`make ' where is one of" @@ -41,33 +41,33 @@ html: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -dirhtml: doxygen +dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -singlehtml: doxygen +singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." -pickle: doxygen +pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." -json: doxygen +json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." -htmlhelp: doxygen +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: doxygen +qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ @@ -76,7 +76,7 @@ qthelp: doxygen @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/libmaple.qhc" -devhelp: doxygen +devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @@ -85,49 +85,50 @@ devhelp: doxygen @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/libmaple" @echo "# devhelp" -epub: doxygen +epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." -latex: doxygen +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: doxygen +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." -text: doxygen +text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." -man: doxygen +man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." -changes: doxygen +changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." -linkcheck: doxygen +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: doxygen +doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." doxygen: - doxygen + @echo "Wrong! You need to run this from within libmaple!" + false diff --git a/README b/README index 7a50a54..2ed141b 100644 --- a/README +++ b/README @@ -1,9 +1,27 @@ -This directory contains source files used to generate libmaple's -documentation. +Introduction +------------ -The generated documentation for the latest libmaple release is -available online in HTML form at http://leaflabs.com/docs/. The web -interface is the recommended way for users to read the documentation. +This directory contains reStructuredText (reST) source files used to +generate the documentation for LeafLabs' libmaple and Maple IDE +projects. For more information on these projects, see their GitHub +pages: + + https://github.com/leaflabs/libmaple + https://github.com/leaflabs/maple-ide + +While the two projects are developed separately, they are released in +lockstep, and Maple IDE depends upon libmaple. (libmaple doesn't +depend on Maple IDE). + +The generated documentation for the latest libmaple and Maple IDE +release is available online in HTML form: + + http://leaflabs.com/docs/ + +The web interface is the recommended way for users to read the +documentation. Older versions are available as well: + + http://static.leaflabs.com/pub/leaflabs/maple-docs/ This file contains instructions for generating the HTML files. @@ -16,7 +34,7 @@ The docs are written in Sphinx's extensions to reStructuredText http://sphinx.pocoo.org/tutorial.html Much of the documentation is pulled out of the libmaple source code; -we use Doxygen XML output into Sphinx documentation. You can read +we pull Doxygen's XML output into Sphinx documentation. You can read more about Doxygen here: http://doxygen.org @@ -67,12 +85,12 @@ the HTML documentation. 4. Before the first time you run Sphinx (and any time the Doxygen comments in the libmaple source code are changed), you'll need to - build the Doxygen XML output: + rebuild libmaple's Doxygen XML output. That is, from within the + libmaple (i.e., NOT THIS REPOSITORY), run: - $ cd libmaple/docs/source - $ doxygen + $ make doxygen -5. Finally, you can build the documentation: +5. Finally, you can build the documentation (in this folder): $ make html @@ -83,16 +101,19 @@ Reading and Modifying the Documentation Just point your web browser at the file - /docs/build/html/index.html + build/html/index.html It corresponds to the Sphinx file - /docs/source/index.rst + source/index.rst + +Read more about Sphinx and chase pointers within the docs source to +find out more. -The file /docs/source/conf.py is the Sphinx configuration file; you -can go read it for more information about our setup. +The file source/conf.py is the Sphinx configuration file; you can go +read it for more information about our setup. All of the documentation which isn't pulled out of source code -comments lives in /docs/source/. The directory /docs/source/_static/ -is for static content (like style sheets); /docs/source/_templates/ -contains Sphinx templates. +comments lives in source/. The directory source/_static/ is for +static content (like style sheets); source/_templates/ is meant to +contain Sphinx templates. diff --git a/source/conf.py b/source/conf.py index 005a988..dce9d1b 100644 --- a/source/conf.py +++ b/source/conf.py @@ -20,8 +20,8 @@ import sys, os # documentation root, use os.path.abspath to make it absolute, like shown here. # # We rely on Michael Jones's breathe as a Doxygen-to-Sphinx bridge. -# See libmaple/docs/README for information on obtaining it and letting -# Sphinx know where it is. +# See the README for information on obtaining it and letting Sphinx +# know where it is. sys.path.append(os.environ['BREATHE_HOME']) # -- General configuration ---------------------------------------------------- @@ -269,6 +269,6 @@ intersphinx_mapping = {'http://docs.python.org/': None} # -- Options for breathe integration ------------------------------------------ breathe_projects = {'libmaple' : os.path.join(os.environ['LIB_MAPLE_HOME'], - 'docs', 'doxygen', 'xml')} + 'doxygen', 'xml')} breathe_default_project = 'libmaple' -- cgit v1.2.3 From 2134210f6e269f60c0a8034bcb57b276545617f2 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 11 Jun 2011 20:47:54 -0400 Subject: ide: Document further, reorganize. Move screenshot down into its own section. Add table of contents. Reorganize toolbar button descriptions as subsections of a new section dedicated to the purpose. Add a stub about getting to the examples. --- source/ide.rst | 116 +++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 72 insertions(+), 44 deletions(-) diff --git a/source/ide.rst b/source/ide.rst index b3ef653..58dca1c 100644 --- a/source/ide.rst +++ b/source/ide.rst @@ -11,116 +11,135 @@ The :ref:`Maple Quickstart ` is another good source of information on the IDE; it is especially useful for setting up a computer for the first time. +.. contents:: Contents + :local: + +IDE Windows +----------- + +The following screenshot shows the appearance of a Maple IDE window: + .. figure:: /_static/img/ide-blinky.png :align: center :alt: Maple IDE +Note the toolbar buttons at the top; they're the icons with circles or +squares around them. You can program your board mostly through the +use of these buttons, which are described in the next section. + +Toolbar Buttons +--------------- + .. _ide-verify: Verify ------- +~~~~~~ .. image:: /_static/img/button-verify.png :align: left -Click Verify to compile the current sketch. +Click Verify to compile the current sketch. This will process your +program and produce an executable which can run on your board. .. _ide-stop: Stop ----- +~~~~ .. image:: /_static/img/button-stop.png :align: left -Click Stop to cancel a compilation. +Click Stop to cancel a compilation. Longer programs may take a while +to compile. Clicking Stop will let you go back to writing code +without having to wait for compilation to finish. .. _ide-new: New ---- +~~~ .. image:: /_static/img/button-new.png :align: left -Click New to begin a fresh sketch. +Click New to make a fresh sketch. .. _ide-open: Open ----- +~~~~ .. image:: /_static/img/button-open.png :align: left -Click Open to open a new sketch. By default, this will look in you -*sketchbook*, which is a directory on your system which contains all -of your sketches. The default directory of your sketchbook varies by -operating system; you can change it in the IDE preferences. +Click Open to open an existing sketch. Maple IDE will first look for +the sketch in your *sketchbook*, which is a folder on your computer +that contains your sketches. The sketchbook is stored in different +places depending on your operating system. You can change its +location in the IDE's preferences. .. _ide-save: Save ----- +~~~~ .. image:: /_static/img/button-save.png :align: left -Click Save to save the currently opened sketch. +Click Save to save the currently opened sketch. This will save all +open tabs, not just the one you're currently looking at. .. _ide-upload: Upload ------- +~~~~~~ .. image:: /_static/img/button-upload.png :align: left Click Upload to send the compiled sketch to your Maple to run. Before you click Upload, you must have a memory location and serial port -selected. The memory location, either Flash or RAM, determines -whether the compiled sketch binary will be stored on the Maple. You -can choose this using the Tools > Board menu. The serial port -corresponds to the Serial-over-USB connection the Maple has -established with your computer. This looks like "COM1", "COM2", -etc. on Windows, "/dev/tty.usbmodemXXX" on Mac (where "XXX" is some -sequence of letters and numbers), or "/dev/ttyACMXXX" on Linux (again, -where "XXX" is some sequence of letters and numbers). You can choose -a serial port using the Tools > Serial Port menu. - -If you click Upload without having made these choices; The IDE -*should* prompt you to do so. However, if you're trying to upload and -are unsuccessful, make sure you've made choices for both board and -serial port. - -For more help, the upload process is documented in more detail (with -screenshots) in the :ref:`quickstart `. +selected. + +The memory location, either Flash or RAM, determines whether the +compiled sketch binary will be stored on the Maple. You can choose +this using the Tools > Board menu. + +The serial port corresponds to the :ref:`SerialUSB ` +connection the Maple establishes with your computer. This looks like +"COM1", "COM2", etc. on Windows, "/dev/tty.usbmodemXXX" on Mac (where +"XXX" is some sequence of letters and numbers), or "/dev/ttyACMXXX" on +Linux (again, where "XXX" is some sequence of letters and numbers). +You can choose a serial port using the Tools > Serial Port menu. + +If you're trying to upload and are unsuccessful, make sure you've made +choices for both board and serial port. More help on uploading +(including screenshots) is available in the :ref:`quickstart +`. If all else fails, try putting your Maple in :ref:`perpetual bootloader mode ` before -uploading. - -In any case, you can always find us on the `forum`_ or `contact us -directly`_. +uploading. You can always find us on the `forum`_ or `contact us +directly`_ for help on any problems you're having. .. _ide-serial-monitor: Serial Monitor --------------- +~~~~~~~~~~~~~~ .. image:: /_static/img/button-serial-monitor.png :align: left -Click Serial Monitor to open up a communications channel between your -PC and the Maple's :ref:`Serial-over-USB ` -(``SerialUSB``) virtual serial port. +Click Serial Monitor to open up a communication channel between your +PC and the Maple's :ref:`SerialUSB ` virtual serial +port. If the serial monitor is open, any information sent to the computer -(e.g. using :ref:`SerialUSB.println() ` will -be displayed in the large text area. You can send data to the Maple -(to be read with e.g. :ref:`SerialUSB.read() `) -by typing into the small text box and either hitting the Enter key or -pressing the Send button. +(for example, using :ref:`SerialUSB.println() +`) will be displayed in the large text area. +You can send data to the Maple by typing into the small text box and +either hitting the Enter key or pressing the Send button. (The Maple +can read the data you send with :ref:`SerialUSB.read() +`). Here is an example serial monitor session with the InteractiveTest sketch (which you can load in the IDE by choosing menu item File > @@ -134,3 +153,12 @@ This is the result of typing "?" in the text box and clicking Send. If you click :ref:`Upload ` while the serial monitor is open, the IDE will close it for you before proceeding with the upload. + +.. _ide-examples: + +Example Code +------------ + +Maple IDE comes with a variety of sample code you can use to help you +get started writing your own programs. To load an example in a new +Maple IDE window, choose one from the submenus under File > Examples. -- cgit v1.2.3 From a66d251c68707b85cd91a8b9fcb19b73f4a8e559 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 11 Jun 2011 20:58:20 -0400 Subject: adc: Add a beginner-friendly introductory section. --- source/adc.rst | 68 +++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/source/adc.rst b/source/adc.rst index 18c54ab..2cf9018 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -4,33 +4,59 @@ ADC ===== -Analog-Digital Conversion is the process of reading a physical voltage -as a number. The Maple has a large number of pins which are capable of -taking 12-bit ADC measurements, which means that voltages from 0 to -3.3V are read as numbers from 0 to 4095. This corresponds to a -theoretical sensitivity of just under 1 millivolt. In reality, a -number of factors introduce noise and bias into this reading, and a -number of techniques must be used to get good precision and accuracy. +Analog to digital conversion is the process of reading a physical +voltage as a number. Maple can convert voltages between 0 and 3.3V to +numbers between 0 and 4095. .. contents:: Contents :local: +ADC On Maple +------------ + +Doing analog-to-digital conversion on the Maple is simple. +:ref:`Maple IDE ` contains a basic example. To see it, choose +Analog > AnalogInSerial from the :ref:`examples menu `. + +In order to set up your board for conversion, first connect the wire +(potentiometer, etc.) with the voltage you want to measure to a +:ref:`pin ` which can perform ADC. Each pin which can do ADC +has "AIN" (or "ain") written next to the the pin number. Then, as in +the example program, set the chosen pin's :ref:`pin mode +` to ``INPUT_ANALOG`` by calling ``pinMode(, +INPUT_ANALOG)``. You will usually do this in your :ref:`lang-setup` +function. Now you can use :ref:`lang-analogread` to perform an ADC +reading. + +.. _adc-function-reference: + +Function Reference +------------------ + +* :ref:`lang-analogread` +* :ref:`lang-pinmode` + .. _adc-noise-bias: Noise and Bias -------------- -.. FIXME [0.0.12, Maple Native] - -The biggest issues with analog to digital conversion are noise and -bias. With the Maple line, we have tried to isolate the ADC pins and -traces from strong noise sources, but there are always trade-offs -between noise, additional functionality, cost, and package size. -We've tried to enable good analog performance by isolating as many ADC -pins as possible from digital noise on each board. +Maple has a large number of pins which are capable of taking 12-bit +ADC measurements, which means that voltages from 0 to 3.3V are read as +numbers from 0 to 4095. In theory, this means that a change in +voltage of about 1 millivolt should change the numeric voltage reading +by 1. In reality, however, a number of issues introduce noise and +bias into this reading, and a number of techniques must be used to get +good precision and accuracy. + +In order to allow for good readings, LeafLabs has tried to isolate at +least some of each board's ADC pins and traces from strong noise +sources. However, there are always trade-offs between noise, +additional functionality, cost, and package size. More information on +these isolated pins is available in each board's hardware +documentation: -More information on these isolated pins is available in each board's -hardware documentation: +.. FIXME [0.0.12, Maple Native] * :ref:`Maple ` * :ref:`Maple RET6 Edition ` @@ -63,14 +89,6 @@ are `resistor dividers `_ and other powered components can also be used if greater precision is required. -.. _adc-function-reference: - -Function Reference ------------------- - -* :ref:`lang-analogread` -* :ref:`lang-pinmode` - .. _adc-recommended-reading: Recommended Reading -- cgit v1.2.3 From fe9c4469d9f2a6a67cc7059e5a45007a12b97b05 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 11 Jun 2011 21:22:05 -0400 Subject: Update x893's EEPROM library link. Old link was redirecting. --- source/arduino-compatibility.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/arduino-compatibility.rst b/source/arduino-compatibility.rst index c200411..3f6fef1 100644 --- a/source/arduino-compatibility.rst +++ b/source/arduino-compatibility.rst @@ -187,7 +187,7 @@ The state of currently ported Arduino libraries is the - (Unsupported) third-party emulation - The Maple doesn't have EEPROM; it uses flash instead. There is an `EEPROM emulation library - `_ by + `_ by `x893 `_, but we haven't tested it. * - Firmata -- cgit v1.2.3 From 793d10a13de9f49acbeec79129e8d987e1c6f218 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 13 Jun 2011 23:45:04 -0400 Subject: adc.rst: Add link to adc.h page. --- source/adc.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/adc.rst b/source/adc.rst index 2cf9018..451e7f0 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -35,6 +35,7 @@ Function Reference * :ref:`lang-analogread` * :ref:`lang-pinmode` +* :ref:`libmaple-adc` (low-level ADC support) .. _adc-noise-bias: -- cgit v1.2.3 From f3c392a0ce87823f740dabf7180d6387ec370ca5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 13 Jun 2011 23:47:38 -0400 Subject: language.rst: Tweaks for C/C++ hackers. --- source/language.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/language.rst b/source/language.rst index be085f2..f707cb2 100644 --- a/source/language.rst +++ b/source/language.rst @@ -13,7 +13,7 @@ language used to program the `Arduino `_ boards. .. TODO [0.2.0?] Wiring tutorial C or C++ programmers may wish to skip to the -:ref:`arduino_c_for_c_hackers`. +:ref:`arduino_c_for_c_hackers` or the :ref:`unix-toolchain`. .. contents:: Contents :local: @@ -22,6 +22,8 @@ C or C++ programmers may wish to skip to the - See the :ref:`libraries` for extra built-in libraries. + - If you want to use C or C++, see the :ref:`unix-toolchain`. + - If you're looking for something from the C standard library (like ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler ` used to compile your programs is configured to link -- cgit v1.2.3 From 57f21c8c3a0bd540fd0894a10917e77398ef38b8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 13 Jun 2011 23:48:56 -0400 Subject: arduino-compatibility: Grammar fix. --- source/arduino-compatibility.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/arduino-compatibility.rst b/source/arduino-compatibility.rst index 3f6fef1..b564e78 100644 --- a/source/arduino-compatibility.rst +++ b/source/arduino-compatibility.rst @@ -15,7 +15,7 @@ Overview The biggest difference between the Maple and most Arduino boards is that the Maple uses a 32-bit ARM Cortex-M3 architecture chip, while the Arduinos have 8-bit Atmel AVR chips. The different instruction set -means that machine code (which makes up executable binary program) is +means that machine code (which makes up executable binary programs) is incompatible between the two, and a different compiler (actually just a different version of `gcc `_) is required. -- cgit v1.2.3 From 74b7520159a5f7fc86f8698a5ac042d96ae4f6ee Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 14 Jun 2011 00:04:45 -0400 Subject: arm-gcc: Expanding notes on replacing pgmspace.h Thanks to James Bowman for the extra defines and typedef. --- source/arm-gcc.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index e97bb2f..5fb9a17 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -74,12 +74,23 @@ including Arduino) for use on the Maple. .. _arm-gcc-attribute-flash: -- Replacing ``PROGMEM``: You can direct the linker script provided - with libmaple to store a variable in Flash (instead of RAM) by using - the libmaple macro ``__FLASH__``, like so:: +- Replacing ``PROGMEM``: If you need to store a lot of constant data, + you can store variables in Flash (instead of RAM) by using the + libmaple macro ``__FLASH__``. Here's an example:: uint32 array[] __FLASH__ = {0, 1, 2}; - Be aware, however, that if you do that, you can only store values - which are compile-time constants, and that if you attempt to change - a variable stored in Flash, your program will crash. + This will help you save RAM when you need to store large amounts of + data, like look-up tables. + + You can only store values which are compile-time constants (like + numbers and strings, and arrays of numbers and strings) in this way. + Also, if you try to change a variable stored in Flash, your program + will crash. + + If you need to port over AVR/Arduino code that uses pgmspace.h, + these declarations may help you:: + + typedef const unsigned char prog_uchar; + #define pgm_read_byte_near(x) (*(prog_uchar*)x) + #define pgm_read_byte(x) (*(prog_uchar*)x) -- cgit v1.2.3 From 9335540d39df30f096f96dcfd15eea962757144f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 14 Jun 2011 00:05:05 -0400 Subject: Adding an FAQ. --- source/faq.rst | 33 +++++++++++++++++++++++++++++++++ source/index.rst | 1 + 2 files changed, 34 insertions(+) create mode 100644 source/faq.rst diff --git a/source/faq.rst b/source/faq.rst new file mode 100644 index 0000000..13347f8 --- /dev/null +++ b/source/faq.rst @@ -0,0 +1,33 @@ +.. _faq: + +================================== + Frequently Asked Questions (FAQ) +================================== + +.. contents:: Contents + :local: + +.. _faq-atoi: + +How can I use ``atoi()``? +------------------------- + +The :ref:`CodeSourcery GCC compiler ` used to compile your +programs is configured to link against the `newlib +`_ C library, and allows the use of any +of its headers. + +.. _faq-dynamic-memory: + +Why don't ``malloc()``/``new`` work? +------------------------------------ + +Due to our newlib configuration, dynamic memory allocation is +currently not available. + +.. _faq-flash-tables: + +How do I replace ``PROGMEM``/put data into Flash? +------------------------------------------------- + +See :ref:`this note `. diff --git a/source/index.rst b/source/index.rst index d17c4db..1df81f5 100644 --- a/source/index.rst +++ b/source/index.rst @@ -36,6 +36,7 @@ Have fun! libmaple Bootloader Troubleshooting + FAQ Notes on GCC's ARM target Complete Language Index -- cgit v1.2.3 From d1b3c4d990aa90502195511e7dc50eeac12cf871 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 14 Jun 2011 00:05:19 -0400 Subject: language: Making atoi() question point to FAQ. --- source/language.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/source/language.rst b/source/language.rst index f707cb2..82d2e7b 100644 --- a/source/language.rst +++ b/source/language.rst @@ -25,15 +25,10 @@ C or C++ programmers may wish to skip to the - If you want to use C or C++, see the :ref:`unix-toolchain`. - If you're looking for something from the C standard library (like - ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler - ` used to compile your programs is configured to link - against `newlib `_, and allows the - use of any of its header files. However, dynamic memory allocation - (``malloc()``, etc.) is not available. - - - If you're looking for pointers to low-level details, see - :ref:`libmaple` and this page's :ref:`Recommended Reading - `. + ``atoi()``, for instance, see :ref:`this FAQ `. + + - Low-level details are in :ref:`libmaple` and this page's + :ref:`Recommended Reading `. .. _language-lang-docs: -- cgit v1.2.3 From d9a2ef23dd2f6ba0210e126517b4bbaf5841dd40 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 14 Jun 2011 00:05:41 -0400 Subject: .gitignore Emacs autosave files. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 567609b..0187b3d 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ build/ +*~ -- cgit v1.2.3 From 2fe3429821293ad1d87d2d84d2960c2864e09268 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 14 Jun 2011 15:56:36 -0400 Subject: faq: Adding "How do I write to a pin at high speed?" --- source/faq.rst | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/source/faq.rst b/source/faq.rst index 13347f8..4b5b605 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -1,3 +1,5 @@ +.. highlight:: cpp + .. _faq: ================================== @@ -31,3 +33,63 @@ How do I replace ``PROGMEM``/put data into Flash? ------------------------------------------------- See :ref:`this note `. + +How do I write to a pin at high speed? +-------------------------------------- + +Sometimes, :ref:`lang-digitalwrite` just isn't fast enough. If that's +your situation, you should first try using fast GPIO writes using the +low-level :ref:`libmaple-gpio` interface. This FAQ entry explains +how. + +You'll need to look up the :ref:`GPIO port and bit ` which +correspond to the pin you want to write to. If you don't know what +that means, don't worry. We'll go through an example here. + +Let's say you want to write to pin 4 on the Maple. In order to find +out the port and bit number, take look at the Maple's :ref:`master pin +map ` next to "D4". You'll see that in the +"GPIO" column, there's "PB5". That's short for "**P**\ ort **B**, bit +**5**". So the GPIO port is "B", and the bit is "5". (If you're not +on the Maple, you can find your board's pin map :ref:`from here +`). + +That's all you need to know. Now you can use the function +``gpio_write_bit()`` to quickly write to the pin. The way you call it +is by writing ``gpio_write_bit(GPIO, , HIGH/LOW)``, where +```` is the GPIO port, ```` is the bit, and ``HIGH`` or +``LOW`` is the level you want to write to the pin. Here's an example +program which writes pin 4 (GPIOB, bit 5) ``HIGH`` and then ``LOW`` +several times in a row each time it :ref:`lang-loop`\ s:: + + /* + Fast pin writing example, for Maple. + + This example works for pin 4 (PB5 on Maple). If you want to + use another pin (or are on another board), just change PIN, + PIN_PORT, and PIN_BIT as described above. + */ + + #define PIN 4 + #define PIN_PORT GPIOB + #define PIN_BIT 5 + + void setup() { + pinMode(PIN, OUTPUT); + } + + void loop() { + gpio_write_bit(PIN_PORT, PIN_BIT, HIGH); + gpio_write_bit(PIN_PORT, PIN_BIT, LOW); + gpio_write_bit(PIN_PORT, PIN_BIT, HIGH); + gpio_write_bit(PIN_PORT, PIN_BIT, LOW); + } + +Now, if you've already tried this and you still can't get enough +speed, there are some threads on the `forum`_ which might help you +squeeze a little extra out of your board. First, a `general summary +`_ of other things to +try, with measurements of the speed you'll get. Next, a thread +featuring a `detailed discussion on pin capability +`_, with a focus on +writes. -- cgit v1.2.3 From a8d55cf8ff16d44c851851f490a982c445217ed1 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 03:43:00 -0400 Subject: unix-toolchain: Typo. --- source/unix-toolchain.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index b8382c4..71c6afb 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -52,7 +52,7 @@ contemporary Debian-based distribution. **1. Collect and Install Tools** -Firs, you'll need some tools:: +First, you'll need some tools:: $ sudo aptitude install build-essential git-core wget screen dfu-util \ openocd python python-serial -- cgit v1.2.3 From ebf148c41cf537ae2b4bf8d2ccdf1b6e4399ad89 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 03:48:14 -0400 Subject: unix-toolchain: Slight reorganization, typos --- source/unix-toolchain.rst | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 71c6afb..b9e6a8f 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -13,6 +13,22 @@ program the Maple; you can always :ref:`install the Maple IDE are comfortable using C or C++ and would like to use :ref:`libmaple` directly. +We currently have instructions for 32- and 64-bit Linux and OS X Snow +Leopard. If you're on another Unix platform, Windows, or an earlier +version of OS X, we imagine you can translate/port these directions on +your own. You might want to begin with these `stripped down +distributions `_ of the +`CodeSourcery GCC compiler tools +`_ (including Win32 +versions). If you do have success on other platforms, please post in +the forums, so we can fold your tips into this document! + +.. contents:: Contents + :local: + +Requirements +------------ + You'll need a Maple board, a Mini-B USB cable, a functional computer, and root (or Administrator) access to that computer. This guide assumes you've had success with the IDE on your machine and that you @@ -21,24 +37,6 @@ experience with editing your shell startup script (.bashrc, .tcshrc, etc.) and using `GCC `_ and `make `_ is recommended. -For generic installation and setup issues, see the :ref:`IDE -installation ` and :ref:`troubleshooting` pages. If -all else fails, try our `forum`_, or `contact us directly`_\ ! - -We currently have instructions for 32- and 64-bit Linux and OS X Snow -Leopard. If you're on another Unix platform, Windows, or an earlier -version of OS X, we're guessing that you can translate/port these -directions on your own. As a jumping off point, you might want to -begin with these `stripped down distributions -`_ of the `CodeSourcery -GCC compiler tools `_ -(including Win32 versions). If you do have success on other platforms, -please post in the forums, so we can fold your tips into this -document! - -.. contents:: Contents - :local: - .. _toolchain-linux-setup: Setup @@ -121,7 +119,7 @@ script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. From the libmaple directory, :: - $ groups # make sure it includes plugdev; if not add, yourself to it + $ groups # make sure it includes plugdev; if not, add yourself to it $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules $ sudo restart udev @@ -246,7 +244,7 @@ you can then unpack the archive and let OS X know where the compilers live with :: $ cd ~/Downloads - $ tar -xvzf gcc-blah-blah-macosx32.tar.gz + $ tar -xvzf gcc-blah-blah-osx32.tar.gz $ mv arm ~/libmaple/arm $ export PATH=$PATH:~/libmaple/arm/bin -- cgit v1.2.3 From 97e2ab5c5e6a028557c257c61563cd84b11bb021 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 04:36:57 -0400 Subject: bootloader: Fix "github" -> "GitHub" --- source/bootloader.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index ec4fe73..f64830d 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -14,7 +14,7 @@ Flash memory and only runs when the chip is reset). git clone git://github.com/leaflabs/maple-bootloader.git -**Visit the github development project**: https://github.com/leaflabs/maple-bootloader +**Visit the GitHub development project**: https://github.com/leaflabs/maple-bootloader .. contents:: Contents :local: @@ -34,7 +34,7 @@ This is a fairly involved explanation, with a lot of details that are likely only interesting to a few. If you just want to get the rough idea, skim this article. If you want to start hacking on the bootloader, get in touch with us to get even more info on how this all -works. And finally, you can always `check out the code at github +works. And finally, you can always `check out the code at GitHub `_! Arduino @@ -668,7 +668,7 @@ down*, release the RESET button and wait for a few seconds before releasing BUT. **Step 4: Get stm32loader.py**. You can download it directly from -`libmaple's github page +`libmaple's GitHub page `_ (click the link, then save the file somewhere on your system). If you have set up the :ref:`Unix toolchain `, it's the file -- cgit v1.2.3 From 8b4c4d8871d9b2537b37bd3482f307611bb98121 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 04:41:41 -0400 Subject: bootloader: Add some 0.0.12 FIXME comments. --- source/bootloader.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index f64830d..df0d77d 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -622,7 +622,7 @@ do is to compile your bootloader binary. Note that an ASCII representation of the binary, such as the Intel .hex format, won't work. -.. FIXME [Mini, Native] links to precompiled bootloaders +.. FIXME [0.0.12] links to bootloaders for Mini and Native If you just want to flash the default Maple bootloader (the one that was installed on your Maple when it arrived), we host a `pre-compiled @@ -646,7 +646,7 @@ could use another Maple, an Arduino, etc. -- anything that allows your computer to communicate with the Maple you want to reprogram over a serial interface. -.. FIXME [Maple-specific values] +.. FIXME [0.0.12, Maple-specific values] If you do use an FTDI breakout board, first make sure your Maple is disconnected from an external power source, be it battery, USB, or -- cgit v1.2.3 From f89ed85e6645e7da73ba255d71f7affba4f8ce36 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 04:45:08 -0400 Subject: bootloader: Point to perpetual bootloader troubleshooting item. --- source/bootloader.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index df0d77d..cb2fd30 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -661,11 +661,9 @@ More information on ``Serial1`` is available :ref:`here At this point, you're ready to plug the FTDI board into your computer (via USB). -**Step 3: Put your Maple into serial bootloader mode**. Do this by -pressing the RESET button, then *while RESET is held down*, pressing -and holding the BUT button. Next, *making sure to keep BUT held -down*, release the RESET button and wait for a few seconds before -releasing BUT. +**Step 3: Put your Maple into serial bootloader mode**. See the +:ref:`perpetual bootloader mode troubleshooting item +` for instructions. **Step 4: Get stm32loader.py**. You can download it directly from `libmaple's GitHub page -- cgit v1.2.3 From 385d90b263086efa21591699304ebd92499890b2 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 04:46:39 -0400 Subject: troubleshooting: Generalize across boards. --- source/troubleshooting.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index da6fb40..073eecb 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -223,15 +223,14 @@ In this mode, Maple stays a DFU device and does not jump to user code until the next reset. This is useful for guaranteeing that your Maple will be available for reprogramming. -To put your Maple into perpetual bootloader mode: +To put your Maple (or other Maple board) into perpetual bootloader mode: -#. Plug your Maple into the USB port. +#. Plug your board into the USB port. -#. Hit the reset button on your Maple (it's the small button at the - bottom left, labeled RESET). Notice that it blinks quickly 6 - times, then blinks slowly a few more times. +#. Hit the reset button (it's the button labeled RESET). Notice that + your board blinks quickly 6 times, then blinks slowly a few more + times. #. Hit reset again, and this time push and hold the other button - during the 6 fast blinks (the button is on the top right; it is - labeled BUT). You can release it once the slow blinks start. - + during the 6 fast blinks (the normal button is labeled BUT). You + can release it once the slow blinks start. -- cgit v1.2.3 From 748863f14ac5a3d2e45c50dce6a590b5ba4ea056 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 04:51:31 -0400 Subject: conf.py: Update copyright. --- source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index dce9d1b..841eadc 100644 --- a/source/conf.py +++ b/source/conf.py @@ -50,7 +50,7 @@ master_doc = 'index' # General information about the project. project = u'Maple' -copyright = u'2010, LeafLabs, LLC' +copyright = u'2010, 2011, LeafLabs, LLC' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the -- cgit v1.2.3 From 50f7b35ac9d10f2f9b6e1f1250e6f18ed1fd7a5b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 04:54:30 -0400 Subject: index: cosmetics. --- source/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/index.rst b/source/index.rst index 1df81f5..63347db 100644 --- a/source/index.rst +++ b/source/index.rst @@ -33,12 +33,12 @@ Have fun! Language Libraries Arduino Compatibility - libmaple + libmaple Bootloader Troubleshooting FAQ - Notes on GCC's ARM target - Complete Language Index + GCC and libc for Maple + Language Index .. _index-hardware: -- cgit v1.2.3 From d407a4eeec837a463bd636fd12daa307c3ea6047 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 12:12:12 -0400 Subject: external-interrupts: Add link to exti.h API page. --- source/external-interrupts.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index 9089d77..60a87f1 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -56,6 +56,7 @@ Function Reference - :ref:`attachInterrupt() ` - :ref:`detachInterrupt() ` +- :ref:`libmaple-exti` Recommended Reading ------------------- -- cgit v1.2.3 From b0bb39ffe6861b938113b596c04e86b0de934fcb Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 12:23:57 -0400 Subject: Add template page for creating libmaple proper API documentation. --- README | 6 ++++-- tmpl/libmaple-proper-page.rst.tmpl | 43 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 2 deletions(-) create mode 100644 tmpl/libmaple-proper-page.rst.tmpl diff --git a/README b/README index 2ed141b..d5aab21 100644 --- a/README +++ b/README @@ -107,8 +107,10 @@ It corresponds to the Sphinx file source/index.rst -Read more about Sphinx and chase pointers within the docs source to -find out more. +Read more about Sphinx and use the existing docs source as an example +when writing yours. The directory tmpl/ contains template ReST files +you should modify when creating a new page, in order to keep the style +consistent. The file source/conf.py is the Sphinx configuration file; you can go read it for more information about our setup. diff --git a/tmpl/libmaple-proper-page.rst.tmpl b/tmpl/libmaple-proper-page.rst.tmpl new file mode 100644 index 0000000..c00dd63 --- /dev/null +++ b/tmpl/libmaple-proper-page.rst.tmpl @@ -0,0 +1,43 @@ +.. This page is a template for documenting a peripheral support header +.. in libmaple proper (example: source/libmaple/api/adc.rst). +.. +.. To use, modify "foo" appropriately, etc. If a section would be +.. empty (i.e., there are no devices, just register maps) feel free to +.. leave it out. +.. +.. It would be nice if, in addition to the base breathe directives, +.. you flesh out sections as appropriate with free-form text that +.. helps the user get their job done. + +``foo.h`` +========= + +Support for Furious Oscillation Ocelots (FOO) peripherals. + +.. contents:: Contents + :local: + +Types +----- + +.. Docs for register map and device types here + +Devices +------- + +.. Docs for devices here + +Functions +--------- + +.. Documented, user-facing functions here + +Register Map Base Pointers +-------------------------- + +.. RMBPs here + +Register Bit Definitions +------------------------ + +.. you get the picture -- cgit v1.2.3 From 1461bfa98227e62c34addb743003d20a04c83941 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 15 Jun 2011 12:35:23 -0400 Subject: troubleshooting: Make sure you've got the right board selected. --- source/troubleshooting.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 073eecb..80f6df4 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -180,6 +180,12 @@ you :command:`make clean` when switching between Flash and RAM targets; our Makefile isn't smart enough to rebuild everything for the new target. +My code uploads, but it doesn't work! +------------------------------------- + +Are you sure you have the right board selected? (Maple vs. Maple Mini, +etc.) + .. _troubleshooting-shell: =================== -- cgit v1.2.3 From 78800630cd34f70577335b36eb5c88689a3036ef Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 20 Jun 2011 23:29:26 -0400 Subject: ide: Improve escape hatches. Better top-of-page pointers for people who are on the wrong page. --- source/ide.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/ide.rst b/source/ide.rst index 58dca1c..6e36e47 100644 --- a/source/ide.rst +++ b/source/ide.rst @@ -7,9 +7,11 @@ This page documents the basic functionality of the Maple IDE. Specifically, it describes the operation of the buttons on the main toolbar. It is expected to become more comprehensive over time. -The :ref:`Maple Quickstart ` is another good source of -information on the IDE; it is especially useful for setting up a -computer for the first time. +If you're new to Maple, you should begin with the :ref:`Maple +Quickstart `. + +If you need to install the IDE for the first time, see the +:ref:`maple-ide-install` page. .. contents:: Contents :local: -- cgit v1.2.3 From 272558f7ceaeff7dcf5d4cea039fcecaa0c52cb8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 20 Jun 2011 23:39:56 -0400 Subject: unix-toolchain: Tweaks. Use a :ref: to point to the IDE docs. Fix a path name mistake in the OS X toolchain docs. --- source/unix-toolchain.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index b9e6a8f..c7fc501 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -144,8 +144,8 @@ These instructions have been tested successfully on OS X 10.6.4. As stated previously, this document assumes a general level of Unix aptitude on the part of the reader; if you're uncomfortable using Terminal (or if you don't know what that means), then you should -probably stick with using the `Maple IDE -`_ to write programs. +probably stick with using the :ref:`Maple IDE ` to write +programs. **1. Collect and Install Tools** @@ -235,12 +235,12 @@ You first need to clone libmaple:: Then you need to get the cross-compilers we use to build a project. These are just modified versions of GCC; you can `download them for OS X here -`_. Assuming -you saved this file to +`_. Let's +say you saved this file to :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz` -you can then unpack the archive and let OS X know where the compilers +You can then unpack the archive and let OS X know where the compilers live with :: $ cd ~/Downloads -- cgit v1.2.3 From 46a3e6decf5b85bfff6461e416e1078dcceaf1e1 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 20 Jun 2011 23:43:33 -0400 Subject: hardware/maple-mini: Trivial grammar fix. --- source/hardware/maple-mini.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index b142e77..dab7195 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -304,7 +304,7 @@ Hardware Design Files --------------------- The hardware schematics and board layout files are available in the -`Maple Mini GitHub repository `_ +`Maple Mini GitHub repository `_. From the GitHub repository main page, you can download the entire repository by clicking the "Download" button. If you are familiar -- cgit v1.2.3 From 01ed40d84b34a5f1636b99a7959d6a70db456863 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 20 Jun 2011 23:53:03 -0400 Subject: hardware/maple-ret6: Clarifications. --- source/hardware/maple-ret6.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 1de2465..25c1294 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -7,8 +7,9 @@ Maple RET6 Edition This page is a general resource for information specific to the Maple RET6 Edition. The Maple RET6 Edition is a "beta" board released as a -simple way to get a more powerful chip than the one on the base Maple -(the STM32F103RET6, hence the name) in the hands of Maple developers. +simple way to get a more powerful chip (the STM32F103\ **RET6**, hence +the name) than the one on the base Maple (the STM32F103\ **RBT6**) in +the hands of Maple developers. .. contents:: Contents :local: @@ -394,9 +395,10 @@ features only available on the STM32F103RET6. the board's built-in LED; this is the same GPIO bit which is connected to the DAC's channel 2 output. This is also due to the RET6 Edition's board layout being that of the Maple Rev 5. The DAC - output channel is still available, and (if you use libmaple) its - output is buffered by default, so this may not significantly - interfere with its functionality. + output channel is still available, and (if you use the + :ref:`standard libmaple DAC interface `) its output is + buffered by default, so this may not significantly interfere with + its functionality. .. _maple-ret6-nrst-pb4: -- cgit v1.2.3 From 41f99bf34c5fb209ac8df26c0e69fa273d9944a5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 21 Jun 2011 00:56:54 -0400 Subject: arm-gcc: Typo. --- source/arm-gcc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 5fb9a17..75c3292 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -4,7 +4,7 @@ GCC for Maple ============= -This document provides notes on using of ``arm-none-eabi-gcc``, the +This document provides notes on using ``arm-none-eabi-gcc``, the `CodeSourcery `_ version of the GNU `GCC `_ compilers used for the Maple boards. It is not intended as a reference manual for GCC; such manuals are available -- cgit v1.2.3 From 48cbceeb74015fc2347ec8b139d3f6af34a4bf1b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 21 Jun 2011 00:59:32 -0400 Subject: arm-gcc: Add table of contents. --- source/arm-gcc.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 75c3292..129f5e6 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -10,6 +10,9 @@ This document provides notes on using ``arm-none-eabi-gcc``, the not intended as a reference manual for GCC; such manuals are available `elsewhere `_. +.. contents:: Contents + :local: + Obtaining ``arm-none-eabi-gcc`` ------------------------------- -- cgit v1.2.3 From 52fd358d32d75dfde684d4b2b54219956a01fbb6 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 23 Jun 2011 02:47:10 -0400 Subject: bootloader: Fix repo clone shell incantation. --- source/bootloader.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index cb2fd30..cebc671 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -634,7 +634,7 @@ To obtain the latest development version, you can run (on a :ref:`suitably configured system `) the following to obtain a binary of the bootloader currently used on the Maple:: - $ git checkout git://github.com/leaflabs/maple-bootloader.git + $ git clone git://github.com/leaflabs/maple-bootloader.git $ cd maple-bootloader $ make $ ls -lh build/maple-boot.bin # this is the compiled bootloader binary -- cgit v1.2.3 From 36491ca9078e34bccd9ee61a4411493fe3f2e41a Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 24 Jun 2011 16:38:48 -0400 Subject: usb: Add link to glossary of terms. --- source/usb.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/usb.rst b/source/usb.rst index a67d710..f9c0f28 100644 --- a/source/usb.rst +++ b/source/usb.rst @@ -38,6 +38,7 @@ Recommended Reading * `Embedded USB - a brief tutorial `_ * `Wikipedia article on Universal Serial Bus (USB) `_ * Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ +* `USB Glossary of Terms `_ * ST documentation: * Reference Manual `RM0008 `_ -- cgit v1.2.3 From 5e9c51e54457f39ea94d199572dad643065c63a0 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 5 Jul 2011 17:20:27 -0400 Subject: libmaple/contributing: Add more DCO information. --- source/libmaple/contributing.rst | 46 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/source/libmaple/contributing.rst b/source/libmaple/contributing.rst index bb4d550..debee6b 100644 --- a/source/libmaple/contributing.rst +++ b/source/libmaple/contributing.rst @@ -70,6 +70,15 @@ The steps to submit a pull request are as follows: 3. Push your commits to your GitHub libmaple fork (see instructions linked in Step 2 for a step-by-step walkthrough on how to do this). + Please add a signed-off-by line to your commits which certify your + `developer certificate of origin + `_ [#fcert]_. + For example, if your name is "John Smith", and your email address + is "jsmith@example.com", just include the following line at the + bottom of your commit messages: + + ``Signed-off-by: John Smith `` + 4. `Submit a pull request `_ to the LeafLabs version of libmaple. @@ -92,7 +101,7 @@ the following information in your email: you think we should know. 4. A sign-off line certifying your `developer certificate of origin - `_. + `_ [#fcert]_. That said, we'd really prefer a pull request. If you'd like to learn more about Git, we recommend the following resources: @@ -111,3 +120,38 @@ more about Git, we recommend the following resources: `_: if you're comfortable with directed acyclic graphs, this resource explains Git's functionality in graph-theoretic terms. + +.. highlight:: text + +.. rubric:: Footnotes + +.. [#fcert] Including this line indicates that you certify the following:: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + + This may seem arbitrary, but it helps ensure that libmaple + remains open source. -- cgit v1.2.3 From 56383840c0872dab24501c981420a500b1f4c200 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 6 Jul 2011 12:20:49 -0400 Subject: bootloader: Mention lack of serial port after flashing a fresh bootloader. After installing a fresh DFU bootloader, the board has no user code on it, so libmaple's init() never gets run, and there's no need to select a serial port to perform the autoreset sequence on. This caused confusion among users who weren't able to find a serial port after installing a new bootloader. Add some documentation to help avoid this confusion. --- source/bootloader.rst | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index cebc671..d946fe4 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -708,7 +708,25 @@ You can also run the following to get usage information:: python.exe stm32loader.py -h If all goes well, you'll see a bunch of output, then "Verification -OK". If something goes wrong, the `forum`_ is probably your best bet -for obtaining help, with IRC (server irc.freenode.net, channel +OK". Your board now has a fresh bootloader installed. + +The first time you upload a program after installing a new bootloader, +there is no need to select a serial port in the :ref:`IDE ` +[#fbootser]_. Perform this first upload with no serial port selected. +The IDE will emit a warning about not finding a serial port, but the +upload will still succeed. In subsequent uploads, select a serial +port as you normally would. + +If something goes wrong, the `forum`_ is probably your best bet for +obtaining help, with IRC (server irc.freenode.net, channel #leafblowers) being another option. If all else fails, you can always `contact us directly`_! + +.. rubric:: Footnotes + +.. [#fbootser] This is because immediately after installing a new + bootloader, the only program on your board is the + bootloader itself. Unlike a normal sketch, the + bootloader is not enumerated as a virtual serial port + (it uses DFU instead; see :ref:`above + ` for more details). -- cgit v1.2.3 From 19909ffa44e68453f928164275a8263c8548b32b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 10 Jul 2011 19:59:18 -0400 Subject: coding-standard: Kill trailing whitespace. --- source/libmaple/coding-standard.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/libmaple/coding-standard.rst b/source/libmaple/coding-standard.rst index 23d20f8..94af3d7 100644 --- a/source/libmaple/coding-standard.rst +++ b/source/libmaple/coding-standard.rst @@ -356,7 +356,7 @@ General Formatting .. highlight:: scheme -- Keep it 80-column clean. +- Keep it 80-column clean. Emacs users: this means that the largest column number is 79. You should turn on column number mode to help you out:: -- cgit v1.2.3 From 2f0df39d1e895245f6437a2ba3a4a5bb4faee7c5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 10 Jul 2011 19:59:39 -0400 Subject: coding-standard: Add link to TextMate bundle for whitespace handling. --- source/libmaple/coding-standard.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/libmaple/coding-standard.rst b/source/libmaple/coding-standard.rst index 94af3d7..d22f12e 100644 --- a/source/libmaple/coding-standard.rst +++ b/source/libmaple/coding-standard.rst @@ -53,6 +53,11 @@ Emacs: if you don't like seeing the license, you should use elide-head Whitespace ---------- +TextMate users may find `this bundle +`_ useful for +automatically converting tabs to spaces and removing trailing +whitespace at save time. + - 4 space indents (set in ``.dir-locals.el``). - Unix newlines. Some exceptions are currently grandfathered in; these -- cgit v1.2.3 From 7f60680a7b6f8a3c2dfd808a937e888c6e30bfae Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 25 Jul 2011 13:56:08 -0400 Subject: bootloader: Reorganize, bugfix, update "Flashing A Custom Bootloader". - Clarify that PySerial must be installed separately - Add links to pre-compiled Mini and RET6 Edition bootloaders - Add note that Mini must have BOOT1 tied to GND during upload - Fix instructions for activating built-in serial bootloader - Add disambiguation between serial bootloader and perpetual bootloader mode - Add footnote distinguishing baked-in serial bootloader from LeafLabs' bootloaders --- source/bootloader.rst | 67 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 43 insertions(+), 24 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index d946fe4..b8c0654 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -611,33 +611,34 @@ Setup In order to follow these instructions, you will need: -- A binary of the bootloader you want to upload +- A binary of the bootloader you want to upload (see below). - Hardware for communicating between the Maple and your computer over serial. -- `Python `_ version 2.5 or higher, with the - `PySerial `_ library installed. +- `Python `_, version 2.5 or higher. +- The `PySerial `_ library (this + must be installed separately; it is not part of the Python standard + library). -**Step 1: Obtain a bootloader binary**. The first thing you'll need to -do is to compile your bootloader binary. Note that an ASCII -representation of the binary, such as the Intel .hex format, won't -work. +**Step 1: Obtain a bootloader binary**. If you want to re-flash the +"factory-default" bootloader, LeafLabs hosts pre-compiled copies: -.. FIXME [0.0.12] links to bootloaders for Mini and Native +- `Maple `_ +- `Maple Mini `_ +- `Maple RET6 Edition `_ -If you just want to flash the default Maple bootloader (the one that -was installed on your Maple when it arrived), we host a `pre-compiled -copy -`_, -which works on all Maple Revs. - -To obtain the latest development version, you can run (on a -:ref:`suitably configured system `) the following to -obtain a binary of the bootloader currently used on the Maple:: +To flash a customized version of a LeafLabs bootloader, you can run +(on a :ref:`suitably configured system `) the +following to obtain a bootloader binary:: $ git clone git://github.com/leaflabs/maple-bootloader.git $ cd maple-bootloader $ make - $ ls -lh build/maple-boot.bin # this is the compiled bootloader binary + $ ls -lh build/maple_boot.bin # this is the compiled bootloader binary + +.. note:: If you plan to write a totally custom bootloader, you'll + need an actual binary to use these instructions. An ASCII + representation of the binary, such as the Intel .hex format, won't + work. **Step 2: Connect Maple Serial1 to your computer**. There are a variety of ways of doing this. We use Sparkfun's `FTDI @@ -651,9 +652,10 @@ serial interface. If you do use an FTDI breakout board, first make sure your Maple is disconnected from an external power source, be it battery, USB, or barrel jack. Then, connect the FTDI board's TX pin to ``Serial1``\ 's -RX pin (pin 8), FTDI RX to ``Serial1`` TX (pin 7), FTDI ground to -Maple's GND, and its 3.3V pin to Maple's Vin (use the Maple's -silkscreen for help locating these pins). +RX pin (pin 8 on Maple), FTDI RX to ``Serial1`` TX (pin 7 on Maple), +FTDI ground to ground (labeled GND), and its 3.3V pin to Vin. On +Maple Mini, you will also need to tie BOOT1 (pin 2) to ground. You +can use the silkscreen for help locating these pins on other boards. More information on ``Serial1`` is available :ref:`here `. @@ -661,9 +663,20 @@ More information on ``Serial1`` is available :ref:`here At this point, you're ready to plug the FTDI board into your computer (via USB). -**Step 3: Put your Maple into serial bootloader mode**. See the -:ref:`perpetual bootloader mode troubleshooting item -` for instructions. +**Step 3: Run the built-in hardware serial bootloader**\ +[#fserbootmode]_. Accomplish this using the following steps: + +1. Press and hold the reset and BUT buttons. +2. Release the reset button *without releasing BUT*. +3. Release BUT. + +At this point, if you followed the instructions correctly, the board +will appear unresponsive -- the LED won't blink, etc. Don't worry. +This is the expected behavior for the serial bootloader. + +Do not confuse the above steps, which run the built-in serial +bootloader, with the steps for :ref:`perpetual boodloader mode +`. **Step 4: Get stm32loader.py**. You can download it directly from `libmaple's GitHub page @@ -730,3 +743,9 @@ obtaining help, with IRC (server irc.freenode.net, channel bootloader is not enumerated as a virtual serial port (it uses DFU instead; see :ref:`above ` for more details). + +.. [#fserbootmode] Resetting your board in this way runs a special + bootloader that ST builds into their chips' + hardware, which communicates over :ref:`usart`. + This is different from the LeafLabs bootloader, + which is a normal program that runs on your board. -- cgit v1.2.3 From 8103a679d4672d366263c9132c24abd2e90a9ace Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 25 Jul 2011 14:07:29 -0400 Subject: bootloader: Update boards the document applies to. --- source/bootloader.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index b8c0654..a252473 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -599,10 +599,12 @@ This means that you can **always** follow these instructions to put a new bootloader program on your board; it **doesn't matter** if there's already a copy of the Maple bootloader on it or not. -This section applies to Maple Rev 3 or higher. If you have a Maple -Rev 1; you don't have a BUT button, and won't be able to follow these -directions. A workaround is detailed in `this forum posting -`_. +This section applies to Maple Rev 3 (or higher), Maple Mini, and Maple +RET6 Edition. + +If you have a Maple Rev 1; you don't have a BUT button, and won't be +able to follow these directions. A workaround is detailed in `this +forum posting `_. .. highlight:: sh -- cgit v1.2.3 From edbf9e113f65dc0f498db1d6152e3bf499615abf Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 27 Jul 2011 14:50:50 -0400 Subject: hardwarespi: Fix HardwareSPI::transmit() -> HardwareSPI::transfer() --- source/lang/api/hardwarespi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst index 054d1a8..3e71fb6 100644 --- a/source/lang/api/hardwarespi.rst +++ b/source/lang/api/hardwarespi.rst @@ -99,7 +99,7 @@ receive data using ``HardwareSPI::read()``, and do both using Get the next available, unread byte. If there aren't any unread bytes, this function will wait until one is received. -.. cpp:function:: byte HardwareSPI::transmit(byte data) +.. cpp:function:: byte HardwareSPI::transfer(byte data) Send a byte, then return the next byte received. -- cgit v1.2.3 From 2ffc358cd2e69108d2c2137e73fec68071b11c6d Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 3 Aug 2011 14:12:59 -0400 Subject: hardware/maple-mini: Fix copy/paste errors. --- source/hardware/maple-mini.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index dab7195..665970a 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -185,7 +185,7 @@ EXTI Line Pin Map ^^^^^^^^^^^^^^^^^ The following table shows which pins connect to which :ref:`EXTI lines -` on the Maple. +`. .. list-table:: :widths: 1 1 @@ -231,9 +231,9 @@ The following table shows which pins connect to which :ref:`EXTI lines USART Pin Map ^^^^^^^^^^^^^ -The Maple RET6 Edition has three serial ports whose pins are broken -out to headers (also known as :ref:`USARTs `). They communicate -using the pins summarized in the following table: +The Maple Mini has three serial ports (also known as :ref:`USARTs +`). They communicate using the pins summarized in the following +table: .. csv-table:: :header: Serial Port, TX, RX, CK, CTS, RTS -- cgit v1.2.3 From 7756783c967fa7468bcf803ce8a24404b1094109 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 3 Aug 2011 20:01:50 -0400 Subject: Improve external interrupts documentation. Simplify and remove redundancies from external-interrupts.rst. Move a pin configuration detail from that page into the attachInterrupt() API page (attachinterrupt.rst). Fix and explain what's going on in the example sketch in attachinterrupt.rst. --- source/external-interrupts.rst | 32 ++++++++++++-------------------- source/lang/api/attachinterrupt.rst | 36 ++++++++++++++++++++++++++++-------- 2 files changed, 40 insertions(+), 28 deletions(-) diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index 60a87f1..1ab65be 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -5,13 +5,11 @@ External Interrupts =================== -External interrupts can be used to make a voltage change on a pin -cause a function to be called. Each :ref:`GPIO pin ` can be -used to detect transitions, such as when the voltage goes from -:ref:`LOW ` to :ref:`HIGH `, -or from ``HIGH`` to ``LOW``. This can be used to avoid checking for -changes on a pin "manually" by waiting in a loop until the pin -changes. +External interrupts can be used to make a voltage change on a +:ref:`pin ` (the pin going from :ref:`LOW ` +to :ref:`HIGH `, or vice-versa) to cause a +function to be called. This can be used to avoid checking for changes +on a pin "manually" by waiting in a loop until the pin changes. .. _contents: Contents :local: @@ -20,16 +18,16 @@ Overview -------- External interrupts are often used to detect when events happen -outside of the Maple. These can be used to tell Maple when events -happen, such as when a sensor has data ready to be read, or when a -button has been pushed. When such an event happens, an interrupt is -raised, and the Maple stops whatever it was doing to react to it by -calling a function (called an *interrupt handler*) which you specify -using :ref:`lang-attachinterrupt`. +outside of the Maple. Example events include when a sensor has data +ready to be read, or when a button has been pushed. When such an +event happens, an interrupt is raised, and the Maple stops whatever it +was doing (it is "interrupted"), and reacts to the event by calling a +function (called an *interrupt handler*) which you specify using +:ref:`lang-attachinterrupt`. .. _external-interrupts-exti-line: -Every pin can generate an external interrupt, but there are some +Any pin can be used for external interrupts, but there are some restrictions. At most 16 different external interrupts can be used at one time. Further, you can't just pick any 16 pins to use. This is because every pin on the Maple connects to what is called an *EXTI @@ -45,12 +43,6 @@ EXTI lines: * :ref:`Maple RET6 Edition ` * :ref:`Maple Mini ` -.. note:: - - You should set the :ref:`pin mode ` of your desired - pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``, - ``INPUT_PULLDOWN``). - Function Reference ------------------ diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst index 39902ac..58e4764 100644 --- a/source/lang/api/attachinterrupt.rst +++ b/source/lang/api/attachinterrupt.rst @@ -41,6 +41,12 @@ Library Documentation .. doxygentypedef:: voidFuncPtr +.. note:: + + You should set the :ref:`pin mode ` of your desired + pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``, + ``INPUT_PULLDOWN``). + Discussion ---------- @@ -50,31 +56,45 @@ Because the function will run in interrupt context, inside of it, the function may be lost. You should declare as ``volatile`` any global variables that you modify within the attached function. -There are a few limits you should be aware of if you're using more -than one interrupt at a time; the :ref:`External Interrupts -` page has more information. +There are some limits you should be aware of if you're using +``attachInterrupt()`` with more than one pin; the :ref:`External +Interrupts ` page has more information. Example ------- - :: +The following example blinks the LED any time pin 0 changes from +``HIGH`` to ``LOW`` or vice versa. :: volatile int state = LOW; // must declare volatile, since it's // modified within the blink() handler void setup() { - pinMode(BOARD_LED_PIN, OUTPUT); - attachInterrupt(0, blink, CHANGE); + pinMode(BOARD_LED_PIN, OUTPUT); + pinMode(0, INPUT); + attachInterrupt(0, blink, CHANGE); } void loop() { - digitalWrite(BOARD_LED_PIN, state); + digitalWrite(BOARD_LED_PIN, state); } void blink() { - state = !state; + if (state == HIGH) { + state = LOW; + } else { // state must be LOW + state = HIGH; + } } +In this example, the function ``blink()`` is the interrupt handler. +Whenever the state on pin 0 changes, ``blink()`` gets called. It +reacts to the change by changing the ``state`` variable to ``LOW`` if +it is ``HIGH``, and to ``HIGH`` if it is ``LOW``. It then exits, +letting the board get back to calling ``loop()``. Since ``loop()`` +sets the LED pin to whatever ``state`` is, changing the voltage on pin +0 will toggle the LED. + Arduino Compatibility --------------------- -- cgit v1.2.3 From 7590eff36e173d693aac79209e03094d2c72e7c6 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 11 Aug 2011 02:57:19 -0400 Subject: Typo. --- source/libmaple/overview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/libmaple/overview.rst b/source/libmaple/overview.rst index d18bfe2..21d1a72 100644 --- a/source/libmaple/overview.rst +++ b/source/libmaple/overview.rst @@ -198,7 +198,7 @@ saying ``volatile`` when referring to register values):: holding register */ __io uint32 DHR12LD; /**< Dual DAC 12-bit left-aligned data holding register */ - __io uint32 DHR8RD; /**< Dual DAC 8-bit left-aligned data holding + __io uint32 DHR8RD; /**< Dual DAC 8-bit right-aligned data holding register */ __io uint32 DOR1; /**< Channel 1 data output register */ __io uint32 DOR2; /**< Channel 2 data output register */ -- cgit v1.2.3 From e77706eedde0f7363068c2ebaec415fb1a3f9e36 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 11 Aug 2011 17:27:44 -0400 Subject: Typo. --- source/bootloader.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index a252473..e9a52cf 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -677,7 +677,7 @@ will appear unresponsive -- the LED won't blink, etc. Don't worry. This is the expected behavior for the serial bootloader. Do not confuse the above steps, which run the built-in serial -bootloader, with the steps for :ref:`perpetual boodloader mode +bootloader, with the steps for :ref:`perpetual bootloader mode `. **Step 4: Get stm32loader.py**. You can download it directly from -- cgit v1.2.3 From 5dad37433f3ed4a81baf7bc2a89f38f2db7e4af1 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 16 Aug 2011 06:10:33 -0400 Subject: bootloader: Tweak. --- source/bootloader.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index e9a52cf..d3a1abb 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -750,4 +750,5 @@ obtaining help, with IRC (server irc.freenode.net, channel bootloader that ST builds into their chips' hardware, which communicates over :ref:`usart`. This is different from the LeafLabs bootloader, - which is a normal program that runs on your board. + which is a normal program that runs on your board, + and communicates over :ref:`usb`. -- cgit v1.2.3 From 1529927c59ee12f390bec9eb612343a982e1f43c Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 16 Aug 2011 06:11:03 -0400 Subject: serial: Add tutorial style content, fix method signatures. --- source/lang/api/serial.rst | 164 +++++++++++++++++++++++++++++++++------------ 1 file changed, 122 insertions(+), 42 deletions(-) diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst index a08c9b7..8c9ebc7 100644 --- a/source/lang/api/serial.rst +++ b/source/lang/api/serial.rst @@ -1,31 +1,104 @@ +.. highlight:: cpp + .. _lang-serial: Serial Ports (``Serial1``, ``Serial2``, ``Serial3``) ==================================================== -Used for communication between the Maple board and a computer or other -devices. +This page describes how to use the built-in serial ports (also known +as USARTs). For more information about serial ports, see +:ref:`usart`. .. contents:: Contents :local: -Introduction ------------- - -.. FIXME [0.0.12/Maple Native] UART4, UART5 - -To use a serial port to communicate with an external serial device, -connect the TX pin to your device's RX pin, the RX to your device's TX -pin, and your Maple board's ground to your device's ground. - -.. warning:: Don't connect these pins directly to an RS232 serial - port; they operate at +/- 12V and can damage your board. +Getting Started +--------------- + +First, decide which serial port you wish to use, and :ref:`connect its +pins to the device you're communicating with `. (The TX +and RX pins for a serial port are labeled on your board's silkscreen; +for example, serial port 2 has pins labeled "TX2" and "RX2"). + +The variable for controlling a serial port is the word ``Serial``, +plus the serial port's number. For example, you can control serial +port 1 with the variable ``Serial1``, serial port 2 with ``Serial2``, +and so on. + +In order to get started using your serial port, you'll first need to +turn it on. Do this by calling your serial port's ``begin()`` +function, giving it the baud rate you wish it to communicate at. If +you're not sure what baud rate to use, 9600 is a safe (although slow) +value to try. Put this call to ``begin()`` in your :ref:`lang-setup`, +like in the following example:: + + void setup() { + // 9600 is the baud rate to use. The baud rate determines how + // fast the communication goes. + Serial2.begin(9600); + } + + void loop() { + // Communicate using Serial2 here + } + +Communicating Over Serial +------------------------- + +Now that your serial port is set up, it's time to start communicating. + +One common use for serial ports is to print strings and other +debugging information to a computer. You can print numbers or strings +using ``print()`` and ``println()``, like this:: + + void printSomeInformation() { + Serial2.print("First, print this string. Then print a number: "); + Serial2.print(42); + Serial2.print(". You can print floating point values, too: "); + Serial2.print(3.14); + Serial2.println(". Using println() instead of print() ends the line."); + Serial2.println("This sentence starts on a new line."); + } + +This sort of communication can go both ways: you can send characters +from a computer to a serial port as well. You can check how many +characters are waiting for you to read using the ``available()`` +function, and read them out one at a time using ``read()``. The +following example program uses these functions to "echo" back anything +sent to ``Serial2``:: + + void setup() { + Serial2.begin(9600); + } + + void echoCharacter() { + // Check to see if we have received any information. numUnread + // will hold the number of bytes we've received, but haven't + // looked at yet. + int numUnread = Serial2.available(); + + // numUnread > 0 means that there are some unread bytes waiting + if (numUnread > 0) { + // Read a single byte out: + byte b = Serial2.read(); + // And then print it back: + Serial2.print(b); + } + } + + void loop() { + echoCharacter(); + } + +Function Reference +------------------ + +This section gives a full listing of functions available for use with +serial ports. Library Documentation --------------------- -.. FIXME [0.1.0] Tutorial-style usage introduction - All of the ``Serial[1,2,3]`` objects are instances of the ``HardwareSerial`` class, which is documented in this section. (This means that you can use any of these functions on any of ``Serial1``, @@ -36,14 +109,14 @@ means that you can use any of these functions on any of ``Serial1``, Serial port class. Predefined instances are ``Serial1``, ``Serial2``, and ``Serial3``. -.. cpp:function:: HardwareSerial::begin(unsigned int baud) +.. cpp:function:: void HardwareSerial::begin(unsigned int baud) Set up a ``HardwareSerial`` object for communications. This method must be called before attempting to use the ``HardwareSerial`` object (typically, you call this in your :ref:`setup() ` function). -.. cpp:function:: HardwareSerial::end() +.. cpp:function:: void HardwareSerial::end() Disables the USART associated with this object, allowing any associated communication pins to be used for other purposes. @@ -59,107 +132,106 @@ means that you can use any of these functions on any of ``Serial1``, `), the call will block until one becomes available. -.. cpp:function:: HardwareSerial::flush() +.. cpp:function:: void HardwareSerial::flush() Throw away the contents of the serial port's receiver (RX) buffer. That is, clears any buffered characters, so that the next character read is guaranteed to be new. -.. cpp:function:: HardwareSerial::print(unsigned char b) +.. cpp:function:: void HardwareSerial::print(unsigned char b) Print the given byte over the USART. -.. cpp:function:: HardwareSerial::print(char c) +.. cpp:function:: void HardwareSerial::print(char c) Print the given character over the USART. 7-bit clean characters are typically interpreted as ASCII text. -.. cpp:function:: HardwareSerial::print(const char *str) +.. cpp:function:: void HardwareSerial::print(const char *str) Print the given null-terminated string over the USART. -.. cpp:function:: HardwareSerial::print(int n) +.. cpp:function:: void HardwareSerial::print(int n) Print the argument's digits over the USART, in decimal format. Negative values will be prefixed with a ``'-'`` character. -.. cpp:function:: HardwareSerial::print(unsigned int n) +.. cpp:function:: void HardwareSerial::print(unsigned int n) Print the argument's digits over the USART, in decimal format. -.. cpp:function:: HardwareSerial::print(long n) +.. cpp:function:: void HardwareSerial::print(long n) Print the argument's digits over the USART, in decimal format. Negative values will be prefixed with a ``'-'`` character. -.. cpp:function:: HardwareSerial::print(unsigned long n) +.. cpp:function:: void HardwareSerial::print(unsigned long n) Print the argument's digits over the USART, in decimal format. -.. cpp:function:: HardwareSerial::print(long n, int base) +.. cpp:function:: void HardwareSerial::print(long n, int base) Print the digits of ``n`` over the USART, in base ``base`` (which may be between 2 and 16). The ``base`` value 2 corresponds to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative values will be prefixed with a ``'-'`` character. -.. cpp:function:: HardwareSerial::print(double n) +.. cpp:function:: void HardwareSerial::print(double n) Print ``n``, accurate to 2 digits after the decimal point. .. _lang-serial-println: -.. cpp:function:: HardwareSerial::println(char c) +.. cpp:function:: void HardwareSerial::println(char c) Like ``print(c)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(const char *c) +.. cpp:function:: void HardwareSerial::println(const char *c) Like ``print(c)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(unsigned char b) +.. cpp:function:: void HardwareSerial::println(unsigned char b) Like ``print(b)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(int n) +.. cpp:function:: void HardwareSerial::println(int n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(unsigned int n) +.. cpp:function:: void HardwareSerial::println(unsigned int n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(long n) +.. cpp:function:: void HardwareSerial::println(long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(unsigned long n) +.. cpp:function:: void HardwareSerial::println(unsigned long n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(long n, int base) +.. cpp:function:: void HardwareSerial::println(long n, int base) Like ``print(n, b)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println(double n) +.. cpp:function:: void HardwareSerial::println(double n) Like ``print(n)``, followed by ``"\r\n"``. -.. cpp:function:: HardwareSerial::println() +.. cpp:function:: void HardwareSerial::println() Prints ``"\r\n"`` over the USART. -.. cpp:function:: HardwareSerial::write(unsigned char ch) +.. cpp:function:: void HardwareSerial::write(unsigned char ch) Sends one character over the USART. This function is currently - blocking, although nonblocking writes are a planned future - extension. + blocking. This is a low-level function. One of the ``print()`` or ``println()`` functions is likely to be more useful when printing multiple characters, when formatting numbers for printing, etc. -.. cpp:function:: HardwareSerial::write(const char* str) +.. cpp:function:: void HardwareSerial::write(const char* str) Send the given null-terminated character string over the USART. @@ -167,7 +239,7 @@ means that you can use any of these functions on any of ``Serial1``, ``println()`` functions is likely to be more useful when printing multiple characters, when formatting numbers for printing, etc. -.. cpp:function:: HardwareSerial::write(void *buf, unsigned int size) +.. cpp:function:: void HardwareSerial::write(void *buf, unsigned int size) Writes the first ``size`` bytes of ``buf`` over the USART. Each byte is transmitted as an individual character. @@ -176,6 +248,14 @@ means that you can use any of these functions on any of ``Serial1``, ``println()`` functions is likely to be more useful when printing multiple characters, when formatting numbers for printing, etc. +.. cpp:function:: int HardwareSerial::txPin() + + Return the number of the TX (transmit) pin. + +.. cpp:function:: int HardwareSerial::rxPin() + + Return the number of the RX (receive) pin. + Arduino Compatibility Note -------------------------- -- cgit v1.2.3 From b49dfa32cc38e7a8a708261a03ed0d8ce69f7feb Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 16 Aug 2011 06:11:25 -0400 Subject: usart: Add electrical configuration removed from serial.rst. --- source/usart.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/source/usart.rst b/source/usart.rst index e65821d..fa9c55c 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -10,11 +10,17 @@ another Maple, etc.). .. contents:: Contents :local: +.. _usart-circuit: + Hardware/Circuit Design ----------------------- -.. TODO [0.0.12] Add some more information here (like how you should -.. connect TX_a to RX_b and RX_a to TX_b). +To use a serial port to communicate with an external serial device, +connect the TX pin to your device's RX pin, the RX to your device's TX +pin, and your Maple board's ground to your device's ground. + +.. warning:: Don't connect these pins directly to an RS232 serial + port; they operate at +/- 12V and can damage your board. .. TODO [0.0.12/Maple Native] UART4 and UART5, Native links @@ -52,3 +58,6 @@ Recommended Reading * ST `Reference Manual RM0008 `_ (PDF), Chapter 27. +* `Serial and UART Tutorial + `_ (written for + FreeBSD, but contains a large amount of general information). -- cgit v1.2.3 From 653c06fed765d9748e18f289ac3f1e995c6a9486 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 18 Aug 2011 13:26:08 -0400 Subject: unix-toolchain: Add note about using BOARD env. variable. --- source/unix-toolchain.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index c7fc501..cb23782 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -269,6 +269,22 @@ tools correctly:: $ make clean $ make +.. note:: These instructions are for the Maple. If you're compiling + for another board, you'll need to set a ``BOARD`` environment + variable appropriately. For example, to compile for Maple Mini (in + the bash shell), :: + + $ export BOARD=maple_mini + $ make + + The ``BOARD`` for Maple RET6 edition is ``maple_RET6``. You can + also use :: + + $ BOARD=maple_mini make + + This will only set the environment variable for the duration of + that single compile. + If it all works out, you should end up seeing something like this:: find build -iname *.o | xargs arm-none-eabi-size -t -- cgit v1.2.3 From 02a32f2b79ead308306975576910ef731e760492 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 19 Aug 2011 14:03:06 -0400 Subject: troubleshooting.rst: Add debugging pointers to "throbbing LED" item. --- source/troubleshooting.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 80f6df4..7654c40 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -17,9 +17,23 @@ This page documents common problems and their solutions. The LED is throbbing and my program is stopped! ----------------------------------------------- -The LED throbs when there has been a failed software :ref:`assertion +The LED throbs when there has been a failed software :ref:`ASSERT() ` or some other error. +In the case of a failed assertion, a first debugging step you can take +is to find out the file and line where the failed assertion took place +(for instructions on this, see the ``ASSERT()`` documentation linked +to above). This may give you some clue about the source of the error. + +:ref:`libmaple` often uses ``ASSERT()`` to halt immediately when it +detects that something has gone wrong, so if you're not using +assertions, then what's probably happening is that some bug is causing +the failed ``ASSERT()`` lower down. + +If it's not a failed assertion, then you're likely looking at +something like a `hard fault +`_. + There are a few issues with the bootloader which mean you might not be able to upload your program when this happens. You can still reprogram by using :ref:`perpetual bootloader mode -- cgit v1.2.3 From 00231553cd084f3e8abbc347e7d0e3cdfd0505f5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 19 Aug 2011 14:21:58 -0400 Subject: index.rst: Mention the wiki. The wiki doesn't get enough love. This should help. --- source/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/index.rst b/source/index.rst index 63347db..7886c4f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -9,6 +9,9 @@ If you just bought a Maple board, you probably want to head to the :ref:`quickstart `. If you're having problems, check out the :ref:`troubleshooting ` page. +If you can't find what you're looking for, try looking on our `wiki +`_. + Have fun! .. _index-usage: -- cgit v1.2.3 From 9f0a1e2911100ae7601aa2d7519b0d2003c87cf3 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 22 Aug 2011 17:13:50 -0400 Subject: README: updates/cosmetics. --- README | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/README b/README index d5aab21..15c1006 100644 --- a/README +++ b/README @@ -1,7 +1,7 @@ Introduction ------------ -This directory contains reStructuredText (reST) source files used to +This repository contains reStructuredText (reST) source files used to generate the documentation for LeafLabs' libmaple and Maple IDE projects. For more information on these projects, see their GitHub pages: @@ -33,9 +33,8 @@ The docs are written in Sphinx's extensions to reStructuredText http://sphinx.pocoo.org/tutorial.html -Much of the documentation is pulled out of the libmaple source code; -we pull Doxygen's XML output into Sphinx documentation. You can read -more about Doxygen here: +Much of the documentation is pulled out of the libmaple source code. +libmaple documents itself using Doxygen: http://doxygen.org @@ -47,8 +46,8 @@ into a form usable by Sphinx. You can read more about Breathe here: Documentation Build Steps ------------------------- -You first need to produce Doxygen XML output, then you can generate -the HTML documentation. +First, you will need to install some dependencies (Doxygen, Sphinx, +and Breathe). 1. You need a recent-ish version of Doxygen in your PATH: @@ -83,14 +82,17 @@ the HTML documentation. You need Sphinx version >= 1.0.6. -4. Before the first time you run Sphinx (and any time the Doxygen +You are now ready to build the documentation. First, you'll produce +Doxygen XML output, then you can generate the HTML documentation. + +1. Before the first time you run Sphinx (and any time the Doxygen comments in the libmaple source code are changed), you'll need to rebuild libmaple's Doxygen XML output. That is, from within the - libmaple (i.e., NOT THIS REPOSITORY), run: + libmaple repository (i.e., NOT THIS REPOSITORY), run: $ make doxygen -5. Finally, you can build the documentation (in this folder): +2. Finally, you can build the documentation (in this folder): $ make html -- cgit v1.2.3 From 614dcf6613e79d68894bd41a329b2c407c2a50fb Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 22 Aug 2011 23:33:56 -0400 Subject: troubleshooting: Add target for throb() item. --- source/troubleshooting.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 7654c40..4d7cbb0 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -14,6 +14,8 @@ This page documents common problems and their solutions. Hardware problems =================== +.. _troubleshooting-throb: + The LED is throbbing and my program is stopped! ----------------------------------------------- -- cgit v1.2.3 From 6a6a7c31c3b1a920a73dbc1f11dc502de7e776cd Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 22 Aug 2011 23:34:20 -0400 Subject: libmaple.rst: Add "libmaple vs. wirish" target. --- source/libmaple.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/libmaple.rst b/source/libmaple.rst index d9f30be..60bf814 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -13,6 +13,8 @@ Cortex M3 microcontrollers. Its high-level interfaces are libraries written for the `Arduino `_ and `Wiring `_ development boards. +.. _libmaple-vs-wirish: + libmaple is split into two pieces: a lower level layer written in pure C, which we call *libmaple proper* (in the `libmaple/ `_ -- cgit v1.2.3 From c6ba836ad1fbda247d9622b2f372a0c9c0cdbfd9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 22 Aug 2011 23:37:16 -0400 Subject: Better document libmaple proper APIs. Instead of using doxygenfile, add finely-grained documentation for each libmaple proper header that we guarantee an API for. These new files are in keeping with the template provided in /tmpl/libmaple-proper-page.rst.tmpl. Breathe still has to be taught how to do doxygenunion to get some of this right, but I'm committing this now in anticipation of that happening. --- source/libmaple/api/adc.rst | 211 +++++++++++++++- source/libmaple/api/bitband.rst | 11 +- source/libmaple/api/bkp.rst | 73 +++++- source/libmaple/api/dac.rst | 119 ++++++++- source/libmaple/api/delay.rst | 8 +- source/libmaple/api/dma.rst | 216 +++++++++++++++- source/libmaple/api/exti.rst | 33 ++- source/libmaple/api/flash.rst | 93 ++++++- source/libmaple/api/fsmc.rst | 185 +++++++++++++- source/libmaple/api/gpio.rst | 237 ++++++++++++++++- source/libmaple/api/i2c.rst | 120 ++++++++- source/libmaple/api/iwdg.rst | 69 ++++- source/libmaple/api/libmaple.rst | 9 +- source/libmaple/api/libmaple_types.rst | 39 ++- source/libmaple/api/nvic.rst | 39 ++- source/libmaple/api/pwr.rst | 47 +++- source/libmaple/api/rcc.rst | 373 ++++++++++++++++++++++++++- source/libmaple/api/ring_buffer.rst | 23 +- source/libmaple/api/scb.rst | 26 +- source/libmaple/api/spi.rst | 183 +++++++++++++- source/libmaple/api/stm32.rst | 15 +- source/libmaple/api/systick.rst | 58 ++++- source/libmaple/api/timer.rst | 449 ++++++++++++++++++++++++++++++++- source/libmaple/api/usart.rst | 192 +++++++++++++- source/libmaple/api/util.rst | 47 +++- 25 files changed, 2773 insertions(+), 102 deletions(-) diff --git a/source/libmaple/api/adc.rst b/source/libmaple/api/adc.rst index 8817055..fecaece 100644 --- a/source/libmaple/api/adc.rst +++ b/source/libmaple/api/adc.rst @@ -4,9 +4,212 @@ ``adc.h`` ========= -[Stub] support. +:ref:`Analog to Digital Conversion ` (ADC) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: adc.h +Types +----- + +.. doxygenstruct:: adc_dev +.. doxygenstruct:: adc_reg_map +.. doxygenenum:: adc_extsel_event +.. doxygenenum:: adc_smp_rate + +Devices +------- + +.. doxygenvariable:: ADC1 +.. doxygenvariable:: ADC2 +.. doxygenvariable:: ADC3 + +Functions +--------- + +.. doxygenfunction:: adc_init +.. doxygenfunction:: adc_calibrate +.. doxygenfunction:: adc_set_extsel +.. doxygenfunction:: adc_enable +.. doxygenfunction:: adc_disable +.. doxygenfunction:: adc_disable_all +.. doxygenfunction:: adc_foreach +.. doxygenfunction:: adc_set_sample_rate +.. doxygenfunction:: adc_read +.. doxygenfunction:: adc_set_reg_seqlen +.. doxygenfunction:: adc_set_exttrig + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: ADC1_BASE +.. doxygendefine:: ADC2_BASE +.. doxygendefine:: ADC3_BASE + +Register Bit Definitions +------------------------ + +Status register +~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_SR_AWD_BIT +.. doxygendefine:: ADC_SR_EOC_BIT +.. doxygendefine:: ADC_SR_JEOC_BIT +.. doxygendefine:: ADC_SR_JSTRT_BIT +.. doxygendefine:: ADC_SR_STRT_BIT + +.. doxygendefine:: ADC_SR_AWD +.. doxygendefine:: ADC_SR_EOC +.. doxygendefine:: ADC_SR_JEOC +.. doxygendefine:: ADC_SR_JSTRT +.. doxygendefine:: ADC_SR_STRT + +Control register 1 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_CR1_EOCIE_BIT +.. doxygendefine:: ADC_CR1_AWDIE_BIT +.. doxygendefine:: ADC_CR1_JEOCIE_BIT +.. doxygendefine:: ADC_CR1_SCAN_BIT +.. doxygendefine:: ADC_CR1_AWDSGL_BIT +.. doxygendefine:: ADC_CR1_JAUTO_BIT +.. doxygendefine:: ADC_CR1_DISCEN_BIT +.. doxygendefine:: ADC_CR1_JDISCEN_BIT +.. doxygendefine:: ADC_CR1_JAWDEN_BIT +.. doxygendefine:: ADC_CR1_AWDEN_BIT + +.. doxygendefine:: ADC_CR1_AWDCH +.. doxygendefine:: ADC_CR1_EOCIE +.. doxygendefine:: ADC_CR1_AWDIE +.. doxygendefine:: ADC_CR1_JEOCIE +.. doxygendefine:: ADC_CR1_SCAN +.. doxygendefine:: ADC_CR1_AWDSGL +.. doxygendefine:: ADC_CR1_JAUTO +.. doxygendefine:: ADC_CR1_DISCEN +.. doxygendefine:: ADC_CR1_JDISCEN +.. doxygendefine:: ADC_CR1_DISCNUM +.. doxygendefine:: ADC_CR1_JAWDEN +.. doxygendefine:: ADC_CR1_AWDEN + +Control register 2 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_CR2_ADON_BIT +.. doxygendefine:: ADC_CR2_CONT_BIT +.. doxygendefine:: ADC_CR2_CAL_BIT +.. doxygendefine:: ADC_CR2_RSTCAL_BIT +.. doxygendefine:: ADC_CR2_DMA_BIT +.. doxygendefine:: ADC_CR2_ALIGN_BIT +.. doxygendefine:: ADC_CR2_JEXTTRIG_BIT +.. doxygendefine:: ADC_CR2_EXTTRIG_BIT +.. doxygendefine:: ADC_CR2_JSWSTART_BIT +.. doxygendefine:: ADC_CR2_SWSTART_BIT +.. doxygendefine:: ADC_CR2_TSEREFE_BIT + +.. doxygendefine:: ADC_CR2_ADON +.. doxygendefine:: ADC_CR2_CONT +.. doxygendefine:: ADC_CR2_CAL +.. doxygendefine:: ADC_CR2_RSTCAL +.. doxygendefine:: ADC_CR2_DMA +.. doxygendefine:: ADC_CR2_ALIGN +.. doxygendefine:: ADC_CR2_JEXTSEL +.. doxygendefine:: ADC_CR2_JEXTTRIG +.. doxygendefine:: ADC_CR2_EXTSEL +.. doxygendefine:: ADC_CR2_EXTTRIG +.. doxygendefine:: ADC_CR2_JSWSTART +.. doxygendefine:: ADC_CR2_SWSTART +.. doxygendefine:: ADC_CR2_TSEREFE + +Sample time register 1 +~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_SMPR1_SMP17 +.. doxygendefine:: ADC_SMPR1_SMP16 +.. doxygendefine:: ADC_SMPR1_SMP15 +.. doxygendefine:: ADC_SMPR1_SMP14 +.. doxygendefine:: ADC_SMPR1_SMP13 +.. doxygendefine:: ADC_SMPR1_SMP12 +.. doxygendefine:: ADC_SMPR1_SMP11 +.. doxygendefine:: ADC_SMPR1_SMP10 + +Sample time register 2 +~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_SMPR2_SMP9 +.. doxygendefine:: ADC_SMPR2_SMP8 +.. doxygendefine:: ADC_SMPR2_SMP7 +.. doxygendefine:: ADC_SMPR2_SMP6 +.. doxygendefine:: ADC_SMPR2_SMP5 +.. doxygendefine:: ADC_SMPR2_SMP4 +.. doxygendefine:: ADC_SMPR2_SMP3 +.. doxygendefine:: ADC_SMPR2_SMP2 +.. doxygendefine:: ADC_SMPR2_SMP1 +.. doxygendefine:: ADC_SMPR2_SMP0 + +Injected channel data offset register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_JOFR_JOFFSET + +Watchdog high threshold register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_HTR_HT + +Watchdog low threshold register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_LTR_LT + +Regular sequence register 1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_SQR1_L +.. doxygendefine:: ADC_SQR1_SQ16 +.. doxygendefine:: ADC_SQR1_SQ15 +.. doxygendefine:: ADC_SQR1_SQ14 +.. doxygendefine:: ADC_SQR1_SQ13 + +Regular sequence register 2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_SQR2_SQ12 +.. doxygendefine:: ADC_SQR2_SQ11 +.. doxygendefine:: ADC_SQR2_SQ10 +.. doxygendefine:: ADC_SQR2_SQ9 +.. doxygendefine:: ADC_SQR2_SQ8 +.. doxygendefine:: ADC_SQR2_SQ7 + +Regular sequence register 3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_SQR3_SQ6 +.. doxygendefine:: ADC_SQR3_SQ5 +.. doxygendefine:: ADC_SQR3_SQ4 +.. doxygendefine:: ADC_SQR3_SQ3 +.. doxygendefine:: ADC_SQR3_SQ2 +.. doxygendefine:: ADC_SQR3_SQ1 + +Injected sequence register +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_JSQR_JL +.. doxygendefine:: ADC_JSQR_JL_1CONV +.. doxygendefine:: ADC_JSQR_JL_2CONV +.. doxygendefine:: ADC_JSQR_JL_3CONV +.. doxygendefine:: ADC_JSQR_JL_4CONV +.. doxygendefine:: ADC_JSQR_JSQ4 +.. doxygendefine:: ADC_JSQR_JSQ3 +.. doxygendefine:: ADC_JSQR_JSQ2 +.. doxygendefine:: ADC_JSQR_JSQ1 + +Injected data registers +~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_JDR_JDATA + +Regular data register +~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: ADC_DR_ADC2DATA +.. doxygendefine:: ADC_DR_DATA diff --git a/source/libmaple/api/bitband.rst b/source/libmaple/api/bitband.rst index fd57944..5251015 100644 --- a/source/libmaple/api/bitband.rst +++ b/source/libmaple/api/bitband.rst @@ -4,9 +4,12 @@ ``bitband.h`` ============= -[Stub] support. +Bit-banding support. -Library Documentation ---------------------- +Functions +--------- -.. doxygenfile:: bitband.h +.. doxygenfunction:: bb_sram_get_bit +.. doxygenfunction:: bb_sram_set_bit +.. doxygenfunction:: bb_peri_get_bit +.. doxygenfunction:: bb_peri_set_bit diff --git a/source/libmaple/api/bkp.rst b/source/libmaple/api/bkp.rst index 9a697c7..4f0115b 100644 --- a/source/libmaple/api/bkp.rst +++ b/source/libmaple/api/bkp.rst @@ -4,9 +4,76 @@ ``bkp.h`` ========= -[Stub] support. +Backup register (BKP) suport. -Library Documentation +.. contents:: Contents + :local: + +Types +----- + +.. doxygenstruct:: bkp_dev +.. doxygenstruct:: bkp_reg_map + +Devices +------- + +.. doxygenvariable:: BKP + +Convenience Functions --------------------- -.. doxygenfile:: bkp.h +.. doxygenfunction:: bkp_init +.. doxygenfunction:: bkp_enable_writes +.. doxygenfunction:: bkp_disable_writes +.. doxygenfunction:: bkp_read +.. doxygenfunction:: bkp_write + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: BKP_BASE + +Register Bit Definitions +------------------------ + +Data Registers +~~~~~~~~~~~~~~ + +.. doxygendefine:: BKP_DR_D + +RTC Clock Calibration Register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: BKP_RTCCR_ASOS_BIT +.. doxygendefine:: BKP_RTCCR_ASOE_BIT +.. doxygendefine:: BKP_RTCCR_CCO_BIT + +.. doxygendefine:: BKP_RTCCR_ASOS +.. doxygendefine:: BKP_RTCCR_ASOE +.. doxygendefine:: BKP_RTCCR_CCO +.. doxygendefine:: BKP_RTCCR_CAL + +Backup control register +~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: BKP_CR_TPAL_BIT +.. doxygendefine:: BKP_CR_TPE_BIT + +.. doxygendefine:: BKP_CR_TPAL +.. doxygendefine:: BKP_CR_TPE + +Backup control/status register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: BKP_CSR_TIF_BIT +.. doxygendefine:: BKP_CSR_TEF_BIT +.. doxygendefine:: BKP_CSR_TPIE_BIT +.. doxygendefine:: BKP_CSR_CTI_BIT +.. doxygendefine:: BKP_CSR_CTE_BIT + +.. doxygendefine:: BKP_CSR_TIF +.. doxygendefine:: BKP_CSR_TEF +.. doxygendefine:: BKP_CSR_TPIE +.. doxygendefine:: BKP_CSR_CTI +.. doxygendefine:: BKP_CSR_CTE diff --git a/source/libmaple/api/dac.rst b/source/libmaple/api/dac.rst index 038753b..55c8faf 100644 --- a/source/libmaple/api/dac.rst +++ b/source/libmaple/api/dac.rst @@ -4,9 +4,120 @@ ``dac.h`` ========= -[Stub] support. +Digital to Analog Conversion (DAC) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: dac.h +Types +----- + +.. doxygenstruct:: dac_dev +.. doxygenstruct:: dac_reg_map + +Devices +------- + +.. doxygenvariable:: DAC + +Functions +--------- + +.. doxygenfunction:: dac_init +.. doxygenfunction:: dac_write_channel +.. doxygenfunction:: dac_enable_channel +.. doxygenfunction:: dac_disable_channel + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: DAC_BASE + +Register Bit Definitions +------------------------ + +Control register +~~~~~~~~~~~~~~~~ + +**Channel 1**: + +.. doxygendefine:: DAC_CR_EN1 +.. doxygendefine:: DAC_CR_BOFF1 +.. doxygendefine:: DAC_CR_TEN1 +.. doxygendefine:: DAC_CR_TSEL1 +.. doxygendefine:: DAC_CR_WAVE1 +.. doxygendefine:: DAC_CR_MAMP1 +.. doxygendefine:: DAC_CR_DMAEN1 + +**Channel 2**: + +.. doxygendefine:: DAC_CR_EN2 +.. doxygendefine:: DAC_CR_BOFF2 +.. doxygendefine:: DAC_CR_TEN2 +.. doxygendefine:: DAC_CR_TSEL2 +.. doxygendefine:: DAC_CR_WAVE2 +.. doxygendefine:: DAC_CR_MAMP2 +.. doxygendefine:: DAC_CR_DMAEN2 + +Software trigger register +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_SWTRIGR_SWTRIG1 +.. doxygendefine:: DAC_SWTRIGR_SWTRIG2 + +Channel 1 12-bit right-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR12R1_DACC1DHR + +Channel 1 12-bit left-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR12L1_DACC1DHR + +Channel 1 8-bit left-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR8R1_DACC1DHR + +Channel 2 12-bit right-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR12R2_DACC2DHR + +Channel 2 12-bit left-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR12L2_DACC2DHR + +Channel 2 8-bit left-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR8R2_DACC2DHR + +Dual DAC 12-bit right-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR12RD_DACC1DHR +.. doxygendefine:: DAC_DHR12RD_DACC2DHR + +Dual DAC 12-bit left-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR12LD_DACC1DHR +.. doxygendefine:: DAC_DHR12LD_DACC2DHR + +Dual DAC 8-bit left-aligned data holding register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DHR8RD_DACC1DHR +.. doxygendefine:: DAC_DHR8RD_DACC2DHR + +Channel 1 data output register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DAC_DOR1_DACC1DOR + +Channel 1 data output register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. doxygendefine:: DAC_DOR2_DACC2DOR diff --git a/source/libmaple/api/delay.rst b/source/libmaple/api/delay.rst index a0d013a..5d0397d 100644 --- a/source/libmaple/api/delay.rst +++ b/source/libmaple/api/delay.rst @@ -4,9 +4,9 @@ ``delay.h`` =========== -[Stub] support. +Simple busy-loop delaying. -Library Documentation ---------------------- +Functions +--------- -.. doxygenfile:: delay.h +.. doxygenfunction:: delay_us diff --git a/source/libmaple/api/dma.rst b/source/libmaple/api/dma.rst index 1512d0c..2acca41 100644 --- a/source/libmaple/api/dma.rst +++ b/source/libmaple/api/dma.rst @@ -4,9 +4,217 @@ ``dma.h`` ========= -[Stub] support. +Direct Memory Access (DMA) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: dma.h +Types +----- + +.. doxygenstruct:: dma_reg_map +.. doxygenstruct:: dma_dev +.. doxygenstruct:: dma_handler_config +.. doxygenenum:: dma_mode_flags +.. doxygenenum:: dma_xfer_size +.. doxygenenum:: dma_channel +.. doxygenenum:: dma_priority +.. doxygenenum:: dma_irq_cause +.. doxygenstruct:: dma_channel_reg_map + +Devices +------- + +.. doxygenvariable:: DMA1 +.. doxygenvariable:: DMA2 + +Functions +--------- + +.. TODO [0.0.11?] figure out the dma_attach_interrupt weirdness + +.. warning:: There currently appear to be problems with + the dma_attach_interrupt() implementation. + +.. doxygenfunction:: dma_init +.. doxygenfunction:: dma_setup_transfer +.. doxygenfunction:: dma_set_num_transfers +.. doxygenfunction:: dma_set_priority +.. doxygenfunction:: dma_attach_interrupt +.. doxygenfunction:: dma_detach_interrupt +.. doxygenfunction:: dma_get_irq_cause +.. doxygenfunction:: dma_enable +.. doxygenfunction:: dma_disable +.. doxygenfunction:: dma_set_mem_addr +.. doxygenfunction:: dma_set_per_addr +.. doxygenfunction:: dma_channel_regs +.. doxygenfunction:: dma_is_channel_enabled +.. doxygenfunction:: dma_get_isr_bits +.. doxygenfunction:: dma_clear_isr_bits + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: DMA1_BASE +.. doxygendefine:: DMA2_BASE + +Register Bit Definitions +------------------------ + +Interrupt status register +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DMA_ISR_TEIF7_BIT +.. doxygendefine:: DMA_ISR_HTIF7_BIT +.. doxygendefine:: DMA_ISR_TCIF7_BIT +.. doxygendefine:: DMA_ISR_GIF7_BIT +.. doxygendefine:: DMA_ISR_TEIF6_BIT +.. doxygendefine:: DMA_ISR_HTIF6_BIT +.. doxygendefine:: DMA_ISR_TCIF6_BIT +.. doxygendefine:: DMA_ISR_GIF6_BIT +.. doxygendefine:: DMA_ISR_TEIF5_BIT +.. doxygendefine:: DMA_ISR_HTIF5_BIT +.. doxygendefine:: DMA_ISR_TCIF5_BIT +.. doxygendefine:: DMA_ISR_GIF5_BIT +.. doxygendefine:: DMA_ISR_TEIF4_BIT +.. doxygendefine:: DMA_ISR_HTIF4_BIT +.. doxygendefine:: DMA_ISR_TCIF4_BIT +.. doxygendefine:: DMA_ISR_GIF4_BIT +.. doxygendefine:: DMA_ISR_TEIF3_BIT +.. doxygendefine:: DMA_ISR_HTIF3_BIT +.. doxygendefine:: DMA_ISR_TCIF3_BIT +.. doxygendefine:: DMA_ISR_GIF3_BIT +.. doxygendefine:: DMA_ISR_TEIF2_BIT +.. doxygendefine:: DMA_ISR_HTIF2_BIT +.. doxygendefine:: DMA_ISR_TCIF2_BIT +.. doxygendefine:: DMA_ISR_GIF2_BIT +.. doxygendefine:: DMA_ISR_TEIF1_BIT +.. doxygendefine:: DMA_ISR_HTIF1_BIT +.. doxygendefine:: DMA_ISR_TCIF1_BIT +.. doxygendefine:: DMA_ISR_GIF1_BIT + +.. doxygendefine:: DMA_ISR_TEIF7 +.. doxygendefine:: DMA_ISR_HTIF7 +.. doxygendefine:: DMA_ISR_TCIF7 +.. doxygendefine:: DMA_ISR_GIF7 +.. doxygendefine:: DMA_ISR_TEIF6 +.. doxygendefine:: DMA_ISR_HTIF6 +.. doxygendefine:: DMA_ISR_TCIF6 +.. doxygendefine:: DMA_ISR_GIF6 +.. doxygendefine:: DMA_ISR_TEIF5 +.. doxygendefine:: DMA_ISR_HTIF5 +.. doxygendefine:: DMA_ISR_TCIF5 +.. doxygendefine:: DMA_ISR_GIF5 +.. doxygendefine:: DMA_ISR_TEIF4 +.. doxygendefine:: DMA_ISR_HTIF4 +.. doxygendefine:: DMA_ISR_TCIF4 +.. doxygendefine:: DMA_ISR_GIF4 +.. doxygendefine:: DMA_ISR_TEIF3 +.. doxygendefine:: DMA_ISR_HTIF3 +.. doxygendefine:: DMA_ISR_TCIF3 +.. doxygendefine:: DMA_ISR_GIF3 +.. doxygendefine:: DMA_ISR_TEIF2 +.. doxygendefine:: DMA_ISR_HTIF2 +.. doxygendefine:: DMA_ISR_TCIF2 +.. doxygendefine:: DMA_ISR_GIF2 +.. doxygendefine:: DMA_ISR_TEIF1 +.. doxygendefine:: DMA_ISR_HTIF1 +.. doxygendefine:: DMA_ISR_TCIF1 +.. doxygendefine:: DMA_ISR_GIF1 + +Interrupt flag clear register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DMA_IFCR_CTEIF7_BIT +.. doxygendefine:: DMA_IFCR_CHTIF7_BIT +.. doxygendefine:: DMA_IFCR_CTCIF7_BIT +.. doxygendefine:: DMA_IFCR_CGIF7_BIT +.. doxygendefine:: DMA_IFCR_CTEIF6_BIT +.. doxygendefine:: DMA_IFCR_CHTIF6_BIT +.. doxygendefine:: DMA_IFCR_CTCIF6_BIT +.. doxygendefine:: DMA_IFCR_CGIF6_BIT +.. doxygendefine:: DMA_IFCR_CTEIF5_BIT +.. doxygendefine:: DMA_IFCR_CHTIF5_BIT +.. doxygendefine:: DMA_IFCR_CTCIF5_BIT +.. doxygendefine:: DMA_IFCR_CGIF5_BIT +.. doxygendefine:: DMA_IFCR_CTEIF4_BIT +.. doxygendefine:: DMA_IFCR_CHTIF4_BIT +.. doxygendefine:: DMA_IFCR_CTCIF4_BIT +.. doxygendefine:: DMA_IFCR_CGIF4_BIT +.. doxygendefine:: DMA_IFCR_CTEIF3_BIT +.. doxygendefine:: DMA_IFCR_CHTIF3_BIT +.. doxygendefine:: DMA_IFCR_CTCIF3_BIT +.. doxygendefine:: DMA_IFCR_CGIF3_BIT +.. doxygendefine:: DMA_IFCR_CTEIF2_BIT +.. doxygendefine:: DMA_IFCR_CHTIF2_BIT +.. doxygendefine:: DMA_IFCR_CTCIF2_BIT +.. doxygendefine:: DMA_IFCR_CGIF2_BIT +.. doxygendefine:: DMA_IFCR_CTEIF1_BIT +.. doxygendefine:: DMA_IFCR_CHTIF1_BIT +.. doxygendefine:: DMA_IFCR_CTCIF1_BIT +.. doxygendefine:: DMA_IFCR_CGIF1_BIT + +.. doxygendefine:: DMA_IFCR_CTEIF7 +.. doxygendefine:: DMA_IFCR_CHTIF7 +.. doxygendefine:: DMA_IFCR_CTCIF7 +.. doxygendefine:: DMA_IFCR_CGIF7 +.. doxygendefine:: DMA_IFCR_CTEIF6 +.. doxygendefine:: DMA_IFCR_CHTIF6 +.. doxygendefine:: DMA_IFCR_CTCIF6 +.. doxygendefine:: DMA_IFCR_CGIF6 +.. doxygendefine:: DMA_IFCR_CTEIF5 +.. doxygendefine:: DMA_IFCR_CHTIF5 +.. doxygendefine:: DMA_IFCR_CTCIF5 +.. doxygendefine:: DMA_IFCR_CGIF5 +.. doxygendefine:: DMA_IFCR_CTEIF4 +.. doxygendefine:: DMA_IFCR_CHTIF4 +.. doxygendefine:: DMA_IFCR_CTCIF4 +.. doxygendefine:: DMA_IFCR_CGIF4 +.. doxygendefine:: DMA_IFCR_CTEIF3 +.. doxygendefine:: DMA_IFCR_CHTIF3 +.. doxygendefine:: DMA_IFCR_CTCIF3 +.. doxygendefine:: DMA_IFCR_CGIF3 +.. doxygendefine:: DMA_IFCR_CTEIF2 +.. doxygendefine:: DMA_IFCR_CHTIF2 +.. doxygendefine:: DMA_IFCR_CTCIF2 +.. doxygendefine:: DMA_IFCR_CGIF2 +.. doxygendefine:: DMA_IFCR_CTEIF1 +.. doxygendefine:: DMA_IFCR_CHTIF1 +.. doxygendefine:: DMA_IFCR_CTCIF1 +.. doxygendefine:: DMA_IFCR_CGIF1 + +Channel configuration register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: DMA_CCR_MEM2MEM_BIT +.. doxygendefine:: DMA_CCR_MINC_BIT +.. doxygendefine:: DMA_CCR_PINC_BIT +.. doxygendefine:: DMA_CCR_CIRC_BIT +.. doxygendefine:: DMA_CCR_DIR_BIT +.. doxygendefine:: DMA_CCR_TEIE_BIT +.. doxygendefine:: DMA_CCR_HTIE_BIT +.. doxygendefine:: DMA_CCR_TCIE_BIT +.. doxygendefine:: DMA_CCR_EN_BIT + +.. doxygendefine:: DMA_CCR_MEM2MEM +.. doxygendefine:: DMA_CCR_PL +.. doxygendefine:: DMA_CCR_PL_LOW +.. doxygendefine:: DMA_CCR_PL_MEDIUM +.. doxygendefine:: DMA_CCR_PL_HIGH +.. doxygendefine:: DMA_CCR_PL_VERY_HIGH +.. doxygendefine:: DMA_CCR_MSIZE +.. doxygendefine:: DMA_CCR_MSIZE_8BITS +.. doxygendefine:: DMA_CCR_MSIZE_16BITS +.. doxygendefine:: DMA_CCR_MSIZE_32BITS +.. doxygendefine:: DMA_CCR_PSIZE +.. doxygendefine:: DMA_CCR_PSIZE_8BITS +.. doxygendefine:: DMA_CCR_PSIZE_16BITS +.. doxygendefine:: DMA_CCR_PSIZE_32BITS +.. doxygendefine:: DMA_CCR_MINC +.. doxygendefine:: DMA_CCR_PINC +.. doxygendefine:: DMA_CCR_CIRC +.. doxygendefine:: DMA_CCR_DIR +.. doxygendefine:: DMA_CCR_TEIE +.. doxygendefine:: DMA_CCR_HTIE +.. doxygendefine:: DMA_CCR_TCIE +.. doxygendefine:: DMA_CCR_EN diff --git a/source/libmaple/api/exti.rst b/source/libmaple/api/exti.rst index 2909aa7..1038fbf 100644 --- a/source/libmaple/api/exti.rst +++ b/source/libmaple/api/exti.rst @@ -4,9 +4,34 @@ ``exti.h`` ========== -[Stub] support. +:ref:`External interrupt ` support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: exti.h +Types +----- + +.. doxygenstruct:: exti_reg_map +.. doxygenenum:: exti_trigger_mode + +Devices +------- + +None at this time. + +Functions +--------- + +.. doxygenfunction:: exti_attach_interrupt +.. doxygenfunction:: exti_detach_interrupt + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: EXTI_BASE + +Register Bit Definitions +------------------------ + +None at this time. diff --git a/source/libmaple/api/flash.rst b/source/libmaple/api/flash.rst index 6f2f9d3..8a7e79b 100644 --- a/source/libmaple/api/flash.rst +++ b/source/libmaple/api/flash.rst @@ -4,9 +4,94 @@ ``flash.h`` =========== -[Stub] support. +Flash support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: flash.h +Types +----- + +.. doxygenstruct:: flash_reg_map + +Functions +--------- + +.. doxygenfunction:: flash_enable_prefetch +.. doxygenfunction:: flash_set_latency + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: FLASH_BASE + +Register Bit Definitions +------------------------ + +Access control register +~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FLASH_ACR_PRFTBS_BIT +.. doxygendefine:: FLASH_ACR_PRFTBE_BIT +.. doxygendefine:: FLASH_ACR_HLFCYA_BIT + +.. doxygendefine:: FLASH_ACR_PRFTBS +.. doxygendefine:: FLASH_ACR_PRFTBE +.. doxygendefine:: FLASH_ACR_HLFCYA +.. doxygendefine:: FLASH_ACR_LATENCY + +Status register +~~~~~~~~~~~~~~~ + +.. doxygendefine:: FLASH_SR_EOP_BIT +.. doxygendefine:: FLASH_SR_WRPRTERR_BIT +.. doxygendefine:: FLASH_SR_PGERR_BIT +.. doxygendefine:: FLASH_SR_BSY_BIT + +.. doxygendefine:: FLASH_SR_EOP +.. doxygendefine:: FLASH_SR_WRPRTERR +.. doxygendefine:: FLASH_SR_PGERR +.. doxygendefine:: FLASH_SR_BSY + +Control register +~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FLASH_CR_EOPIE_BIT +.. doxygendefine:: FLASH_CR_ERRIE_BIT +.. doxygendefine:: FLASH_CR_OPTWRE_BIT +.. doxygendefine:: FLASH_CR_LOCK_BIT +.. doxygendefine:: FLASH_CR_STRT_BIT +.. doxygendefine:: FLASH_CR_OPTER_BIT +.. doxygendefine:: FLASH_CR_OPTPG_BIT +.. doxygendefine:: FLASH_CR_MER_BIT +.. doxygendefine:: FLASH_CR_PER_BIT +.. doxygendefine:: FLASH_CR_PG_BIT + +.. doxygendefine:: FLASH_CR_EOPIE +.. doxygendefine:: FLASH_CR_ERRIE +.. doxygendefine:: FLASH_CR_OPTWRE +.. doxygendefine:: FLASH_CR_LOCK +.. doxygendefine:: FLASH_CR_STRT +.. doxygendefine:: FLASH_CR_OPTER +.. doxygendefine:: FLASH_CR_OPTPG +.. doxygendefine:: FLASH_CR_MER +.. doxygendefine:: FLASH_CR_PER +.. doxygendefine:: FLASH_CR_PG + +Option byte register +~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FLASH_OBR_nRST_STDBY_BIT +.. doxygendefine:: FLASH_OBR_nRST_STOP_BIT +.. doxygendefine:: FLASH_OBR_WDG_SW_BIT +.. doxygendefine:: FLASH_OBR_RDPRT_BIT +.. doxygendefine:: FLASH_OBR_OPTERR_BIT + +.. doxygendefine:: FLASH_OBR_DATA1 +.. doxygendefine:: FLASH_OBR_DATA0 +.. doxygendefine:: FLASH_OBR_USER +.. doxygendefine:: FLASH_OBR_nRST_STDBY +.. doxygendefine:: FLASH_OBR_nRST_STOP +.. doxygendefine:: FLASH_OBR_WDG_SW +.. doxygendefine:: FLASH_OBR_RDPRT +.. doxygendefine:: FLASH_OBR_OPTERR diff --git a/source/libmaple/api/fsmc.rst b/source/libmaple/api/fsmc.rst index cecfc99..3b356cc 100644 --- a/source/libmaple/api/fsmc.rst +++ b/source/libmaple/api/fsmc.rst @@ -4,9 +4,186 @@ ``fsmc.h`` ========== -[Stub] support. +Flexible Static Memory Controller (FSMC) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: fsmc.h +Types +----- + +.. doxygenstruct:: fsmc_reg_map +.. doxygenstruct:: fsmc_nor_psram_reg_map + +Devices +------- + +None at this time. + +Functions +--------- + +.. doxygenfunction:: fsmc_sram_init_gpios +.. doxygenfunction:: fsmc_nor_psram_set_datast +.. doxygenfunction:: fsmc_nor_psram_set_addset + +Memory Bank Boundary Addresses +------------------------------ + +.. doxygendefine:: FSMC_BANK1 +.. doxygendefine:: FSMC_BANK2 +.. doxygendefine:: FSMC_BANK3 +.. doxygendefine:: FSMC_BANK4 + +.. doxygendefine:: FSMC_NOR_PSRAM_REGION1 +.. doxygendefine:: FSMC_NOR_PSRAM_REGION2 +.. doxygendefine:: FSMC_NOR_PSRAM_REGION3 +.. doxygendefine:: FSMC_NOR_PSRAM_REGION4 + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: FSMC_BASE + +.. doxygendefine:: FSMC_NOR_PSRAM1_BASE +.. doxygendefine:: FSMC_NOR_PSRAM2_BASE +.. doxygendefine:: FSMC_NOR_PSRAM3_BASE +.. doxygendefine:: FSMC_NOR_PSRAM4_BASE + +Register Bit Definitions +------------------------ + +NOR/PSRAM Chip-Select Control Registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_BCR_CBURSTRW_BIT +.. doxygendefine:: FSMC_BCR_ASYNCWAIT_BIT +.. doxygendefine:: FSMC_BCR_EXTMOD_BIT +.. doxygendefine:: FSMC_BCR_WAITEN_BIT +.. doxygendefine:: FSMC_BCR_WREN_BIT +.. doxygendefine:: FSMC_BCR_WAITCFG_BIT +.. doxygendefine:: FSMC_BCR_WRAPMOD_BIT +.. doxygendefine:: FSMC_BCR_WAITPOL_BIT +.. doxygendefine:: FSMC_BCR_BURSTEN_BIT +.. doxygendefine:: FSMC_BCR_FACCEN_BIT +.. doxygendefine:: FSMC_BCR_MUXEN_BIT +.. doxygendefine:: FSMC_BCR_MBKEN_BIT + +.. doxygendefine:: FSMC_BCR_CBURSTRW +.. doxygendefine:: FSMC_BCR_ASYNCWAIT +.. doxygendefine:: FSMC_BCR_EXTMOD +.. doxygendefine:: FSMC_BCR_WAITEN +.. doxygendefine:: FSMC_BCR_WREN +.. doxygendefine:: FSMC_BCR_WAITCFG +.. doxygendefine:: FSMC_BCR_WRAPMOD +.. doxygendefine:: FSMC_BCR_WAITPOL +.. doxygendefine:: FSMC_BCR_BURSTEN +.. doxygendefine:: FSMC_BCR_FACCEN +.. doxygendefine:: FSMC_BCR_MWID +.. doxygendefine:: FSMC_BCR_MWID_8BITS +.. doxygendefine:: FSMC_BCR_MWID_16BITS +.. doxygendefine:: FSMC_BCR_MTYP +.. doxygendefine:: FSMC_BCR_MTYP_SRAM +.. doxygendefine:: FSMC_BCR_MTYP_PSRAM +.. doxygendefine:: FSMC_BCR_MTYP_NOR_FLASH +.. doxygendefine:: FSMC_BCR_MUXEN +.. doxygendefine:: FSMC_BCR_MBKEN + +SRAM/NOR-Flash Chip-Select Timing Registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_BTR_ACCMOD +.. doxygendefine:: FSMC_BTR_ACCMOD_A +.. doxygendefine:: FSMC_BTR_ACCMOD_B +.. doxygendefine:: FSMC_BTR_ACCMOD_C +.. doxygendefine:: FSMC_BTR_ACCMOD_D +.. doxygendefine:: FSMC_BTR_DATLAT +.. doxygendefine:: FSMC_BTR_CLKDIV +.. doxygendefine:: FSMC_BTR_BUSTURN +.. doxygendefine:: FSMC_BTR_DATAST +.. doxygendefine:: FSMC_BTR_ADDHLD +.. doxygendefine:: FSMC_BTR_ADDSET + +SRAM/NOR-Flash Write Timing Registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_BWTR_ACCMOD +.. doxygendefine:: FSMC_BWTR_ACCMOD_A +.. doxygendefine:: FSMC_BWTR_ACCMOD_B +.. doxygendefine:: FSMC_BWTR_ACCMOD_C +.. doxygendefine:: FSMC_BWTR_ACCMOD_D +.. doxygendefine:: FSMC_BWTR_DATLAT +.. doxygendefine:: FSMC_BWTR_CLKDIV +.. doxygendefine:: FSMC_BWTR_DATAST +.. doxygendefine:: FSMC_BWTR_ADDHLD +.. doxygendefine:: FSMC_BWTR_ADDSET + +NAND Flash/PC Card Controller Registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_PCR_ECCEN_BIT +.. doxygendefine:: FSMC_PCR_PTYP_BIT +.. doxygendefine:: FSMC_PCR_PBKEN_BIT +.. doxygendefine:: FSMC_PCR_PWAITEN_BIT + +.. doxygendefine:: FSMC_PCR_ECCPS +.. doxygendefine:: FSMC_PCR_ECCPS_256B +.. doxygendefine:: FSMC_PCR_ECCPS_512B +.. doxygendefine:: FSMC_PCR_ECCPS_1024B +.. doxygendefine:: FSMC_PCR_ECCPS_2048B +.. doxygendefine:: FSMC_PCR_ECCPS_4096B +.. doxygendefine:: FSMC_PCR_ECCPS_8192B +.. doxygendefine:: FSMC_PCR_TAR +.. doxygendefine:: FSMC_PCR_TCLR +.. doxygendefine:: FSMC_PCR_ECCEN +.. doxygendefine:: FSMC_PCR_PWID +.. doxygendefine:: FSMC_PCR_PWID_8BITS +.. doxygendefine:: FSMC_PCR_PWID_16BITS +.. doxygendefine:: FSMC_PCR_PTYP +.. doxygendefine:: FSMC_PCR_PTYP_PC_CF_PCMCIA +.. doxygendefine:: FSMC_PCR_PTYP_NAND +.. doxygendefine:: FSMC_PCR_PBKEN +.. doxygendefine:: FSMC_PCR_PWAITEN + +FIFO Status And Interrupt Registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_SR_FEMPT_BIT +.. doxygendefine:: FSMC_SR_IFEN_BIT +.. doxygendefine:: FSMC_SR_ILEN_BIT +.. doxygendefine:: FSMC_SR_IREN_BIT +.. doxygendefine:: FSMC_SR_IFS_BIT +.. doxygendefine:: FSMC_SR_ILS_BIT +.. doxygendefine:: FSMC_SR_IRS_BIT + +.. doxygendefine:: FSMC_SR_FEMPT +.. doxygendefine:: FSMC_SR_IFEN +.. doxygendefine:: FSMC_SR_ILEN +.. doxygendefine:: FSMC_SR_IREN +.. doxygendefine:: FSMC_SR_IFS +.. doxygendefine:: FSMC_SR_ILS +.. doxygendefine:: FSMC_SR_IRS + +Common Memory Space Timing Registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_PMEM_MEMHIZ +.. doxygendefine:: FSMC_PMEM_MEMHOLD +.. doxygendefine:: FSMC_PMEM_MEMWAIT +.. doxygendefine:: FSMC_PMEM_MEMSET + +Attribute Memory Space Timing Registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_PATT_ATTHIZ +.. doxygendefine:: FSMC_PATT_ATTHOLD +.. doxygendefine:: FSMC_PATT_ATTWAIT +.. doxygendefine:: FSMC_PATT_ATTSET + +I/O Space Timing Register 4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: FSMC_PIO_IOHIZ +.. doxygendefine:: FSMC_PIO_IOHOLD +.. doxygendefine:: FSMC_PIO_IOWAIT +.. doxygendefine:: FSMC_PIO_IOSET diff --git a/source/libmaple/api/gpio.rst b/source/libmaple/api/gpio.rst index 2cfec23..96058c0 100644 --- a/source/libmaple/api/gpio.rst +++ b/source/libmaple/api/gpio.rst @@ -4,9 +4,238 @@ ``gpio.h`` ========== -[Stub] support. +General Purpose Input/Output (GPIO) port and Alternate Function +Input/Output (AFIO) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: gpio.h +Types +----- + +.. doxygenstruct:: gpio_reg_map +.. doxygenstruct:: gpio_dev +.. doxygenenum:: gpio_pin_mode + +.. doxygenstruct:: afio_reg_map +.. doxygenenum:: afio_exti_port +.. doxygenenum:: afio_exti_num +.. doxygenenum:: afio_remap_peripheral +.. doxygenenum:: afio_debug_cfg + +Devices +------- + +.. doxygenvariable:: GPIOA +.. doxygenvariable:: GPIOB +.. doxygenvariable:: GPIOC +.. doxygenvariable:: GPIOD +.. doxygenvariable:: GPIOE +.. doxygenvariable:: GPIOF +.. doxygenvariable:: GPIOG + +Functions +--------- + +.. doxygenfunction:: gpio_init +.. doxygenfunction:: gpio_init_all +.. doxygenfunction:: gpio_set_mode +.. doxygenfunction:: gpio_exti_port +.. doxygenfunction:: gpio_write_bit +.. doxygenfunction:: gpio_read_bit +.. doxygenfunction:: gpio_toggle_bit + +.. doxygenfunction:: afio_init +.. doxygenfunction:: afio_exti_select +.. doxygenfunction:: afio_remap +.. doxygenfunction:: afio_cfg_debug_ports + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: GPIOA_BASE +.. doxygendefine:: GPIOB_BASE +.. doxygendefine:: GPIOC_BASE +.. doxygendefine:: GPIOD_BASE +.. doxygendefine:: GPIOE_BASE +.. doxygendefine:: GPIOF_BASE +.. doxygendefine:: GPIOG_BASE + +.. doxygendefine:: AFIO_BASE + +Register Bit Definitions +------------------------ + +GPIO Control Registers +~~~~~~~~~~~~~~~~~~~~~~ + +These values apply to both the low and high configuration registers +(ST RM0008: GPIOx_CRL and GPIOx_CRH). You can shift them right by the +appropriate number of bits for the GPIO port bit you're interested in +to obtain a bit mask. + +For example, to mask out just the value of GPIOA_CRH_CNF12, note that +GPIO port bit 12's configuration starts at bit 18 in the corresponding +CRH. Thus, an appropriate mask is ``GPIOA_BASE->CRH & (GPIO_CR_CNF << +18)``. + +.. doxygendefine:: GPIO_CR_CNF_INPUT_ANALOG +.. doxygendefine:: GPIO_CR_CNF_INPUT_FLOATING +.. doxygendefine:: GPIO_CR_CNF_INPUT_PU_PD +.. doxygendefine:: GPIO_CR_CNF_OUTPUT_PP +.. doxygendefine:: GPIO_CR_CNF_OUTPUT_OD +.. doxygendefine:: GPIO_CR_CNF_AF_OUTPUT_PP +.. doxygendefine:: GPIO_CR_CNF_AF_OUTPUT_OD +.. doxygendefine:: GPIO_CR_MODE_INPUT +.. doxygendefine:: GPIO_CR_MODE_OUTPUT_10MHZ +.. doxygendefine:: GPIO_CR_MODE_OUTPUT_2MHZ +.. doxygendefine:: GPIO_CR_MODE_OUTPUT_50MHZ + +Event Control Register +~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: AFIO_EVCR_EVOE +.. doxygendefine:: AFIO_EVCR_PORT_PA +.. doxygendefine:: AFIO_EVCR_PORT_PB +.. doxygendefine:: AFIO_EVCR_PORT_PC +.. doxygendefine:: AFIO_EVCR_PORT_PD +.. doxygendefine:: AFIO_EVCR_PORT_PE +.. doxygendefine:: AFIO_EVCR_PIN_0 +.. doxygendefine:: AFIO_EVCR_PIN_1 +.. doxygendefine:: AFIO_EVCR_PIN_2 +.. doxygendefine:: AFIO_EVCR_PIN_3 +.. doxygendefine:: AFIO_EVCR_PIN_4 +.. doxygendefine:: AFIO_EVCR_PIN_5 +.. doxygendefine:: AFIO_EVCR_PIN_6 +.. doxygendefine:: AFIO_EVCR_PIN_7 +.. doxygendefine:: AFIO_EVCR_PIN_8 +.. doxygendefine:: AFIO_EVCR_PIN_9 +.. doxygendefine:: AFIO_EVCR_PIN_10 +.. doxygendefine:: AFIO_EVCR_PIN_11 +.. doxygendefine:: AFIO_EVCR_PIN_12 +.. doxygendefine:: AFIO_EVCR_PIN_13 +.. doxygendefine:: AFIO_EVCR_PIN_14 +.. doxygendefine:: AFIO_EVCR_PIN_15 + +AF Remap and Debug I/O Configuration Register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: AFIO_MAPR_SWJ_CFG +.. doxygendefine:: AFIO_MAPR_SWJ_CFG_FULL_SWJ +.. doxygendefine:: AFIO_MAPR_SWJ_CFG_FULL_SWJ_NO_NJRST +.. doxygendefine:: AFIO_MAPR_SWJ_CFG_NO_JTAG_SW +.. doxygendefine:: AFIO_MAPR_SWJ_CFG_NO_JTAG_NO_SW +.. doxygendefine:: AFIO_MAPR_ADC2_ETRGREG_REMAP +.. doxygendefine:: AFIO_MAPR_ADC2_ETRGINJ_REMAP +.. doxygendefine:: AFIO_MAPR_ADC1_ETRGREG_REMAP +.. doxygendefine:: AFIO_MAPR_ADC1_ETRGINJ_REMAP +.. doxygendefine:: AFIO_MAPR_TIM5CH4_IREMAP +.. doxygendefine:: AFIO_MAPR_PD01_REMAP +.. doxygendefine:: AFIO_MAPR_CAN_REMAP +.. doxygendefine:: AFIO_MAPR_CAN_REMAP_NONE +.. doxygendefine:: AFIO_MAPR_CAN_REMAP_PB8_PB9 +.. doxygendefine:: AFIO_MAPR_CAN_REMAP_PD0_PD1 +.. doxygendefine:: AFIO_MAPR_TIM4_REMAP +.. doxygendefine:: AFIO_MAPR_TIM3_REMAP +.. doxygendefine:: AFIO_MAPR_TIM3_REMAP_NONE +.. doxygendefine:: AFIO_MAPR_TIM3_REMAP_PARTIAL +.. doxygendefine:: AFIO_MAPR_TIM3_REMAP_FULL +.. doxygendefine:: AFIO_MAPR_TIM2_REMAP +.. doxygendefine:: AFIO_MAPR_TIM2_REMAP_NONE +.. doxygendefine:: AFIO_MAPR_TIM2_REMAP_PA15_PB3_PA2_PA3 +.. doxygendefine:: AFIO_MAPR_TIM2_REMAP_PA0_PA1_PB10_PB11 +.. doxygendefine:: AFIO_MAPR_TIM2_REMAP_FULL +.. doxygendefine:: AFIO_MAPR_TIM1_REMAP +.. doxygendefine:: AFIO_MAPR_TIM1_REMAP_NONE +.. doxygendefine:: AFIO_MAPR_TIM1_REMAP_PARTIAL +.. doxygendefine:: AFIO_MAPR_TIM1_REMAP_FULL +.. doxygendefine:: AFIO_MAPR_USART3_REMAP +.. doxygendefine:: AFIO_MAPR_USART3_REMAP_NONE +.. doxygendefine:: AFIO_MAPR_USART3_REMAP_PARTIAL +.. doxygendefine:: AFIO_MAPR_USART3_REMAP_FULL +.. doxygendefine:: AFIO_MAPR_USART2_REMAP +.. doxygendefine:: AFIO_MAPR_USART1_REMAP +.. doxygendefine:: AFIO_MAPR_I2C1_REMAP +.. doxygendefine:: AFIO_MAPR_SPI1_REMAP + +External Interrupt Configuration Register 1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: AFIO_EXTICR1_EXTI3 +.. doxygendefine:: AFIO_EXTICR1_EXTI3_PA +.. doxygendefine:: AFIO_EXTICR1_EXTI3_PB +.. doxygendefine:: AFIO_EXTICR1_EXTI3_PC +.. doxygendefine:: AFIO_EXTICR1_EXTI3_PD +.. doxygendefine:: AFIO_EXTICR1_EXTI3_PE +.. doxygendefine:: AFIO_EXTICR1_EXTI3_PF +.. doxygendefine:: AFIO_EXTICR1_EXTI3_PG +.. doxygendefine:: AFIO_EXTICR1_EXTI2 +.. doxygendefine:: AFIO_EXTICR1_EXTI2_PA +.. doxygendefine:: AFIO_EXTICR1_EXTI2_PB +.. doxygendefine:: AFIO_EXTICR1_EXTI2_PC +.. doxygendefine:: AFIO_EXTICR1_EXTI2_PD +.. doxygendefine:: AFIO_EXTICR1_EXTI2_PE +.. doxygendefine:: AFIO_EXTICR1_EXTI2_PF +.. doxygendefine:: AFIO_EXTICR1_EXTI2_PG +.. doxygendefine:: AFIO_EXTICR1_EXTI1 +.. doxygendefine:: AFIO_EXTICR1_EXTI1_PA +.. doxygendefine:: AFIO_EXTICR1_EXTI1_PB +.. doxygendefine:: AFIO_EXTICR1_EXTI1_PC +.. doxygendefine:: AFIO_EXTICR1_EXTI1_PD +.. doxygendefine:: AFIO_EXTICR1_EXTI1_PE +.. doxygendefine:: AFIO_EXTICR1_EXTI1_PF +.. doxygendefine:: AFIO_EXTICR1_EXTI1_PG +.. doxygendefine:: AFIO_EXTICR1_EXTI0 +.. doxygendefine:: AFIO_EXTICR1_EXTI0_PA +.. doxygendefine:: AFIO_EXTICR1_EXTI0_PB +.. doxygendefine:: AFIO_EXTICR1_EXTI0_PC +.. doxygendefine:: AFIO_EXTICR1_EXTI0_PD +.. doxygendefine:: AFIO_EXTICR1_EXTI0_PE +.. doxygendefine:: AFIO_EXTICR1_EXTI0_PF +.. doxygendefine:: AFIO_EXTICR1_EXTI0_PG + +External Interrupt Configuration Register 2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: AFIO_EXTICR2_EXTI7 +.. doxygendefine:: AFIO_EXTICR2_EXTI7_PA +.. doxygendefine:: AFIO_EXTICR2_EXTI7_PB +.. doxygendefine:: AFIO_EXTICR2_EXTI7_PC +.. doxygendefine:: AFIO_EXTICR2_EXTI7_PD +.. doxygendefine:: AFIO_EXTICR2_EXTI7_PE +.. doxygendefine:: AFIO_EXTICR2_EXTI7_PF +.. doxygendefine:: AFIO_EXTICR2_EXTI7_PG +.. doxygendefine:: AFIO_EXTICR2_EXTI6 +.. doxygendefine:: AFIO_EXTICR2_EXTI6_PA +.. doxygendefine:: AFIO_EXTICR2_EXTI6_PB +.. doxygendefine:: AFIO_EXTICR2_EXTI6_PC +.. doxygendefine:: AFIO_EXTICR2_EXTI6_PD +.. doxygendefine:: AFIO_EXTICR2_EXTI6_PE +.. doxygendefine:: AFIO_EXTICR2_EXTI6_PF +.. doxygendefine:: AFIO_EXTICR2_EXTI6_PG +.. doxygendefine:: AFIO_EXTICR2_EXTI5 +.. doxygendefine:: AFIO_EXTICR2_EXTI5_PA +.. doxygendefine:: AFIO_EXTICR2_EXTI5_PB +.. doxygendefine:: AFIO_EXTICR2_EXTI5_PC +.. doxygendefine:: AFIO_EXTICR2_EXTI5_PD +.. doxygendefine:: AFIO_EXTICR2_EXTI5_PE +.. doxygendefine:: AFIO_EXTICR2_EXTI5_PF +.. doxygendefine:: AFIO_EXTICR2_EXTI5_PG +.. doxygendefine:: AFIO_EXTICR2_EXTI4 +.. doxygendefine:: AFIO_EXTICR2_EXTI4_PA +.. doxygendefine:: AFIO_EXTICR2_EXTI4_PB +.. doxygendefine:: AFIO_EXTICR2_EXTI4_PC +.. doxygendefine:: AFIO_EXTICR2_EXTI4_PD +.. doxygendefine:: AFIO_EXTICR2_EXTI4_PE +.. doxygendefine:: AFIO_EXTICR2_EXTI4_PF +.. doxygendefine:: AFIO_EXTICR2_EXTI4_PG + +AF Remap and Debug I/O Configuration Register 2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: AFIO_MAPR2_FSMC_NADV +.. doxygendefine:: AFIO_MAPR2_TIM14_REMAP +.. doxygendefine:: AFIO_MAPR2_TIM13_REMAP +.. doxygendefine:: AFIO_MAPR2_TIM11_REMAP +.. doxygendefine:: AFIO_MAPR2_TIM10_REMAP +.. doxygendefine:: AFIO_MAPR2_TIM9_REMAP diff --git a/source/libmaple/api/i2c.rst b/source/libmaple/api/i2c.rst index 14dd304..ff380cc 100644 --- a/source/libmaple/api/i2c.rst +++ b/source/libmaple/api/i2c.rst @@ -4,9 +4,121 @@ ``i2c.h`` ========= -[Stub] support. +Inter-Integrated Circuit (|i2c|) peripheral support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: i2c.h +Important Note +-------------- + +There are some important known problems with the built-in I2C +peripherals. For more information, see STM32F10xx8 and STM32F10xxB +Errata sheet (ST Doc ID 14574 Rev 8), Section 2.11.1, 2.11.2. An +important consequence of these problems is that the |i2c| interrupt +must not be preempted. Consequently, (by default) Wirish uses an +|i2c| interrupt priority which is the highest in the system (priority +level 0). Other interrupt priorities are set lower. + +Types +----- + +.. doxygenstruct:: i2c_reg_map +.. doxygenenum:: i2c_state +.. doxygenstruct:: i2c_msg +.. doxygenstruct:: i2c_dev + +Devices +------- + +.. doxygenvariable:: I2C1 +.. doxygenvariable:: I2C2 + +Functions +--------- + +.. doxygenfunction:: i2c_init +.. doxygenfunction:: i2c_master_enable +.. doxygenfunction:: i2c_master_xfer +.. doxygenfunction:: i2c_bus_reset +.. doxygenfunction:: i2c_disable +.. doxygenfunction:: i2c_peripheral_enable +.. doxygenfunction:: i2c_peripheral_disable +.. doxygenfunction:: i2c_write +.. doxygenfunction:: i2c_set_input_clk +.. doxygenfunction:: i2c_set_clk_control +.. doxygenfunction:: i2c_set_trise +.. doxygenfunction:: i2c_start_condition +.. doxygenfunction:: i2c_stop_condition +.. doxygenfunction:: i2c_enable_irq +.. doxygenfunction:: i2c_disable_irq +.. doxygenfunction:: i2c_enable_ack +.. doxygenfunction:: i2c_disable_ack + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: I2C1_BASE +.. doxygendefine:: I2C2_BASE + +Register Bit Definitions +------------------------ + +Control register 1 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: I2C_CR1_SWRST +.. doxygendefine:: I2C_CR1_ALERT +.. doxygendefine:: I2C_CR1_PEC +.. doxygendefine:: I2C_CR1_POS +.. doxygendefine:: I2C_CR1_ACK +.. doxygendefine:: I2C_CR1_START +.. doxygendefine:: I2C_CR1_STOP +.. doxygendefine:: I2C_CR1_PE + +Control register 2 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: I2C_CR2_LAST +.. doxygendefine:: I2C_CR2_DMAEN +.. doxygendefine:: I2C_CR2_ITBUFEN +.. doxygendefine:: I2C_CR2_ITEVTEN +.. doxygendefine:: I2C_CR2_ITERREN +.. doxygendefine:: I2C_CR2_FREQ + +Clock control register +~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: I2C_CCR_FS +.. doxygendefine:: I2C_CCR_DUTY +.. doxygendefine:: I2C_CCR_CCR + +Status register 1 +~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: I2C_SR1_SB +.. doxygendefine:: I2C_SR1_ADDR +.. doxygendefine:: I2C_SR1_BTF +.. doxygendefine:: I2C_SR1_ADD10 +.. doxygendefine:: I2C_SR1_STOPF +.. doxygendefine:: I2C_SR1_RXNE +.. doxygendefine:: I2C_SR1_TXE +.. doxygendefine:: I2C_SR1_BERR +.. doxygendefine:: I2C_SR1_ARLO +.. doxygendefine:: I2C_SR1_AF +.. doxygendefine:: I2C_SR1_OVR +.. doxygendefine:: I2C_SR1_PECERR +.. doxygendefine:: I2C_SR1_TIMEOUT +.. doxygendefine:: I2C_SR1_SMBALERT + +Status register 2 +~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: I2C_SR2_MSL +.. doxygendefine:: I2C_SR2_BUSY +.. doxygendefine:: I2C_SR2_TRA +.. doxygendefine:: I2C_SR2_GENCALL +.. doxygendefine:: I2C_SR2_SMBDEFAULT +.. doxygendefine:: I2C_SR2_SMBHOST +.. doxygendefine:: I2C_SR2_DUALF +.. doxygendefine:: I2C_SR2_PEC diff --git a/source/libmaple/api/iwdg.rst b/source/libmaple/api/iwdg.rst index 3911ece..06691f8 100644 --- a/source/libmaple/api/iwdg.rst +++ b/source/libmaple/api/iwdg.rst @@ -4,9 +4,70 @@ ``iwdg.h`` ========== -[Stub] support. +Independent Watchdog (IWDG) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: iwdg.h +Usage Note +---------- + +To use the independent watchdog, first call :c:func:`iwdg_init()` with +the appropriate prescaler and IWDG counter reload values for your +application. Afterwards, you must periodically call +:c:func:`iwdg_feed()` before the IWDG counter reaches 0 to reset the +counter to its reload value. If you do not, the chip will reset. + +Once started, the independent watchdog cannot be turned off. + +Types +----- + +.. doxygenstruct:: iwdg_reg_map +.. doxygenenum:: iwdg_prescaler + +Devices +------- + +None at this time. + +Functions +--------- + +.. doxygenfunction:: iwdg_init +.. doxygenfunction:: iwdg_feed + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: IWDG_BASE + +Register Bit Definitions +------------------------ + +Key register +~~~~~~~~~~~~ + +.. doxygendefine:: IWDG_KR_UNLOCK +.. doxygendefine:: IWDG_KR_FEED +.. doxygendefine:: IWDG_KR_START + +Prescaler register +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: IWDG_PR_DIV_4 +.. doxygendefine:: IWDG_PR_DIV_8 +.. doxygendefine:: IWDG_PR_DIV_16 +.. doxygendefine:: IWDG_PR_DIV_32 +.. doxygendefine:: IWDG_PR_DIV_64 +.. doxygendefine:: IWDG_PR_DIV_128 +.. doxygendefine:: IWDG_PR_DIV_256 + +Status register +~~~~~~~~~~~~~~~ + +.. doxygendefine:: IWDG_SR_RVU_BIT +.. doxygendefine:: IWDG_SR_PVU_BIT + +.. doxygendefine:: IWDG_SR_RVU +.. doxygendefine:: IWDG_SR_PVU diff --git a/source/libmaple/api/libmaple.rst b/source/libmaple/api/libmaple.rst index d4f28f0..c230cef 100644 --- a/source/libmaple/api/libmaple.rst +++ b/source/libmaple/api/libmaple.rst @@ -4,9 +4,8 @@ ``libmaple.h`` ============== -[Stub] support. +Base include file for libmaple. -Library Documentation ---------------------- - -.. doxygenfile:: libmaple.h +This file includes :ref:`libmaple-libmaple_types`, +:ref:`libmaple-stm32`, and :ref:`libmaple-util`. You shouldn't rely +on it doing anything else, however. diff --git a/source/libmaple/api/libmaple_types.rst b/source/libmaple/api/libmaple_types.rst index bbea2c1..7fed5dc 100644 --- a/source/libmaple/api/libmaple_types.rst +++ b/source/libmaple/api/libmaple_types.rst @@ -4,9 +4,40 @@ ``libmaple_types.h`` ==================== -[Stub] support. +Defines the base types and type-related macros used throughout the +rest of libmaple. -Library Documentation ---------------------- +Integral Types +-------------- -.. doxygenfile:: libmaple_types.h +.. doxygentypedef:: uint8 +.. doxygentypedef:: uint16 +.. doxygentypedef:: uint32 +.. doxygentypedef:: uint64 +.. doxygentypedef:: int8 +.. doxygentypedef:: int16 +.. doxygentypedef:: int32 +.. doxygentypedef:: int64 + +Attributes and Type Qualifiers +------------------------------ + +.. c:macro:: __io + + This is a macro for ``volatile`` which is used to denote that the + variable whose type is being qualified is IO-mapped. Its most + common use is in the individual members of each :ref:`register map + ` struct. + +.. c:macro:: __attr_flash + + This is a macro for a GCC ``__attribute__`` which (when using the + linker scripts provided with libmaple) will cause the variable + being marked to be stored in Flash, rather than SRAM. The + variable's value may be read like that of any other variable, but + it may not be written. + +Other typedefs +-------------- + +.. doxygentypedef:: voidFuncPtr diff --git a/source/libmaple/api/nvic.rst b/source/libmaple/api/nvic.rst index b94dc31..11342d2 100644 --- a/source/libmaple/api/nvic.rst +++ b/source/libmaple/api/nvic.rst @@ -4,9 +4,40 @@ ``nvic.h`` ========== -[Stub] support. +Nested Vector Interrupt Controller (NVIC) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: nvic.h +Types +----- + +.. doxygenstruct:: nvic_reg_map +.. doxygenenum:: nvic_irq_num + +Devices +------- + +None at this time. + +Functions +--------- + +.. doxygenfunction:: nvic_init +.. doxygenfunction:: nvic_set_vector_table +.. doxygenfunction:: nvic_irq_set_priority +.. doxygenfunction:: nvic_globalirq_enable +.. doxygenfunction:: nvic_globalirq_disable +.. doxygenfunction:: nvic_irq_enable +.. doxygenfunction:: nvic_irq_disable +.. doxygenfunction:: nvic_irq_disable_all + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: NVIC_BASE + +Register Bit Definitions +------------------------ + +None at this time. diff --git a/source/libmaple/api/pwr.rst b/source/libmaple/api/pwr.rst index 82e4864..6a2cf22 100644 --- a/source/libmaple/api/pwr.rst +++ b/source/libmaple/api/pwr.rst @@ -4,9 +4,48 @@ ``pwr.h`` ========= -[Stub] support. +Power control (PWR) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: pwr.h +Types +----- + +.. doxygenstruct:: pwr_reg_map + +Devices +------- + +None. + +Functions +--------- + +.. doxygenfunction:: pwr_init + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: PWR_BASE + +Register Bit Definitions +------------------------ + +Control register +~~~~~~~~~~~~~~~~ + +.. doxygendefine:: PWR_CR_DBP +.. doxygendefine:: PWR_CR_PVDE +.. doxygendefine:: PWR_CR_CSBF +.. doxygendefine:: PWR_CR_CWUF +.. doxygendefine:: PWR_CR_PDDS +.. doxygendefine:: PWR_CR_LPDS + +Control and status register +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: PWR_CSR_EWUP +.. doxygendefine:: PWR_CSR_PVDO +.. doxygendefine:: PWR_CSR_SBF +.. doxygendefine:: PWR_CSR_WUF diff --git a/source/libmaple/api/rcc.rst b/source/libmaple/api/rcc.rst index 81dc604..4b96c00 100644 --- a/source/libmaple/api/rcc.rst +++ b/source/libmaple/api/rcc.rst @@ -4,9 +4,374 @@ ``rcc.h`` ========= -[Stub] support. +Reset and Clock Control (RCC) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: rcc.h +Types +----- + +.. doxygenstruct:: rcc_reg_map +.. doxygenenum:: rcc_sysclk_src +.. doxygenenum:: rcc_pllsrc +.. doxygenenum:: rcc_pll_multiplier +.. doxygenenum:: rcc_clk_id +.. doxygenenum:: rcc_clk_domain +.. doxygenenum:: rcc_prescaler +.. doxygenenum:: rcc_adc_divider +.. doxygenenum:: rcc_apb1_divider +.. doxygenenum:: rcc_apb2_divider +.. doxygenenum:: rcc_ahb_divider + +Devices +------- + +None. + +Functions +--------- + +.. doxygenfunction:: rcc_clk_init +.. doxygenfunction:: rcc_clk_enable +.. doxygenfunction:: rcc_reset_dev +.. doxygenfunction:: rcc_dev_clk +.. doxygenfunction:: rcc_set_prescaler + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: RCC_BASE + +Register Bit Definitions +------------------------ + +Clock control register +~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_CR_PLLRDY_BIT +.. doxygendefine:: RCC_CR_PLLON_BIT +.. doxygendefine:: RCC_CR_CSSON_BIT +.. doxygendefine:: RCC_CR_HSEBYP_BIT +.. doxygendefine:: RCC_CR_HSERDY_BIT +.. doxygendefine:: RCC_CR_HSEON_BIT +.. doxygendefine:: RCC_CR_HSIRDY_BIT +.. doxygendefine:: RCC_CR_HSION_BIT + +.. doxygendefine:: RCC_CR_PLLRDY +.. doxygendefine:: RCC_CR_PLLON +.. doxygendefine:: RCC_CR_CSSON +.. doxygendefine:: RCC_CR_HSEBYP +.. doxygendefine:: RCC_CR_HSERDY +.. doxygendefine:: RCC_CR_HSEON +.. doxygendefine:: RCC_CR_HSICAL +.. doxygendefine:: RCC_CR_HSITRIM +.. doxygendefine:: RCC_CR_HSIRDY +.. doxygendefine:: RCC_CR_HSION + +Clock configuration register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_CFGR_USBPRE_BIT +.. doxygendefine:: RCC_CFGR_PLLXTPRE_BIT +.. doxygendefine:: RCC_CFGR_PLLSRC_BIT + +.. doxygendefine:: RCC_CFGR_MCO +.. doxygendefine:: RCC_CFGR_USBPRE +.. doxygendefine:: RCC_CFGR_PLLMUL +.. doxygendefine:: RCC_CFGR_PLLXTPRE +.. doxygendefine:: RCC_CFGR_PLLSRC +.. doxygendefine:: RCC_CFGR_ADCPRE +.. doxygendefine:: RCC_CFGR_PPRE2 +.. doxygendefine:: RCC_CFGR_PPRE1 +.. doxygendefine:: RCC_CFGR_HPRE +.. doxygendefine:: RCC_CFGR_SWS +.. doxygendefine:: RCC_CFGR_SWS_PLL +.. doxygendefine:: RCC_CFGR_SWS_HSE +.. doxygendefine:: RCC_CFGR_SW +.. doxygendefine:: RCC_CFGR_SW_PLL +.. doxygendefine:: RCC_CFGR_SW_HSE + +Clock interrupt register +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_CIR_CSSC_BIT +.. doxygendefine:: RCC_CIR_PLLRDYC_BIT +.. doxygendefine:: RCC_CIR_HSERDYC_BIT +.. doxygendefine:: RCC_CIR_HSIRDYC_BIT +.. doxygendefine:: RCC_CIR_LSERDYC_BIT +.. doxygendefine:: RCC_CIR_LSIRDYC_BIT +.. doxygendefine:: RCC_CIR_PLLRDYIE_BIT +.. doxygendefine:: RCC_CIR_HSERDYIE_BIT +.. doxygendefine:: RCC_CIR_HSIRDYIE_BIT +.. doxygendefine:: RCC_CIR_LSERDYIE_BIT +.. doxygendefine:: RCC_CIR_LSIRDYIE_BIT +.. doxygendefine:: RCC_CIR_CSSF_BIT +.. doxygendefine:: RCC_CIR_PLLRDYF_BIT +.. doxygendefine:: RCC_CIR_HSERDYF_BIT +.. doxygendefine:: RCC_CIR_HSIRDYF_BIT +.. doxygendefine:: RCC_CIR_LSERDYF_BIT +.. doxygendefine:: RCC_CIR_LSIRDYF_BIT + +.. doxygendefine:: RCC_CIR_CSSC +.. doxygendefine:: RCC_CIR_PLLRDYC +.. doxygendefine:: RCC_CIR_HSERDYC +.. doxygendefine:: RCC_CIR_HSIRDYC +.. doxygendefine:: RCC_CIR_LSERDYC +.. doxygendefine:: RCC_CIR_LSIRDYC +.. doxygendefine:: RCC_CIR_PLLRDYIE +.. doxygendefine:: RCC_CIR_HSERDYIE +.. doxygendefine:: RCC_CIR_HSIRDYIE +.. doxygendefine:: RCC_CIR_LSERDYIE +.. doxygendefine:: RCC_CIR_LSIRDYIE +.. doxygendefine:: RCC_CIR_CSSF +.. doxygendefine:: RCC_CIR_PLLRDYF +.. doxygendefine:: RCC_CIR_HSERDYF +.. doxygendefine:: RCC_CIR_HSIRDYF +.. doxygendefine:: RCC_CIR_LSERDYF +.. doxygendefine:: RCC_CIR_LSIRDYF + +APB2 peripheral reset register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_APB2RSTR_TIM11RST_BIT +.. doxygendefine:: RCC_APB2RSTR_TIM10RST_BIT +.. doxygendefine:: RCC_APB2RSTR_TIM9RST_BIT +.. doxygendefine:: RCC_APB2RSTR_ADC3RST_BIT +.. doxygendefine:: RCC_APB2RSTR_USART1RST_BIT +.. doxygendefine:: RCC_APB2RSTR_TIM8RST_BIT +.. doxygendefine:: RCC_APB2RSTR_SPI1RST_BIT +.. doxygendefine:: RCC_APB2RSTR_TIM1RST_BIT +.. doxygendefine:: RCC_APB2RSTR_ADC2RST_BIT +.. doxygendefine:: RCC_APB2RSTR_ADC1RST_BIT +.. doxygendefine:: RCC_APB2RSTR_IOPGRST_BIT +.. doxygendefine:: RCC_APB2RSTR_IOPFRST_BIT +.. doxygendefine:: RCC_APB2RSTR_IOPERST_BIT +.. doxygendefine:: RCC_APB2RSTR_IOPDRST_BIT +.. doxygendefine:: RCC_APB2RSTR_IOPCRST_BIT +.. doxygendefine:: RCC_APB2RSTR_IOPBRST_BIT +.. doxygendefine:: RCC_APB2RSTR_IOPARST_BIT +.. doxygendefine:: RCC_APB2RSTR_AFIORST_BIT + +.. doxygendefine:: RCC_APB2RSTR_TIM11RST +.. doxygendefine:: RCC_APB2RSTR_TIM10RST +.. doxygendefine:: RCC_APB2RSTR_TIM9RST +.. doxygendefine:: RCC_APB2RSTR_ADC3RST +.. doxygendefine:: RCC_APB2RSTR_USART1RST +.. doxygendefine:: RCC_APB2RSTR_TIM8RST +.. doxygendefine:: RCC_APB2RSTR_SPI1RST +.. doxygendefine:: RCC_APB2RSTR_TIM1RST +.. doxygendefine:: RCC_APB2RSTR_ADC2RST +.. doxygendefine:: RCC_APB2RSTR_ADC1RST +.. doxygendefine:: RCC_APB2RSTR_IOPGRST +.. doxygendefine:: RCC_APB2RSTR_IOPFRST +.. doxygendefine:: RCC_APB2RSTR_IOPERST +.. doxygendefine:: RCC_APB2RSTR_IOPDRST +.. doxygendefine:: RCC_APB2RSTR_IOPCRST +.. doxygendefine:: RCC_APB2RSTR_IOPBRST +.. doxygendefine:: RCC_APB2RSTR_IOPARST +.. doxygendefine:: RCC_APB2RSTR_AFIORST + +APB1 peripheral reset register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_APB1RSTR_DACRST_BIT +.. doxygendefine:: RCC_APB1RSTR_PWRRST_BIT +.. doxygendefine:: RCC_APB1RSTR_BKPRST_BIT +.. doxygendefine:: RCC_APB1RSTR_CANRST_BIT +.. doxygendefine:: RCC_APB1RSTR_USBRST_BIT +.. doxygendefine:: RCC_APB1RSTR_I2C2RST_BIT +.. doxygendefine:: RCC_APB1RSTR_I2C1RST_BIT +.. doxygendefine:: RCC_APB1RSTR_UART5RST_BIT +.. doxygendefine:: RCC_APB1RSTR_UART4RST_BIT +.. doxygendefine:: RCC_APB1RSTR_USART3RST_BIT +.. doxygendefine:: RCC_APB1RSTR_USART2RST_BIT +.. doxygendefine:: RCC_APB1RSTR_SPI3RST_BIT +.. doxygendefine:: RCC_APB1RSTR_SPI2RST_BIT +.. doxygendefine:: RCC_APB1RSTR_WWDRST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM14RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM13RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM12RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM7RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM6RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM5RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM4RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM3RST_BIT +.. doxygendefine:: RCC_APB1RSTR_TIM2RST_BIT + +.. doxygendefine:: RCC_APB1RSTR_DACRST +.. doxygendefine:: RCC_APB1RSTR_PWRRST +.. doxygendefine:: RCC_APB1RSTR_BKPRST +.. doxygendefine:: RCC_APB1RSTR_CANRST +.. doxygendefine:: RCC_APB1RSTR_USBRST +.. doxygendefine:: RCC_APB1RSTR_I2C2RST +.. doxygendefine:: RCC_APB1RSTR_I2C1RST +.. doxygendefine:: RCC_APB1RSTR_UART5RST +.. doxygendefine:: RCC_APB1RSTR_UART4RST +.. doxygendefine:: RCC_APB1RSTR_USART3RST +.. doxygendefine:: RCC_APB1RSTR_USART2RST +.. doxygendefine:: RCC_APB1RSTR_SPI3RST +.. doxygendefine:: RCC_APB1RSTR_SPI2RST +.. doxygendefine:: RCC_APB1RSTR_WWDRST +.. doxygendefine:: RCC_APB1RSTR_TIM14RST +.. doxygendefine:: RCC_APB1RSTR_TIM13RST +.. doxygendefine:: RCC_APB1RSTR_TIM12RST +.. doxygendefine:: RCC_APB1RSTR_TIM7RST +.. doxygendefine:: RCC_APB1RSTR_TIM6RST +.. doxygendefine:: RCC_APB1RSTR_TIM5RST +.. doxygendefine:: RCC_APB1RSTR_TIM4RST +.. doxygendefine:: RCC_APB1RSTR_TIM3RST +.. doxygendefine:: RCC_APB1RSTR_TIM2RST + +AHB peripheral clock enable register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_AHBENR_SDIOEN_BIT +.. doxygendefine:: RCC_AHBENR_FSMCEN_BIT +.. doxygendefine:: RCC_AHBENR_CRCEN_BIT +.. doxygendefine:: RCC_AHBENR_FLITFEN_BIT +.. doxygendefine:: RCC_AHBENR_SRAMEN_BIT +.. doxygendefine:: RCC_AHBENR_DMA2EN_BIT +.. doxygendefine:: RCC_AHBENR_DMA1EN_BIT + +.. doxygendefine:: RCC_AHBENR_SDIOEN +.. doxygendefine:: RCC_AHBENR_FSMCEN +.. doxygendefine:: RCC_AHBENR_CRCEN +.. doxygendefine:: RCC_AHBENR_FLITFEN +.. doxygendefine:: RCC_AHBENR_SRAMEN +.. doxygendefine:: RCC_AHBENR_DMA2EN +.. doxygendefine:: RCC_AHBENR_DMA1EN + +APB2 peripheral clock enable register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_APB2ENR_TIM11EN_BIT +.. doxygendefine:: RCC_APB2ENR_TIM10EN_BIT +.. doxygendefine:: RCC_APB2ENR_TIM9EN_BIT +.. doxygendefine:: RCC_APB2ENR_ADC3EN_BIT +.. doxygendefine:: RCC_APB2ENR_USART1EN_BIT +.. doxygendefine:: RCC_APB2ENR_TIM8EN_BIT +.. doxygendefine:: RCC_APB2ENR_SPI1EN_BIT +.. doxygendefine:: RCC_APB2ENR_TIM1EN_BIT +.. doxygendefine:: RCC_APB2ENR_ADC2EN_BIT +.. doxygendefine:: RCC_APB2ENR_ADC1EN_BIT +.. doxygendefine:: RCC_APB2ENR_IOPGEN_BIT +.. doxygendefine:: RCC_APB2ENR_IOPFEN_BIT +.. doxygendefine:: RCC_APB2ENR_IOPEEN_BIT +.. doxygendefine:: RCC_APB2ENR_IOPDEN_BIT +.. doxygendefine:: RCC_APB2ENR_IOPCEN_BIT +.. doxygendefine:: RCC_APB2ENR_IOPBEN_BIT +.. doxygendefine:: RCC_APB2ENR_IOPAEN_BIT +.. doxygendefine:: RCC_APB2ENR_AFIOEN_BIT + +.. doxygendefine:: RCC_APB2ENR_TIM11EN +.. doxygendefine:: RCC_APB2ENR_TIM10EN +.. doxygendefine:: RCC_APB2ENR_TIM9EN +.. doxygendefine:: RCC_APB2ENR_ADC3EN +.. doxygendefine:: RCC_APB2ENR_USART1EN +.. doxygendefine:: RCC_APB2ENR_TIM8EN +.. doxygendefine:: RCC_APB2ENR_SPI1EN +.. doxygendefine:: RCC_APB2ENR_TIM1EN +.. doxygendefine:: RCC_APB2ENR_ADC2EN +.. doxygendefine:: RCC_APB2ENR_ADC1EN +.. doxygendefine:: RCC_APB2ENR_IOPGEN +.. doxygendefine:: RCC_APB2ENR_IOPFEN +.. doxygendefine:: RCC_APB2ENR_IOPEEN +.. doxygendefine:: RCC_APB2ENR_IOPDEN +.. doxygendefine:: RCC_APB2ENR_IOPCEN +.. doxygendefine:: RCC_APB2ENR_IOPBEN +.. doxygendefine:: RCC_APB2ENR_IOPAEN +.. doxygendefine:: RCC_APB2ENR_AFIOEN + +APB1 peripheral clock enable register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_APB1ENR_DACEN_BIT +.. doxygendefine:: RCC_APB1ENR_PWREN_BIT +.. doxygendefine:: RCC_APB1ENR_BKPEN_BIT +.. doxygendefine:: RCC_APB1ENR_CANEN_BIT +.. doxygendefine:: RCC_APB1ENR_USBEN_BIT +.. doxygendefine:: RCC_APB1ENR_I2C2EN_BIT +.. doxygendefine:: RCC_APB1ENR_I2C1EN_BIT +.. doxygendefine:: RCC_APB1ENR_UART5EN_BIT +.. doxygendefine:: RCC_APB1ENR_UART4EN_BIT +.. doxygendefine:: RCC_APB1ENR_USART3EN_BIT +.. doxygendefine:: RCC_APB1ENR_USART2EN_BIT +.. doxygendefine:: RCC_APB1ENR_SPI3EN_BIT +.. doxygendefine:: RCC_APB1ENR_SPI2EN_BIT +.. doxygendefine:: RCC_APB1ENR_WWDEN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM14EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM13EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM12EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM7EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM6EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM5EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM4EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM3EN_BIT +.. doxygendefine:: RCC_APB1ENR_TIM2EN_BIT + +.. doxygendefine:: RCC_APB1ENR_DACEN +.. doxygendefine:: RCC_APB1ENR_PWREN +.. doxygendefine:: RCC_APB1ENR_BKPEN +.. doxygendefine:: RCC_APB1ENR_CANEN +.. doxygendefine:: RCC_APB1ENR_USBEN +.. doxygendefine:: RCC_APB1ENR_I2C2EN +.. doxygendefine:: RCC_APB1ENR_I2C1EN +.. doxygendefine:: RCC_APB1ENR_UART5EN +.. doxygendefine:: RCC_APB1ENR_UART4EN +.. doxygendefine:: RCC_APB1ENR_USART3EN +.. doxygendefine:: RCC_APB1ENR_USART2EN +.. doxygendefine:: RCC_APB1ENR_SPI3EN +.. doxygendefine:: RCC_APB1ENR_SPI2EN +.. doxygendefine:: RCC_APB1ENR_WWDEN +.. doxygendefine:: RCC_APB1ENR_TIM14EN +.. doxygendefine:: RCC_APB1ENR_TIM13EN +.. doxygendefine:: RCC_APB1ENR_TIM12EN +.. doxygendefine:: RCC_APB1ENR_TIM7EN +.. doxygendefine:: RCC_APB1ENR_TIM6EN +.. doxygendefine:: RCC_APB1ENR_TIM5EN +.. doxygendefine:: RCC_APB1ENR_TIM4EN +.. doxygendefine:: RCC_APB1ENR_TIM3EN +.. doxygendefine:: RCC_APB1ENR_TIM2EN + +Backup domain control register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_BDCR_BDRST_BIT +.. doxygendefine:: RCC_BDCR_RTCEN_BIT +.. doxygendefine:: RCC_BDCR_LSEBYP_BIT +.. doxygendefine:: RCC_BDCR_LSERDY_BIT +.. doxygendefine:: RCC_BDCR_LSEON_BIT + +.. doxygendefine:: RCC_BDCR_BDRST +.. doxygendefine:: RCC_BDCR_RTCEN +.. doxygendefine:: RCC_BDCR_RTCSEL +.. doxygendefine:: RCC_BDCR_RTCSEL_NONE +.. doxygendefine:: RCC_BDCR_RTCSEL_LSE +.. doxygendefine:: RCC_BDCR_RTCSEL_HSE +.. doxygendefine:: RCC_BDCR_LSEBYP +.. doxygendefine:: RCC_BDCR_LSERDY +.. doxygendefine:: RCC_BDCR_LSEON + +Control/status register +~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: RCC_CSR_LPWRRSTF_BIT +.. doxygendefine:: RCC_CSR_WWDGRSTF_BIT +.. doxygendefine:: RCC_CSR_IWDGRSTF_BIT +.. doxygendefine:: RCC_CSR_SFTRSTF_BIT +.. doxygendefine:: RCC_CSR_PORRSTF_BIT +.. doxygendefine:: RCC_CSR_PINRSTF_BIT +.. doxygendefine:: RCC_CSR_RMVF_BIT +.. doxygendefine:: RCC_CSR_LSIRDY_BIT +.. doxygendefine:: RCC_CSR_LSION_BIT + +.. doxygendefine:: RCC_CSR_LPWRRSTF +.. doxygendefine:: RCC_CSR_WWDGRSTF +.. doxygendefine:: RCC_CSR_IWDGRSTF +.. doxygendefine:: RCC_CSR_SFTRSTF +.. doxygendefine:: RCC_CSR_PORRSTF +.. doxygendefine:: RCC_CSR_PINRSTF +.. doxygendefine:: RCC_CSR_RMVF +.. doxygendefine:: RCC_CSR_LSIRDY +.. doxygendefine:: RCC_CSR_LSION diff --git a/source/libmaple/api/ring_buffer.rst b/source/libmaple/api/ring_buffer.rst index a014fa4..e9b6637 100644 --- a/source/libmaple/api/ring_buffer.rst +++ b/source/libmaple/api/ring_buffer.rst @@ -4,9 +4,24 @@ ``ring_buffer.h`` ================= -[Stub] support. +Simple circular byte buffer. This implementation is not thread-safe. +In particular, none of these functions is guaranteed to be re-entrant. -Library Documentation ---------------------- +Ring Buffer Type +---------------- -.. doxygenfile:: ring_buffer.h +.. doxygenstruct:: ring_buffer + +Ring Buffer Operations +---------------------- + +.. doxygenfunction:: rb_init +.. doxygenfunction:: rb_full_count +.. doxygenfunction:: rb_is_full +.. doxygenfunction:: rb_is_empty +.. doxygenfunction:: rb_insert +.. doxygenfunction:: rb_remove +.. doxygenfunction:: rb_safe_remove +.. doxygenfunction:: rb_safe_insert +.. doxygenfunction:: rb_push_insert +.. doxygenfunction:: rb_reset diff --git a/source/libmaple/api/scb.rst b/source/libmaple/api/scb.rst index 78cc7eb..ff6f61b 100644 --- a/source/libmaple/api/scb.rst +++ b/source/libmaple/api/scb.rst @@ -4,9 +4,27 @@ ``scb.h`` ========= -[Stub] support. +System Control Block (SCB) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: scb.h +Types +----- + +.. doxygenstruct:: scb_reg_map + +Devices +------- + +None. + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: SCB_BASE + +Register Bit Definitions +------------------------ + +None at this time. diff --git a/source/libmaple/api/spi.rst b/source/libmaple/api/spi.rst index b0c7e86..e72696b 100644 --- a/source/libmaple/api/spi.rst +++ b/source/libmaple/api/spi.rst @@ -4,9 +4,184 @@ ``spi.h`` ========= -[Stub] support. +Serial Peripheral Interface (SPI) support. Currently, there is no I2S +support beyond register bit definitions. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: spi.h +Types +----- + +.. doxygenstruct:: spi_reg_map +.. doxygenstruct:: spi_dev +.. doxygenenum:: spi_mode +.. doxygenenum:: spi_baud_rate +.. doxygenenum:: spi_cfg_flag +.. doxygenenum:: spi_interrupt + +Devices +------- + +.. doxygenvariable:: SPI1 +.. doxygenvariable:: SPI2 +.. doxygenvariable:: SPI3 + +Functions +--------- + +.. doxygenfunction:: spi_init +.. doxygenfunction:: spi_gpio_cfg +.. doxygenfunction:: spi_master_enable +.. doxygenfunction:: spi_slave_enable +.. doxygenfunction:: spi_tx +.. doxygenfunction:: spi_foreach +.. doxygenfunction:: spi_peripheral_enable +.. doxygenfunction:: spi_peripheral_disable +.. doxygenfunction:: spi_peripheral_disable_all +.. doxygenfunction:: spi_tx_dma_enable +.. doxygenfunction:: spi_tx_dma_disable +.. doxygenfunction:: spi_rx_dma_enable +.. doxygenfunction:: spi_rx_dma_disable +.. doxygenfunction:: spi_is_enabled +.. doxygenfunction:: spi_irq_enable +.. doxygenfunction:: spi_irq_disable +.. doxygenfunction:: spi_dff +.. doxygenfunction:: spi_is_rx_nonempty +.. doxygenfunction:: spi_rx_reg +.. doxygenfunction:: spi_is_tx_empty +.. doxygenfunction:: spi_tx_reg +.. doxygenfunction:: spi_is_busy + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: SPI1_BASE +.. doxygendefine:: SPI2_BASE +.. doxygendefine:: SPI3_BASE + +Register Bit Definitions +------------------------ + +Control register 1 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SPI_CR1_BIDIMODE_BIT +.. doxygendefine:: SPI_CR1_BIDIOE_BIT +.. doxygendefine:: SPI_CR1_CRCEN_BIT +.. doxygendefine:: SPI_CR1_CRCNEXT_BIT +.. doxygendefine:: SPI_CR1_DFF_BIT +.. doxygendefine:: SPI_CR1_RXONLY_BIT +.. doxygendefine:: SPI_CR1_SSM_BIT +.. doxygendefine:: SPI_CR1_SSI_BIT +.. doxygendefine:: SPI_CR1_LSBFIRST_BIT +.. doxygendefine:: SPI_CR1_SPE_BIT +.. doxygendefine:: SPI_CR1_MSTR_BIT +.. doxygendefine:: SPI_CR1_CPOL_BIT +.. doxygendefine:: SPI_CR1_CPHA_BIT + +.. doxygendefine:: SPI_CR1_BIDIMODE +.. doxygendefine:: SPI_CR1_BIDIMODE_2_LINE +.. doxygendefine:: SPI_CR1_BIDIMODE_1_LINE +.. doxygendefine:: SPI_CR1_BIDIOE +.. doxygendefine:: SPI_CR1_CRCEN +.. doxygendefine:: SPI_CR1_CRCNEXT +.. doxygendefine:: SPI_CR1_DFF +.. doxygendefine:: SPI_CR1_DFF_8_BIT +.. doxygendefine:: SPI_CR1_DFF_16_BIT +.. doxygendefine:: SPI_CR1_RXONLY +.. doxygendefine:: SPI_CR1_SSM +.. doxygendefine:: SPI_CR1_SSI +.. doxygendefine:: SPI_CR1_LSBFIRST +.. doxygendefine:: SPI_CR1_SPE +.. doxygendefine:: SPI_CR1_BR +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_2 +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_4 +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_8 +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_16 +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_32 +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_64 +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_128 +.. doxygendefine:: SPI_CR1_BR_PCLK_DIV_256 +.. doxygendefine:: SPI_CR1_MSTR +.. doxygendefine:: SPI_CR1_CPOL +.. doxygendefine:: SPI_CR1_CPOL_LOW +.. doxygendefine:: SPI_CR1_CPOL_HIGH +.. doxygendefine:: SPI_CR1_CPHA + +Control register 2 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SPI_CR2_TXEIE_BIT +.. doxygendefine:: SPI_CR2_RXNEIE_BIT +.. doxygendefine:: SPI_CR2_ERRIE_BIT +.. doxygendefine:: SPI_CR2_SSOE_BIT +.. doxygendefine:: SPI_CR2_TXDMAEN_BIT +.. doxygendefine:: SPI_CR2_RXDMAEN_BIT + +.. doxygendefine:: SPI_CR2_TXEIE +.. doxygendefine:: SPI_CR2_RXNEIE +.. doxygendefine:: SPI_CR2_ERRIE +.. doxygendefine:: SPI_CR2_SSOE +.. doxygendefine:: SPI_CR2_TXDMAEN +.. doxygendefine:: SPI_CR2_RXDMAEN + +Status register +~~~~~~~~~~~~~~~ + +.. doxygendefine:: SPI_SR_BSY_BIT +.. doxygendefine:: SPI_SR_OVR_BIT +.. doxygendefine:: SPI_SR_MODF_BIT +.. doxygendefine:: SPI_SR_CRCERR_BIT +.. doxygendefine:: SPI_SR_UDR_BIT +.. doxygendefine:: SPI_SR_CHSIDE_BIT +.. doxygendefine:: SPI_SR_TXE_BIT +.. doxygendefine:: SPI_SR_RXNE_BIT + +.. doxygendefine:: SPI_SR_BSY +.. doxygendefine:: SPI_SR_OVR +.. doxygendefine:: SPI_SR_MODF +.. doxygendefine:: SPI_SR_CRCERR +.. doxygendefine:: SPI_SR_UDR +.. doxygendefine:: SPI_SR_CHSIDE +.. doxygendefine:: SPI_SR_CHSIDE_LEFT +.. doxygendefine:: SPI_SR_CHSIDE_RIGHT +.. doxygendefine:: SPI_SR_TXE +.. doxygendefine:: SPI_SR_RXNE + +I2S configuration register +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SPI_I2SCFGR_I2SMOD_BIT +.. doxygendefine:: SPI_I2SCFGR_I2SE_BIT +.. doxygendefine:: SPI_I2SCFGR_PCMSYNC_BIT +.. doxygendefine:: SPI_I2SCFGR_CKPOL_BIT +.. doxygendefine:: SPI_I2SCFGR_CHLEN_BIT + +.. doxygendefine:: SPI_I2SCFGR_I2SMOD +.. doxygendefine:: SPI_I2SCFGR_I2SMOD_SPI +.. doxygendefine:: SPI_I2SCFGR_I2SMOD_I2S +.. doxygendefine:: SPI_I2SCFGR_I2SE +.. doxygendefine:: SPI_I2SCFGR_I2SCFG +.. doxygendefine:: SPI_I2SCFGR_I2SCFG_SLAVE_TX +.. doxygendefine:: SPI_I2SCFGR_I2SCFG_SLAVE_RX +.. doxygendefine:: SPI_I2SCFGR_I2SCFG_MASTER_TX +.. doxygendefine:: SPI_I2SCFGR_I2SCFG_MASTER_RX +.. doxygendefine:: SPI_I2SCFGR_PCMSYNC +.. doxygendefine:: SPI_I2SCFGR_PCMSYNC_SHORT +.. doxygendefine:: SPI_I2SCFGR_PCMSYNC_LONG +.. doxygendefine:: SPI_I2SCFGR_I2SSTD +.. doxygendefine:: SPI_I2SCFGR_I2SSTD_PHILLIPS +.. doxygendefine:: SPI_I2SCFGR_I2SSTD_MSB +.. doxygendefine:: SPI_I2SCFGR_I2SSTD_LSB +.. doxygendefine:: SPI_I2SCFGR_I2SSTD_PCM +.. doxygendefine:: SPI_I2SCFGR_CKPOL +.. doxygendefine:: SPI_I2SCFGR_CKPOL_LOW +.. doxygendefine:: SPI_I2SCFGR_CKPOL_HIGH +.. doxygendefine:: SPI_I2SCFGR_DATLEN +.. doxygendefine:: SPI_I2SCFGR_DATLEN_16_BIT +.. doxygendefine:: SPI_I2SCFGR_DATLEN_24_BIT +.. doxygendefine:: SPI_I2SCFGR_DATLEN_32_BIT +.. doxygendefine:: SPI_I2SCFGR_CHLEN +.. doxygendefine:: SPI_I2SCFGR_CHLEN_16_BIT +.. doxygendefine:: SPI_I2SCFGR_CHLEN_32_BIT diff --git a/source/libmaple/api/stm32.rst b/source/libmaple/api/stm32.rst index 2784540..82280bb 100644 --- a/source/libmaple/api/stm32.rst +++ b/source/libmaple/api/stm32.rst @@ -4,9 +4,16 @@ ``stm32.h`` =========== -[Stub] support. +General STM32-specific definitions. This file is currently somewhat +incomplete, but it will form the future basis for MCU-specific (rather +than board-specific, which belongs in :ref:`Wirish +`) configuration. -Library Documentation ---------------------- +Defines +------- -.. doxygenfile:: stm32.h +.. doxygendefine:: PCLK1 +.. doxygendefine:: PCLK2 +.. doxygendefine:: NR_INTERRUPTS +.. doxygendefine:: NR_GPIO_PORTS +.. doxygendefine:: DELAY_US_MULT diff --git a/source/libmaple/api/systick.rst b/source/libmaple/api/systick.rst index fa959f2..8dab417 100644 --- a/source/libmaple/api/systick.rst +++ b/source/libmaple/api/systick.rst @@ -1,7 +1,6 @@ .. highlight:: c -.. FIXME [0.1.0] move these to the right places once Breathe is fast -.. enough to use for libmaple proper +.. FIXME [0.0.10] move these to the right places: .. _libmaple-systick_disable: @@ -12,9 +11,56 @@ ``systick.h`` ============= -[Stub] support. +System timer (SysTick) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: systick.h +Types +----- + +.. doxygenstruct:: systick_reg_map + +Devices +------- + +None. + +Functions +--------- + +.. doxygenfunction:: systick_init +.. doxygenfunction:: systick_enable +.. doxygenfunction:: systick_disable +.. doxygenfunction:: systick_uptime +.. doxygenfunction:: systick_get_count +.. doxygenfunction:: systick_check_underflow + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: SYSTICK_BASE + +Register Bit Definitions +------------------------ + +Control and status register +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SYSTICK_CSR_COUNTFLAG +.. doxygendefine:: SYSTICK_CSR_CLKSOURCE +.. doxygendefine:: SYSTICK_CSR_CLKSOURCE_EXTERNAL +.. doxygendefine:: SYSTICK_CSR_CLKSOURCE_CORE +.. doxygendefine:: SYSTICK_CSR_TICKINT +.. doxygendefine:: SYSTICK_CSR_TICKINT_PEND +.. doxygendefine:: SYSTICK_CSR_TICKINT_NO_PEND +.. doxygendefine:: SYSTICK_CSR_ENABLE +.. doxygendefine:: SYSTICK_CSR_ENABLE_MULTISHOT +.. doxygendefine:: SYSTICK_CSR_ENABLE_DISABLED + +Calibration value register +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SYSTICK_CVR_NOREF +.. doxygendefine:: SYSTICK_CVR_SKEW +.. doxygendefine:: SYSTICK_CVR_TENMS diff --git a/source/libmaple/api/timer.rst b/source/libmaple/api/timer.rst index 3acbf4f..f315cb0 100644 --- a/source/libmaple/api/timer.rst +++ b/source/libmaple/api/timer.rst @@ -4,9 +4,450 @@ ``timer.h`` =========== -[Stub] support. +Timer support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: timer.h +Types +----- + +The timer register map type, unlike that for most other peripherals in +libmaple, is a union rather than a struct. This is due to the fact +that there are advanced, general purpose, and basic timers. Thus, +each kind of timer has a register map type, and a ``union +timer_reg_map`` ties it all together. + +.. doxygenstruct:: timer_adv_reg_map +.. doxygenstruct:: timer_gen_reg_map +.. doxygenstruct:: timer_bas_reg_map +.. doxygenunion:: timer_reg_map +.. doxygenenum:: timer_type +.. doxygenstruct:: timer_dev +.. doxygenenum:: timer_mode +.. doxygenenum:: timer_channel +.. doxygenenum:: timer_interrupt_id +.. doxygenenum:: timer_dma_base_addr +.. doxygenenum:: timer_oc_mode +.. doxygenenum:: timer_oc_mode_flags + +Devices +------- + +.. doxygenvariable:: TIMER1 +.. doxygenvariable:: TIMER2 +.. doxygenvariable:: TIMER3 +.. doxygenvariable:: TIMER4 +.. doxygenvariable:: TIMER5 +.. doxygenvariable:: TIMER6 +.. doxygenvariable:: TIMER7 +.. doxygenvariable:: TIMER8 + +Functions +--------- + +Enabling and Disabling +~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygenfunction:: timer_init +.. doxygenfunction:: timer_init_all +.. doxygenfunction:: timer_disable +.. doxygenfunction:: timer_disable_all + +General Configuration +~~~~~~~~~~~~~~~~~~~~~ + +.. doxygenfunction:: timer_set_mode +.. doxygenfunction:: timer_foreach + +Count and Prescaler +~~~~~~~~~~~~~~~~~~~ + +.. doxygenfunction:: timer_get_count +.. doxygenfunction:: timer_set_count +.. doxygenfunction:: timer_pause +.. doxygenfunction:: timer_resume +.. doxygenfunction:: timer_generate_update +.. doxygenfunction:: timer_get_prescaler +.. doxygenfunction:: timer_set_prescaler +.. doxygenfunction:: timer_get_reload +.. doxygenfunction:: timer_set_reload + +Interrupts +~~~~~~~~~~ + +.. doxygenfunction:: timer_attach_interrupt +.. doxygenfunction:: timer_detach_interrupt +.. doxygenfunction:: timer_enable_irq +.. doxygenfunction:: timer_disable_irq + +Capture/Compare +~~~~~~~~~~~~~~~ + +.. doxygenfunction:: timer_get_compare +.. doxygenfunction:: timer_set_compare +.. doxygenfunction:: timer_cc_enable +.. doxygenfunction:: timer_cc_disable +.. doxygenfunction:: timer_cc_get_pol +.. doxygenfunction:: timer_cc_set_pol +.. doxygenfunction:: timer_oc_set_mode + +DMA +~~~ + +.. doxygenfunction:: timer_dma_enable_trg_req +.. doxygenfunction:: timer_dma_disable_trg_req +.. doxygenfunction:: timer_dma_enable_req +.. doxygenfunction:: timer_dma_get_burst_len +.. doxygenfunction:: timer_dma_set_burst_len +.. doxygenfunction:: timer_dma_get_base_addr +.. doxygenfunction:: timer_dma_set_base_addr + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: TIMER1_BASE +.. doxygendefine:: TIMER2_BASE +.. doxygendefine:: TIMER3_BASE +.. doxygendefine:: TIMER4_BASE +.. doxygendefine:: TIMER5_BASE +.. doxygendefine:: TIMER6_BASE +.. doxygendefine:: TIMER7_BASE +.. doxygendefine:: TIMER8_BASE + +Register Bit Definitions +------------------------ + +Control register 1 (CR1) +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_CR1_ARPE_BIT +.. doxygendefine:: TIMER_CR1_DIR_BIT +.. doxygendefine:: TIMER_CR1_OPM_BIT +.. doxygendefine:: TIMER_CR1_URS_BIT +.. doxygendefine:: TIMER_CR1_UDIS_BIT +.. doxygendefine:: TIMER_CR1_CEN_BIT + +.. doxygendefine:: TIMER_CR1_CKD +.. doxygendefine:: TIMER_CR1_CKD_1TCKINT +.. doxygendefine:: TIMER_CR1_CKD_2TCKINT +.. doxygendefine:: TIMER_CR1_CKD_4TICKINT +.. doxygendefine:: TIMER_CR1_ARPE +.. doxygendefine:: TIMER_CR1_CKD_CMS +.. doxygendefine:: TIMER_CR1_CKD_CMS_EDGE +.. doxygendefine:: TIMER_CR1_CKD_CMS_CENTER1 +.. doxygendefine:: TIMER_CR1_CKD_CMS_CENTER2 +.. doxygendefine:: TIMER_CR1_CKD_CMS_CENTER3 +.. doxygendefine:: TIMER_CR1_DIR +.. doxygendefine:: TIMER_CR1_OPM +.. doxygendefine:: TIMER_CR1_URS +.. doxygendefine:: TIMER_CR1_UDIS +.. doxygendefine:: TIMER_CR1_CEN + +Control register 2 (CR2) +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_CR2_OIS4_BIT +.. doxygendefine:: TIMER_CR2_OIS3N_BIT +.. doxygendefine:: TIMER_CR2_OIS3_BIT +.. doxygendefine:: TIMER_CR2_OIS2N_BIT +.. doxygendefine:: TIMER_CR2_OIS2_BIT +.. doxygendefine:: TIMER_CR2_OIS1N_BIT +.. doxygendefine:: TIMER_CR2_OIS1_BIT +.. doxygendefine:: TIMER_CR2_TI1S_BIT +.. doxygendefine:: TIMER_CR2_CCDS_BIT +.. doxygendefine:: TIMER_CR2_CCUS_BIT +.. doxygendefine:: TIMER_CR2_CCPC_BIT + +.. doxygendefine:: TIMER_CR2_OIS4 +.. doxygendefine:: TIMER_CR2_OIS3N +.. doxygendefine:: TIMER_CR2_OIS3 +.. doxygendefine:: TIMER_CR2_OIS2N +.. doxygendefine:: TIMER_CR2_OIS2 +.. doxygendefine:: TIMER_CR2_OIS1N +.. doxygendefine:: TIMER_CR2_OIS1 +.. doxygendefine:: TIMER_CR2_TI1S +.. doxygendefine:: TIMER_CR2_MMS +.. doxygendefine:: TIMER_CR2_MMS_RESET +.. doxygendefine:: TIMER_CR2_MMS_ENABLE +.. doxygendefine:: TIMER_CR2_MMS_UPDATE +.. doxygendefine:: TIMER_CR2_MMS_COMPARE_PULSE +.. doxygendefine:: TIMER_CR2_MMS_COMPARE_OC1REF +.. doxygendefine:: TIMER_CR2_MMS_COMPARE_OC2REF +.. doxygendefine:: TIMER_CR2_MMS_COMPARE_OC3REF +.. doxygendefine:: TIMER_CR2_MMS_COMPARE_OC4REF +.. doxygendefine:: TIMER_CR2_CCDS +.. doxygendefine:: TIMER_CR2_CCUS +.. doxygendefine:: TIMER_CR2_CCPC + +Slave mode control register (SMCR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_SMCR_ETP_BIT +.. doxygendefine:: TIMER_SMCR_ECE_BIT +.. doxygendefine:: TIMER_SMCR_MSM_BIT + +.. doxygendefine:: TIMER_SMCR_ETP +.. doxygendefine:: TIMER_SMCR_ECE +.. doxygendefine:: TIMER_SMCR_ETPS +.. doxygendefine:: TIMER_SMCR_ETPS_OFF +.. doxygendefine:: TIMER_SMCR_ETPS_DIV2 +.. doxygendefine:: TIMER_SMCR_ETPS_DIV4 +.. doxygendefine:: TIMER_SMCR_ETPS_DIV8 +.. doxygendefine:: TIMER_SMCR_ETF +.. doxygendefine:: TIMER_SMCR_MSM +.. doxygendefine:: TIMER_SMCR_TS +.. doxygendefine:: TIMER_SMCR_TS_ITR0 +.. doxygendefine:: TIMER_SMCR_TS_ITR1 +.. doxygendefine:: TIMER_SMCR_TS_ITR2 +.. doxygendefine:: TIMER_SMCR_TS_ITR3 +.. doxygendefine:: TIMER_SMCR_TS_TI1F_ED +.. doxygendefine:: TIMER_SMCR_TS_TI1FP1 +.. doxygendefine:: TIMER_SMCR_TS_TI2FP2 +.. doxygendefine:: TIMER_SMCR_TS_ETRF +.. doxygendefine:: TIMER_SMCR_SMS +.. doxygendefine:: TIMER_SMCR_SMS_DISABLED +.. doxygendefine:: TIMER_SMCR_SMS_ENCODER1 +.. doxygendefine:: TIMER_SMCR_SMS_ENCODER2 +.. doxygendefine:: TIMER_SMCR_SMS_ENCODER3 +.. doxygendefine:: TIMER_SMCR_SMS_RESET +.. doxygendefine:: TIMER_SMCR_SMS_GATED +.. doxygendefine:: TIMER_SMCR_SMS_TRIGGER +.. doxygendefine:: TIMER_SMCR_SMS_EXTERNAL + +DMA/Interrupt enable register (DIER) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_DIER_TDE_BIT +.. doxygendefine:: TIMER_DIER_CC4DE_BIT +.. doxygendefine:: TIMER_DIER_CC3DE_BIT +.. doxygendefine:: TIMER_DIER_CC2DE_BIT +.. doxygendefine:: TIMER_DIER_CC1DE_BIT +.. doxygendefine:: TIMER_DIER_UDE_BIT +.. doxygendefine:: TIMER_DIER_TIE_BIT +.. doxygendefine:: TIMER_DIER_CC4IE_BIT +.. doxygendefine:: TIMER_DIER_CC3IE_BIT +.. doxygendefine:: TIMER_DIER_CC2IE_BIT +.. doxygendefine:: TIMER_DIER_CC1IE_BIT +.. doxygendefine:: TIMER_DIER_UIE_BIT + +.. doxygendefine:: TIMER_DIER_TDE +.. doxygendefine:: TIMER_DIER_CC4DE +.. doxygendefine:: TIMER_DIER_CC3DE +.. doxygendefine:: TIMER_DIER_CC2DE +.. doxygendefine:: TIMER_DIER_CC1DE +.. doxygendefine:: TIMER_DIER_UDE +.. doxygendefine:: TIMER_DIER_TIE +.. doxygendefine:: TIMER_DIER_CC4IE +.. doxygendefine:: TIMER_DIER_CC3IE +.. doxygendefine:: TIMER_DIER_CC2IE +.. doxygendefine:: TIMER_DIER_CC1IE +.. doxygendefine:: TIMER_DIER_UIE + +Status register (SR) +~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_SR_CC4OF_BIT +.. doxygendefine:: TIMER_SR_CC3OF_BIT +.. doxygendefine:: TIMER_SR_CC2OF_BIT +.. doxygendefine:: TIMER_SR_CC1OF_BIT +.. doxygendefine:: TIMER_SR_BIF_BIT +.. doxygendefine:: TIMER_SR_TIF_BIT +.. doxygendefine:: TIMER_SR_COMIF_BIT +.. doxygendefine:: TIMER_SR_CC4IF_BIT +.. doxygendefine:: TIMER_SR_CC3IF_BIT +.. doxygendefine:: TIMER_SR_CC2IF_BIT +.. doxygendefine:: TIMER_SR_CC1IF_BIT +.. doxygendefine:: TIMER_SR_UIF_BIT + +.. doxygendefine:: TIMER_SR_CC4OF +.. doxygendefine:: TIMER_SR_CC3OF +.. doxygendefine:: TIMER_SR_CC2OF +.. doxygendefine:: TIMER_SR_CC1OF +.. doxygendefine:: TIMER_SR_BIF +.. doxygendefine:: TIMER_SR_TIF +.. doxygendefine:: TIMER_SR_COMIF +.. doxygendefine:: TIMER_SR_CC4IF +.. doxygendefine:: TIMER_SR_CC3IF +.. doxygendefine:: TIMER_SR_CC2IF +.. doxygendefine:: TIMER_SR_CC1IF +.. doxygendefine:: TIMER_SR_UIF + +Event generation register (EGR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_EGR_TG_BIT +.. doxygendefine:: TIMER_EGR_CC4G_BIT +.. doxygendefine:: TIMER_EGR_CC3G_BIT +.. doxygendefine:: TIMER_EGR_CC2G_BIT +.. doxygendefine:: TIMER_EGR_CC1G_BIT +.. doxygendefine:: TIMER_EGR_UG_BIT + +.. doxygendefine:: TIMER_EGR_TG +.. doxygendefine:: TIMER_EGR_CC4G +.. doxygendefine:: TIMER_EGR_CC3G +.. doxygendefine:: TIMER_EGR_CC2G +.. doxygendefine:: TIMER_EGR_CC1G +.. doxygendefine:: TIMER_EGR_UG + +Capture/compare mode registers, common values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_CCMR_CCS_OUTPUT +.. doxygendefine:: TIMER_CCMR_CCS_INPUT_TI1 +.. doxygendefine:: TIMER_CCMR_CCS_INPUT_TI2 +.. doxygendefine:: TIMER_CCMR_CCS_INPUT_TRC + +Capture/compare mode register 1 (CCMR1) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_CCMR1_OC2CE_BIT +.. doxygendefine:: TIMER_CCMR1_OC2PE_BIT +.. doxygendefine:: TIMER_CCMR1_OC2FE_BIT +.. doxygendefine:: TIMER_CCMR1_OC1CE_BIT +.. doxygendefine:: TIMER_CCMR1_OC1PE_BIT +.. doxygendefine:: TIMER_CCMR1_OC1FE_BIT + +.. doxygendefine:: TIMER_CCMR1_OC2CE +.. doxygendefine:: TIMER_CCMR1_OC2M +.. doxygendefine:: TIMER_CCMR1_IC2F +.. doxygendefine:: TIMER_CCMR1_OC2PE +.. doxygendefine:: TIMER_CCMR1_OC2FE +.. doxygendefine:: TIMER_CCMR1_IC2PSC +.. doxygendefine:: TIMER_CCMR1_CC2S +.. doxygendefine:: TIMER_CCMR1_CC2S_OUTPUT +.. doxygendefine:: TIMER_CCMR1_CC2S_INPUT_TI1 +.. doxygendefine:: TIMER_CCMR1_CC2S_INPUT_TI2 +.. doxygendefine:: TIMER_CCMR1_CC2S_INPUT_TRC +.. doxygendefine:: TIMER_CCMR1_OC1CE +.. doxygendefine:: TIMER_CCMR1_OC1M +.. doxygendefine:: TIMER_CCMR1_IC1F +.. doxygendefine:: TIMER_CCMR1_OC1PE +.. doxygendefine:: TIMER_CCMR1_OC1FE +.. doxygendefine:: TIMER_CCMR1_IC1PSC +.. doxygendefine:: TIMER_CCMR1_CC1S +.. doxygendefine:: TIMER_CCMR1_CC1S_OUTPUT +.. doxygendefine:: TIMER_CCMR1_CC1S_INPUT_TI1 +.. doxygendefine:: TIMER_CCMR1_CC1S_INPUT_TI2 +.. doxygendefine:: TIMER_CCMR1_CC1S_INPUT_TRC + +Capture/compare mode register 2 (CCMR2) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_CCMR2_OC4CE_BIT +.. doxygendefine:: TIMER_CCMR2_OC4PE_BIT +.. doxygendefine:: TIMER_CCMR2_OC4FE_BIT +.. doxygendefine:: TIMER_CCMR2_OC3CE_BIT +.. doxygendefine:: TIMER_CCMR2_OC3PE_BIT +.. doxygendefine:: TIMER_CCMR2_OC3FE_BIT + +.. doxygendefine:: TIMER_CCMR2_OC4CE +.. doxygendefine:: TIMER_CCMR2_OC4M +.. doxygendefine:: TIMER_CCMR2_IC2F +.. doxygendefine:: TIMER_CCMR2_OC4PE +.. doxygendefine:: TIMER_CCMR2_OC4FE +.. doxygendefine:: TIMER_CCMR2_IC2PSC +.. doxygendefine:: TIMER_CCMR2_CC4S +.. doxygendefine:: TIMER_CCMR1_CC4S_OUTPUT +.. doxygendefine:: TIMER_CCMR1_CC4S_INPUT_TI1 +.. doxygendefine:: TIMER_CCMR1_CC4S_INPUT_TI2 +.. doxygendefine:: TIMER_CCMR1_CC4S_INPUT_TRC +.. doxygendefine:: TIMER_CCMR2_OC3CE +.. doxygendefine:: TIMER_CCMR2_OC3M +.. doxygendefine:: TIMER_CCMR2_IC1F +.. doxygendefine:: TIMER_CCMR2_OC3PE +.. doxygendefine:: TIMER_CCMR2_OC3FE +.. doxygendefine:: TIMER_CCMR2_IC1PSC +.. doxygendefine:: TIMER_CCMR2_CC3S +.. doxygendefine:: TIMER_CCMR1_CC3S_OUTPUT +.. doxygendefine:: TIMER_CCMR1_CC3S_INPUT_TI1 +.. doxygendefine:: TIMER_CCMR1_CC3S_INPUT_TI2 +.. doxygendefine:: TIMER_CCMR1_CC3S_INPUT_TRC + +Capture/compare enable register (CCER) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_CCER_CC4P_BIT +.. doxygendefine:: TIMER_CCER_CC4E_BIT +.. doxygendefine:: TIMER_CCER_CC3P_BIT +.. doxygendefine:: TIMER_CCER_CC3E_BIT +.. doxygendefine:: TIMER_CCER_CC2P_BIT +.. doxygendefine:: TIMER_CCER_CC2E_BIT +.. doxygendefine:: TIMER_CCER_CC1P_BIT +.. doxygendefine:: TIMER_CCER_CC1E_BIT + +.. doxygendefine:: TIMER_CCER_CC4P +.. doxygendefine:: TIMER_CCER_CC4E +.. doxygendefine:: TIMER_CCER_CC3P +.. doxygendefine:: TIMER_CCER_CC3E +.. doxygendefine:: TIMER_CCER_CC2P +.. doxygendefine:: TIMER_CCER_CC2E +.. doxygendefine:: TIMER_CCER_CC1P +.. doxygendefine:: TIMER_CCER_CC1E + +Break and dead-time register (BDTR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_BDTR_MOE_BIT +.. doxygendefine:: TIMER_BDTR_AOE_BIT +.. doxygendefine:: TIMER_BDTR_BKP_BIT +.. doxygendefine:: TIMER_BDTR_BKE_BIT +.. doxygendefine:: TIMER_BDTR_OSSR_BIT +.. doxygendefine:: TIMER_BDTR_OSSI_BIT + +.. doxygendefine:: TIMER_BDTR_MOE +.. doxygendefine:: TIMER_BDTR_AOE +.. doxygendefine:: TIMER_BDTR_BKP +.. doxygendefine:: TIMER_BDTR_BKE +.. doxygendefine:: TIMER_BDTR_OSSR +.. doxygendefine:: TIMER_BDTR_OSSI +.. doxygendefine:: TIMER_BDTR_LOCK +.. doxygendefine:: TIMER_BDTR_LOCK_OFF +.. doxygendefine:: TIMER_BDTR_LOCK_LEVEL1 +.. doxygendefine:: TIMER_BDTR_LOCK_LEVEL2 +.. doxygendefine:: TIMER_BDTR_LOCK_LEVEL3 +.. doxygendefine:: TIMER_BDTR_DTG + +DMA control register (DCR) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: TIMER_DCR_DBL +.. doxygendefine:: TIMER_DCR_DBL_1BYTE +.. doxygendefine:: TIMER_DCR_DBL_2BYTE +.. doxygendefine:: TIMER_DCR_DBL_3BYTE +.. doxygendefine:: TIMER_DCR_DBL_4BYTE +.. doxygendefine:: TIMER_DCR_DBL_5BYTE +.. doxygendefine:: TIMER_DCR_DBL_6BYTE +.. doxygendefine:: TIMER_DCR_DBL_7BYTE +.. doxygendefine:: TIMER_DCR_DBL_8BYTE +.. doxygendefine:: TIMER_DCR_DBL_9BYTE +.. doxygendefine:: TIMER_DCR_DBL_10BYTE +.. doxygendefine:: TIMER_DCR_DBL_11BYTE +.. doxygendefine:: TIMER_DCR_DBL_12BYTE +.. doxygendefine:: TIMER_DCR_DBL_13BYTE +.. doxygendefine:: TIMER_DCR_DBL_14BYTE +.. doxygendefine:: TIMER_DCR_DBL_15BYTE +.. doxygendefine:: TIMER_DCR_DBL_16BYTE +.. doxygendefine:: TIMER_DCR_DBL_17BYTE +.. doxygendefine:: TIMER_DCR_DBL_18BYTE +.. doxygendefine:: TIMER_DCR_DBA +.. doxygendefine:: TIMER_DCR_DBA_CR1 +.. doxygendefine:: TIMER_DCR_DBA_CR2 +.. doxygendefine:: TIMER_DCR_DBA_SMCR +.. doxygendefine:: TIMER_DCR_DBA_DIER +.. doxygendefine:: TIMER_DCR_DBA_SR +.. doxygendefine:: TIMER_DCR_DBA_EGR +.. doxygendefine:: TIMER_DCR_DBA_CCMR1 +.. doxygendefine:: TIMER_DCR_DBA_CCMR2 +.. doxygendefine:: TIMER_DCR_DBA_CCER +.. doxygendefine:: TIMER_DCR_DBA_CNT +.. doxygendefine:: TIMER_DCR_DBA_PSC +.. doxygendefine:: TIMER_DCR_DBA_ARR +.. doxygendefine:: TIMER_DCR_DBA_RCR +.. doxygendefine:: TIMER_DCR_DBA_CCR1 +.. doxygendefine:: TIMER_DCR_DBA_CCR2 +.. doxygendefine:: TIMER_DCR_DBA_CCR3 +.. doxygendefine:: TIMER_DCR_DBA_CCR4 +.. doxygendefine:: TIMER_DCR_DBA_BDTR +.. doxygendefine:: TIMER_DCR_DBA_DCR +.. doxygendefine:: TIMER_DCR_DBA_DMAR diff --git a/source/libmaple/api/usart.rst b/source/libmaple/api/usart.rst index 26e6b9c..1575a8f 100644 --- a/source/libmaple/api/usart.rst +++ b/source/libmaple/api/usart.rst @@ -4,9 +4,193 @@ ``usart.h`` =========== -[Stub] support. +Universal Synchronous/Asynchronous Receiver/Transmitter (USART, or +commonly *serial port*) support. -Library Documentation ---------------------- +.. contents:: Contents + :local: -.. doxygenfile:: usart.h +Types +----- + +.. doxygenstruct:: usart_reg_map +.. doxygenstruct:: usart_dev + +Devices +------- + +.. doxygenvariable:: USART1 +.. doxygenvariable:: USART2 +.. doxygenvariable:: USART3 +.. doxygenvariable:: UART4 +.. doxygenvariable:: UART5 + +Functions +--------- + +.. doxygenfunction:: usart_init +.. doxygenfunction:: usart_set_baud_rate +.. doxygenfunction:: usart_enable +.. doxygenfunction:: usart_disable +.. doxygenfunction:: usart_disable_all +.. doxygenfunction:: usart_foreach +.. doxygenfunction:: usart_tx +.. doxygenfunction:: usart_putudec +.. doxygenfunction:: usart_putc +.. doxygenfunction:: usart_putstr +.. doxygenfunction:: usart_getc +.. doxygenfunction:: usart_data_available +.. doxygenfunction:: usart_reset_rx + +Register Map Base Pointers +-------------------------- + +.. doxygendefine:: USART1_BASE +.. doxygendefine:: USART2_BASE +.. doxygendefine:: USART3_BASE +.. doxygendefine:: UART4_BASE +.. doxygendefine:: UART5_BASE + +Register Bit Definitions +------------------------ + +Status Register +~~~~~~~~~~~~~~~ + +.. doxygendefine:: USART_SR_CTS_BIT +.. doxygendefine:: USART_SR_LBD_BIT +.. doxygendefine:: USART_SR_TXE_BIT +.. doxygendefine:: USART_SR_TC_BIT +.. doxygendefine:: USART_SR_RXNE_BIT +.. doxygendefine:: USART_SR_IDLE_BIT +.. doxygendefine:: USART_SR_ORE_BIT +.. doxygendefine:: USART_SR_NE_BIT +.. doxygendefine:: USART_SR_FE_BIT +.. doxygendefine:: USART_SR_PE_BIT + +.. doxygendefine:: USART_SR_CTS +.. doxygendefine:: USART_SR_LBD +.. doxygendefine:: USART_SR_TXE +.. doxygendefine:: USART_SR_TC +.. doxygendefine:: USART_SR_RXNE +.. doxygendefine:: USART_SR_IDLE +.. doxygendefine:: USART_SR_ORE +.. doxygendefine:: USART_SR_NE +.. doxygendefine:: USART_SR_FE +.. doxygendefine:: USART_SR_PE + +Data register +~~~~~~~~~~~~~ + +.. doxygendefine:: USART_DR_DR + +Baud Rate Register +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: USART_BRR_DIV_MANTISSA +.. doxygendefine:: USART_BRR_DIV_FRACTION + +Control Register 1 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: USART_CR1_UE_BIT +.. doxygendefine:: USART_CR1_M_BIT +.. doxygendefine:: USART_CR1_WAKE_BIT +.. doxygendefine:: USART_CR1_PCE_BIT +.. doxygendefine:: USART_CR1_PS_BIT +.. doxygendefine:: USART_CR1_PEIE_BIT +.. doxygendefine:: USART_CR1_TXEIE_BIT +.. doxygendefine:: USART_CR1_TCIE_BIT +.. doxygendefine:: USART_CR1_RXNEIE_BIT +.. doxygendefine:: USART_CR1_IDLEIE_BIT +.. doxygendefine:: USART_CR1_TE_BIT +.. doxygendefine:: USART_CR1_RE_BIT +.. doxygendefine:: USART_CR1_RWU_BIT +.. doxygendefine:: USART_CR1_SBK_BIT + +.. doxygendefine:: USART_CR1_UE +.. doxygendefine:: USART_CR1_M +.. doxygendefine:: USART_CR1_WAKE +.. doxygendefine:: USART_CR1_WAKE_IDLE +.. doxygendefine:: USART_CR1_WAKE_ADDR +.. doxygendefine:: USART_CR1_PCE +.. doxygendefine:: USART_CR1_PS +.. doxygendefine:: USART_CR1_PS_EVEN +.. doxygendefine:: USART_CR1_PS_ODD +.. doxygendefine:: USART_CR1_PEIE +.. doxygendefine:: USART_CR1_TXEIE +.. doxygendefine:: USART_CR1_TCIE +.. doxygendefine:: USART_CR1_RXNEIE +.. doxygendefine:: USART_CR1_IDLEIE +.. doxygendefine:: USART_CR1_TE +.. doxygendefine:: USART_CR1_RE +.. doxygendefine:: USART_CR1_RWU +.. doxygendefine:: USART_CR1_RWU_ACTIVE +.. doxygendefine:: USART_CR1_RWU_MUTE +.. doxygendefine:: USART_CR1_SBK + +Control Register 2 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: USART_CR2_LINEN_BIT +.. doxygendefine:: USART_CR2_CLKEN_BIT +.. doxygendefine:: USART_CR2_CPOL_BIT +.. doxygendefine:: USART_CR2_CPHA_BIT +.. doxygendefine:: USART_CR2_LBCL_BIT +.. doxygendefine:: USART_CR2_LBDIE_BIT +.. doxygendefine:: USART_CR2_LBDL_BIT + +.. doxygendefine:: USART_CR2_LINEN +.. doxygendefine:: USART_CR2_STOP +.. doxygendefine:: USART_CR2_STOP_BITS_1 +.. doxygendefine:: USART_CR2_STOP_BITS_POINT_5 +.. doxygendefine:: USART_CR2_STOP_BITS_1_POINT_5 +.. doxygendefine:: USART_CR2_STOP_BITS_2 +.. doxygendefine:: USART_CR2_CLKEN +.. doxygendefine:: USART_CR2_CPOL +.. doxygendefine:: USART_CR2_CPOL_LOW +.. doxygendefine:: USART_CR2_CPOL_HIGH +.. doxygendefine:: USART_CR2_CPHA +.. doxygendefine:: USART_CR2_CPHA_FIRST +.. doxygendefine:: USART_CR2_CPHA_SECOND +.. doxygendefine:: USART_CR2_LBCL +.. doxygendefine:: USART_CR2_LBDIE +.. doxygendefine:: USART_CR2_LBDL +.. doxygendefine:: USART_CR2_LBDL_10_BIT +.. doxygendefine:: USART_CR2_LBDL_11_BIT +.. doxygendefine:: USART_CR2_ADD + +Control Register 3 +~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: USART_CR3_CTSIE_BIT +.. doxygendefine:: USART_CR3_CTSE_BIT +.. doxygendefine:: USART_CR3_RTSE_BIT +.. doxygendefine:: USART_CR3_DMAT_BIT +.. doxygendefine:: USART_CR3_DMAR_BIT +.. doxygendefine:: USART_CR3_SCEN_BIT +.. doxygendefine:: USART_CR3_NACK_BIT +.. doxygendefine:: USART_CR3_HDSEL_BIT +.. doxygendefine:: USART_CR3_IRLP_BIT +.. doxygendefine:: USART_CR3_IREN_BIT +.. doxygendefine:: USART_CR3_EIE_BIT + +.. doxygendefine:: USART_CR3_CTSIE +.. doxygendefine:: USART_CR3_CTSE +.. doxygendefine:: USART_CR3_RTSE +.. doxygendefine:: USART_CR3_DMAT +.. doxygendefine:: USART_CR3_DMAR +.. doxygendefine:: USART_CR3_SCEN +.. doxygendefine:: USART_CR3_NACK +.. doxygendefine:: USART_CR3_HDSEL +.. doxygendefine:: USART_CR3_IRLP +.. doxygendefine:: USART_CR3_IRLP_NORMAL +.. doxygendefine:: USART_CR3_IRLP_LOW_POWER +.. doxygendefine:: USART_CR3_IREN +.. doxygendefine:: USART_CR3_EIE + +Guard Time and Prescaler Register +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: USART_GTPR_GT +.. doxygendefine:: USART_GTPR_PSC diff --git a/source/libmaple/api/util.rst b/source/libmaple/api/util.rst index 50ffe76..06c9246 100644 --- a/source/libmaple/api/util.rst +++ b/source/libmaple/api/util.rst @@ -4,9 +4,48 @@ ``util.h`` ========== -[Stub] support. +.. TODO [0.2.0?] clean this up. -Library Documentation ---------------------- +Miscellaneous utility macros and procedures. -.. doxygenfile:: util.h +.. contents:: Contents + :local: + +Bit Manipulation +---------------- + +:: + + #define BIT(shift) (1UL << (shift)) + #define BIT_MASK_SHIFT(mask, shift) ((mask) << (shift)) + /** Gets bits m to n of x */ + #define GET_BITS(x, m, n) ((((uint32)x) << (31 - (n))) >> ((31 - (n)) + (m))) + #define IS_POWER_OF_TWO(v) (v && !(v & (v - 1))) + +Failure Routines +---------------- + +.. doxygenfunction:: throb + +Asserts and Debug Levels +------------------------ + +The level of libmaple's assertion support is determined by +``DEBUG_LEVEL``, as follows: + +.. doxygendefine:: DEBUG_LEVEL + +The current assert macros are ``ASSERT()`` and ``ASSERT_FAULT()``. +``ASSERT()`` is checked when ``DEBUG_LEVEL >= DEBUG_ALL``. +``ASSERT_FAULT()`` is checked whenever ``DEBUG_LEVEL >= DEBUG_FAULT``. + +As explained above, an assert macro is checked when the current +``DEBUG_LEVEL`` is high enough. If the debug level is too low, the +macro expands into a no-op that gets compiled away. + +If an assertion fails, execution is halted at the point of the failed +assertion. When libmaple has been configured properly (Wirish +performs this configuration by default), the built-in LED throbs in a +smooth pattern to signal the failed assertion (using +:c:func:`throb()`), and the file and line where the assert failed are +transmitted to the user as detailed in :ref:`lang-assert`. -- cgit v1.2.3 From 3e67ecc84bbe08238b4a4d1077657347b1f75abb Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 26 Aug 2011 20:07:05 -0400 Subject: contributing.rst: Split off "Git Resources" section; add new article. I've been linking people to the "submitting patches via email" section when I really wanted them to look at the Git resources. Seems like good enough reason to split it up. Also, reference a nice article from the Linux Journal. --- source/libmaple/contributing.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/source/libmaple/contributing.rst b/source/libmaple/contributing.rst index debee6b..aeaeacb 100644 --- a/source/libmaple/contributing.rst +++ b/source/libmaple/contributing.rst @@ -103,8 +103,13 @@ the following information in your email: 4. A sign-off line certifying your `developer certificate of origin `_ [#fcert]_. -That said, we'd really prefer a pull request. If you'd like to learn -more about Git, we recommend the following resources: +.. _libmaple-git-resources: + +Git Resources +------------- + +If you'd like to learn more about Git, we recommend the following +resources: * `The Git Community Book `_: A collaboratively edited book on Git. @@ -112,6 +117,12 @@ more about Git, we recommend the following resources: * `Pro Git `_: despite its title, this is a fairly beginner-friendly source of information. +* `Git - Revision Control Perfected (Linux Journal) + `_: + Despite a title that makes it sound like it was written by a + marketing department, this is a very good introductory article on + basic Git concepts, and a solid primer on Git's internals. + * `Understanding Git Conceptually `_: a good, introductory tutorial on Git's fundamental concepts. -- cgit v1.2.3 From 08ecbba662402382fb5558ee7832f23dcf83d445 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 29 Aug 2011 19:10:30 -0400 Subject: arduino-compatibility: Add link to wiki Compatible Shields page. --- source/arduino-compatibility.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/arduino-compatibility.rst b/source/arduino-compatibility.rst index b564e78..f7d3210 100644 --- a/source/arduino-compatibility.rst +++ b/source/arduino-compatibility.rst @@ -123,6 +123,10 @@ differences, most of which are improvements: Shield and Device Compatibility ------------------------------- +**Can't find your shield?** Check out the `Compatible Shields +`_ page +on our wiki. + .. list-table:: :header-rows: 1 -- cgit v1.2.3 From 2b793551da411dfc0534322b9b7c1b03766fca6e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 29 Aug 2011 19:45:55 -0400 Subject: hardwarespi: Add docs on SPI modes. --- source/lang/api/hardwarespi.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst index 3e71fb6..f90fc07 100644 --- a/source/lang/api/hardwarespi.rst +++ b/source/lang/api/hardwarespi.rst @@ -57,6 +57,10 @@ The speed at which the SPI port communicates is configured using a .. note:: Due to hardware issues, you can't use the frequency ``SPI_140_625KHz`` with SPI port 1. +The "mode" value determines the clock phase and polarity, like so: + +.. doxygenenum:: spi_mode + You'll need to determine the correct values for ``frequency``, ``bitOrder``, and ``mode`` yourself, by consulting the datasheet for the device you're communicating with. Continuing our example from -- cgit v1.2.3 From 0cf0959b54c05d9a058304331c3326b579c9b2d9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 30 Aug 2011 00:12:35 -0400 Subject: [libmaple] dma.rst: Remove warning about dma_attach_interrupt(). This was fixed in libmaple commit f99e0310faf34ab37f7fb31ff2592fa6d6c3213d. --- source/libmaple/api/dma.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/libmaple/api/dma.rst b/source/libmaple/api/dma.rst index 2acca41..d4e1683 100644 --- a/source/libmaple/api/dma.rst +++ b/source/libmaple/api/dma.rst @@ -33,9 +33,6 @@ Functions .. TODO [0.0.11?] figure out the dma_attach_interrupt weirdness -.. warning:: There currently appear to be problems with - the dma_attach_interrupt() implementation. - .. doxygenfunction:: dma_init .. doxygenfunction:: dma_setup_transfer .. doxygenfunction:: dma_set_num_transfers -- cgit v1.2.3 From 1c4ae6d18cb1b1300856b9eb2923cb745277f47b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 6 Sep 2011 19:25:47 -0400 Subject: coding-standard: Updates and clarifications. We got rid of the Windows newlines a while ago, so nuke the "exceptions" clause in the Unix newlines requirement. Teach the Doxygen -> Breathe information about the leaflabs-docs repo and the wiki. Also provide more links to further sources of information on what to do. --- source/libmaple/coding-standard.rst | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/source/libmaple/coding-standard.rst b/source/libmaple/coding-standard.rst index d22f12e..079329b 100644 --- a/source/libmaple/coding-standard.rst +++ b/source/libmaple/coding-standard.rst @@ -60,8 +60,7 @@ whitespace at save time. - 4 space indents (set in ``.dir-locals.el``). -- Unix newlines. Some exceptions are currently grandfathered in; these - will go away in time. +- Unix newlines. - No tab characters (set in ``.dir-locals.el``). @@ -319,19 +318,24 @@ Documentation by reading ST RM0008. - Doxygen comments generally only belong on types, functions, - etc. that are part of the public user-facing API. This generally - means that if there's ReST documentation for it under libmaple's - ``docs/source/``, it needs Doxygen comments, and that ReST should - use Breathe to pull that Doxygen comment out. (For more information - on this, see libmaple file ``docs/README``). - - There are some exceptions to this rule since Breathe isn't totally - mature yet and Sphinx's C++ domain is still in flux. In these - cases, document the code "manually" in ReST. - - This should be avoided if at all possible, since it creates a - maintenance burden of documenting things in two places at once, and - makes it easier for documentation to go stale. + etc. that are part of the public user-facing API. + + This essentially means that if what you're writing is going to be + documented under http://leaflabs.com/docs/ (i.e., if there's `Sphinx + documentation `_ for it in the + `leaflabs-docs `_ + repository), then you need to write Doxygen comments. Further, + those Sphinx docs should use Breathe to pull the Doxygen out. (For + more information on this, see the `leaflabs-docs README + `_). + + Because Breathe isn't totally mature yet, you won't always be able + to do this. In these cases, document the code "manually" using the + Sphinx `C and C++ domains + `_. This should + be avoided if at all possible, since it creates a maintenance burden + of documenting things in two places at once, and makes it easier for + documentation to go stale. If you do have to document something manually, put a comment in the source file informing future maintainers about it, so they'll pay @@ -345,7 +349,8 @@ Documentation This lets us keep the source files relatively free of "introductory" material, while allowing new readers a convenient starting point. These longer-form notes also have a habit of turning into official, - user-facing documentation. + user-facing documentation (or `wiki `_ + pages). - **For libmaple proper**, the convention is to document any user-facing function at the point where it is defined. In -- cgit v1.2.3 From 2633129a66849b754544b47eb3a4faf81ceb0aab Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 1 Sep 2011 10:18:55 -0400 Subject: hardware: Fix up board pages. Make the following changes to each of the board files under source/hardware/: - Link to ST docs from MCU name in Technical Specifications. - Tweak RM0008 description. - Beautify technical specifications. - Note that pin maps aren't exhaustive. It's becoming clear that we should eventually use some kind of templating language to get these pages done, but it's still overkill for now. --- source/hardware/maple-mini.rst | 30 ++++++++++++++++++------------ source/hardware/maple-ret6.rst | 34 ++++++++++++++++++++-------------- source/hardware/maple.rst | 30 ++++++++++++++++++------------ 3 files changed, 56 insertions(+), 38 deletions(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index 665970a..6f3f437 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -15,25 +15,26 @@ breadboard. Technical Specifications ------------------------ -* MCU: **STM32F103RCBT6**, a 32-bit ARM Cortex M3 microprocessor +* MCU: :ref:`STM32F103RCBT6 `, a 32-bit ARM Cortex + M3 microprocessor * Clock Speed: **72 MHz** * **128 KB Flash** and **20 KB SRAM** -* 34 Digital I/O Pins (:ref:`gpio`) -* 12 **PWM** pins at 16 bit resolution (:ref:`pwm`) -* 9 analog input pins, 12 bit **ADC** resolution (:ref:`adc`) -* 2 **SPI** peripherals (:ref:`spi`) -* 2 **I2C** peripherals (:ref:`i2c`) +* 34 :ref:`digital I/ pins (GPIOs) ` +* 12 :ref:`PWM ` pins at 16 bit resolution +* 9 :ref:`analog input (ADC) ` pins at 12 bit resolution +* 2 :ref:`SPI ` peripherals +* 2 :ref:`I2C ` peripherals * 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) -* 3 **USART** peripherals (:ref:`usart`) -* 1 advanced and 3 general-purpose **timers** (:ref:`timers`) -* Dedicated **USB** port for programming and communications (:ref:`usb`) -* **JTAG** (:ref:`jtag`) +* 3 :ref:`USART (serial port) ` peripherals +* 1 advanced and 3 general-purpose :ref:`timers ` +* Dedicated :ref:`USB ` port for programming and communications +* :ref:`jtag` * Nested Vectored Interrupt Controller (NVIC) (including :ref:`external interrupt ` on GPIOs) * Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital and analog regulators ` for low-noise analog performance -* :ref:`Four layer design ` +* :ref:`Open source, four layer design ` * Support for low power, sleep, and standby modes (<500 μA) * Operating Voltage: 3.3 V * Input Voltage (recommended): 3 V — 12 V @@ -97,6 +98,9 @@ This table shows a summary the available functionality on every GPIO pin, by peripheral type. The "5 V?" column documents whether or not the pin is :ref:`5 volt tolerant `. +Note that this table is not exhaustive; on some pins, more peripherals +are available than are listed here. + .. csv-table:: :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? @@ -347,6 +351,8 @@ This section lists known issues and warnings for the Maple Mini Rev 2 Recommended Reading ------------------- +.. _maple-mini-stdocs: + STMicro documentation for STM32F103CB microcontroller: * `Datasheet @@ -354,7 +360,7 @@ STMicro documentation for STM32F103CB microcontroller: (PDF); covers STM32F103x8, STM32F103xB. * `Reference Manual RM0008 `_ - (PDF); general, definitive resource for STM32F1 line. + (PDF); definitive resource for peripherals on the STM32F1 line. * `Programming Manual PM0056 `_ (PDF); assembly language and register reference. diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 25c1294..5d244af 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -21,27 +21,28 @@ the hands of Maple developers. Technical Specifications ------------------------ -* MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor +* MCU: :ref:`STM32F103RET6 `, a 32-bit ARM Cortex + M3 microprocessor * Clock Speed: **72 MHz** * **512 KB Flash** and **64 KB SRAM** -* 43 Digital I/O Pins (:ref:`gpio`) -* 18 **PWM** pins at 16 bit resolution (:ref:`pwm`) -* 15 analog input pins, 12 bit **ADC** resolution (:ref:`adc`) +* 43 :ref:`digital I/O pins (GPIOs) ` +* 18 :ref:`PWM ` pins at 16 bit resolution +* 15 :ref:`analog input (ADC) ` pins at 12 bit resolution * Built-in, 2 channel **DAC** at 12 bit resolution (:ref:`libmaple-dac`). -* 2 **SPI** peripherals with **I2S** support (:ref:`spi`) -* 2 **I2C** peripherals (:ref:`i2c`) -* 12 Channels of Direct Memory Access (**DMA**) - (:ref:`libmaple-dma`) with 2 DMA controllers -* 3 **USART** devices (:ref:`usart`) -* 2 advanced, 4 general-purpose, and 2 basic **timers** (:ref:`timers`) -* Dedicated **USB** port for programming and communications (:ref:`usb`) -* **JTAG** (:ref:`jtag`) +* 2 :ref:`SPI ` peripherals with **I2S** support +* 2 :ref:`I2C ` peripherals +* 12 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) + with 2 DMA controllers +* 3 :ref:`USART (serial port) ` peripherals +* 2 advanced, 4 general-purpose, and 2 basic :ref:`timers ` +* Dedicated :ref:`USB ` port for programming and communications +* :ref:`JTAG ` * Nested Vectored Interrupt Controller (NVIC) (including :ref:`external interrupt ` on GPIOs) * Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital and analog regulators ` for low-noise analog performance -* :ref:`Four layer design ` +* :ref:`Open-source, four layer design ` * Support for low power, sleep, and standby modes (<500 μA) * Operating Voltage: 3.3 V * Input Voltage (recommended): 4 V — 12 V @@ -107,6 +108,9 @@ This table shows a summary of the available functionality on every GPIO pin, by peripheral type. The "5 V?" column documents whether or not the pin is :ref:`5 volt tolerant `. +Note that this table is not exhaustive; on some pins, more peripherals +are available than are listed here. + .. csv-table:: :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART/USART `, :ref:`SPI `, 5 V? @@ -429,6 +433,8 @@ features only available on the STM32F103RET6. Recommended Reading ------------------- +.. _maple-ret6-stdocs: + STMicro documentation for STM32F103RE microcontroller: * `Datasheet @@ -436,7 +442,7 @@ STMicro documentation for STM32F103RE microcontroller: (PDF); covers STM32F103xC, STM32F103xD, STM32F103xE. * `Reference Manual RM0008 `_ - (PDF); general, definitive resource for STM32F1 line. + (PDF); definitive resource for peripherals on the STM32F1 line. * `Programming Manual PM0056 `_ (PDF); assembly language and register reference. diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 91198f2..69c3845 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -16,24 +16,25 @@ This page is a general resource for information specific to the Maple. Technical Specifications ------------------------ -* MCU: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor +* MCU: :ref:`STM32F103RBT6 `, a 32-bit ARM Cortex M3 + microprocessor * Clock Speed: **72 MHz** * **128 KB Flash** and **20 KB SRAM** -* 43 Digital I/O Pins (:ref:`gpio`) -* 15 **PWM** pins at 16 bit resolution (:ref:`pwm`) -* 15 analog input pins, 12-bit **ADC** resolution (:ref:`adc`) -* 2 **SPI** peripherals (:ref:`spi`) -* 2 **I2C** peripherals (:ref:`i2c`) +* 43 :ref:`digital I/O pins (GPIOs) ` +* 15 :ref:`PWM ` pins at 16 bit resolution +* 15 :ref:`analog input (ADC) ` pins at 12-bit resolution +* 2 :ref:`SPI ` peripherals +* 2 :ref:`I2C ` peripherals * 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) -* 3 **USART** peripherals (:ref:`usart`) -* One advanced and three general-purpose **timers** (:ref:`timers`) -* Dedicated **USB** port for programming and communications (:ref:`usb`) -* **JTAG** (:ref:`jtag`) +* 3 :ref:`USART (serial port) ` peripherals +* One advanced and three general-purpose :ref:`timers ` +* Dedicated :ref:`USB ` port for programming and communications +* :ref:`JTAG ` * Nested Vectored Interrupt Controller (NVIC) (including :ref:`external interrupt ` on GPIOs) * Supplies up to 500 mA at 3.3 V, with separate 250 mA digital and analog regulators for low-noise analog performance -* :ref:`Four layer design ` +* :ref:`Open source, four layer design ` * Support for low power, sleep, and standby modes (<500 μA) * Operating Voltage: 3.3 V * Input Voltage (recommended): 4 V — 12 V @@ -155,6 +156,9 @@ This table shows a summary of the available functionality on every GPIO pin, by peripheral type. The "5 V?" column documents whether or not the pin is :ref:`5 volt tolerant `. +Note that this table is not exhaustive; on some pins, more peripherals +are available than are listed here. + .. csv-table:: :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? @@ -552,6 +556,8 @@ Rev 1 Recommended Reading ------------------- +.. _maple-stdocs: + STMicro documentation for STM32F103RB microcontroller: * `Datasheet @@ -559,7 +565,7 @@ STMicro documentation for STM32F103RB microcontroller: (PDF); covers STM32F103x8, STM32F103xB. * `Reference Manual RM0008 `_ - (PDF); general, definitive resource for STM32F1 line. + (PDF); definitive resource for peripherals on the STM32F1 line. * `Programming Manual PM0056 `_ (PDF); assembly language and register reference. -- cgit v1.2.3 From e62227806e9f15923030644d2bcdfa2692afaf7c Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 1 Sep 2011 14:37:51 -0400 Subject: hardware/maple: Errata tweaks. - dipropylene glycol methyl ether acetate - barrel jack silk errors were marked over --- source/hardware/maple.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 69c3845..ca2afd7 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -108,6 +108,9 @@ board from another source, or you could damage it. supplied by up to 18 V. We recommend a barrel jack input voltage **no greater than 12 V**. + Rev5s manufactured after Spring 2011 may still have this error on + the silk, but it has been marked over. + See :ref:`this erratum ` for more information. Using the Built-in Battery Charger @@ -503,9 +506,10 @@ Rev 3 For reference, the button part number is KMR211GLFS and the flux remover we used is "Precision Electronics Cleaner" from RadioShack, - which is "Safe on most plastics" and contains Dipropylene glycol + which is "Safe on most plastics" and contains: dipropylene glycol monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol - methyl ether acetate, and carbon dioxide. + methyl ether acetate (say that three times fast!), and carbon + dioxide. * **Resistors on pins 0 and 1**: these header pins, which are RX/TX on USART2 (:ref:`Serial2 `), have resistors in-line -- cgit v1.2.3 From 00ce76dc2ce404ecf6fed07b8221a18bff99c08b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 1 Sep 2011 18:25:39 -0400 Subject: maple + RET6: Tweak battery charger docs. --- source/hardware/maple-ret6.rst | 3 +-- source/hardware/maple.rst | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 5d244af..90be01e 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -70,8 +70,7 @@ it, put a jumper across the CHRG header on the power selection header and across the USB, or EXT selectors, depending on whether you're charging the battery via USB cable or barrel jack connector. The LED labeled CHRG will light up while the battery is being charged. When -the battery is finished charging, the LED labeled DONE will also light -up. +the battery is finished charging, the LED labeled DONE will light up. .. _maple-ret6-gpios: diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index ca2afd7..51bd4e2 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -122,7 +122,7 @@ selection header and across the USB, or EXT selectors, depending on whether you're charging the battery via USB cable or barrel jack connector. The LED labeled CHRG will light up while the battery is being charged. When the battery is finished charging, the LED labeled -DONE will also light up. +DONE will light up. .. _maple-gpios: -- cgit v1.2.3 From 53c3edfcac0dd16a2881a8f02595b194830f30ab Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 1 Sep 2011 15:07:19 -0400 Subject: [WIP] Add fsmc.rst. This file explains the general purpose of the FSMC, and gives some information specific to its role in driving SRAM chips. --- source/fsmc.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 source/fsmc.rst diff --git a/source/fsmc.rst b/source/fsmc.rst new file mode 100644 index 0000000..dfd4916 --- /dev/null +++ b/source/fsmc.rst @@ -0,0 +1,14 @@ +.. _fsmc: + +FSMC +==== + +The Flexible Static Memory Controller (FSMC) is a peripheral which an +be configured to control a variety of external memory chips. For +example, it is used on the Maple Native to control the built-in SRAM +chip. + +.. TODO [0.0.12] Add info on: +.. +.. - Address, data, chip-select etc. pins +.. - Memory bank organization -- cgit v1.2.3 From 5b74166a0ad3df0ee672f34e61af3f847fb87951 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 1 Sep 2011 14:54:40 -0400 Subject: [WIP] Add hardware/maple-native-beta.rst. --- source/hardware/maple-native-beta.rst | 559 ++++++++++++++++++++++++++++++++++ source/index.rst | 3 +- 2 files changed, 561 insertions(+), 1 deletion(-) create mode 100644 source/hardware/maple-native-beta.rst diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst new file mode 100644 index 0000000..8b1dc45 --- /dev/null +++ b/source/hardware/maple-native-beta.rst @@ -0,0 +1,559 @@ +.. highlight:: sh + +.. _maple-native: + +Maple Native β +============== + +This page is a general resource for information specific to the Maple +Native Beta. Since this is a beta release, the information here may +change slightly between now and the final Maple Native release. + +.. contents:: Contents + :local: + +Technical Specifications +------------------------ + +.. TODO [0.0.12] Verify recommended input voltage + +* MCU: `STM32F103ZET6 `_, a 32-bit ARM Cortex M3 + microprocessor. +* Clock Speed: **72 MHz** +* **512 KB Flash**, **64 KB SRAM** (on-chip), **1 MB SRAM** (external) +* 106 :ref:`digital I/O pins ` +* 17 :ref:`PWM ` pins at 16 bit resolution +* 21 :ref:`analog input (ADC) ` pins at 12-bit resolution +* 3 :ref:`SPI ` peripherals +* 2 :ref:`I2C ` peripherals +* 12 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) + with 2 DMA controllers +* 3 :ref:`USART (serial port) ` peripherals, 2 **UART** peripherals +* 2 advanced, 4 general-purpose, and 2 basic :ref:`timers ` +* Dedicated :ref:`USB ` port for programming and communications +* :ref:`JTAG ` +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt ` on GPIOs) +* Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital + and analog regulators ` for low-noise analog + performance +* :ref:`Open-source, four layer design ` +* Support for low power, sleep, and standby modes (<500 μA) +* Operating Voltage: 3.3 V +* Input Voltage (recommended): 3 V — 12 V +* Dimensions: 4″ × 2.1″ + +.. _maple-native-b-powering: + +Powering the Maple Native +------------------------- + +The Maple Native may be powered from the barrel jack connector, USB, +or a LiPo battery. The power source is determined by the header +labeled "PWRSEL" on the silkscreen. Boards are shipped with a jumper +on the USB selector. In order to power it off of an alternative +source, unplug the Maple Native, then move the jumper to the desired +selector before reconnecting power. + +You can also power the Maple Native via the pin labeled "Vin" on the +vertical header to the right of the PWRSEL header. This pin feeds +into both the digital and analog voltage regulators. However, don't +do this while simultaneously powering the board from another source, +or you could damage it. + +We recommend an input voltage no greater than 12 V. + +Using the Built-in Battery Charger +---------------------------------- + +Maple Native includes a built-in LiPo battery charger. In order to +use it, put a jumper across the CHRG selector on the PWRSEL header and +across the USB, or EXT selectors, depending on whether you're charging +the battery via USB cable or Vin, respectively. The LED labeled CHRG +will light up while the battery is being charged. When the battery is +finished charging, the LED labeled DONE will light up. + +.. _maple-native-b-gpios: + +GPIO Information +---------------- + +The Maple Native features 106 total input/output pins, numbered ``D0`` +through ``D105``. In most cases, these numbers correspond to the +numeric values next to each header on the Maple Native's silkscreen. +However, pins ``D101`` through ``D105`` are broken out to the +:ref:`JTAG ` header, and are not numbered on the silkscreen. In +addition, some other pins have other uses by default [#fusedpins]_. + +.. _maple-native-b-but: + +Pin ``D6`` is the Native's :ref:`button pin `. +It is thus mainly useful as an :ref:`input `. The +pin will :ref:`read ` ``HIGH`` when the :ref:`button +is pressed `. + +.. _maple-native-b-led: + +Pin ``D22`` is the Native's :ref:`LED pin `. +It is thus mainly useful as an :ref:`output `. The +LED will glow when ``HIGH`` is :ref:`written ` to +it. + +.. _maple-native-b-fsmc: + +.. FIXME [0.0.12] Add note on Native "use SRAM" vs. "no SRAM" builds +.. +.. TODO [0.0.12] Specify which pins are safe, and which aren't + +Many of the pins on the right header (pins ``D56`` through ``D100``, +the header is labeled "FSMC" on the silkscreen) are connected to +:ref:`FSMC ` lines. Using these pins as GPIOs may render the +memory chip useless, which can cause your program to crash. For this +reason, we don't recommend that you use these pins unless you know +what you are doing. + +.. _maple-native-b-jtag: + +Pins ``D101`` through ``D105`` are connected to the pads on the +:ref:`JTAG ` header. In order to use them as GPIOs, you must +first disable the Maple Native's debug ports. You can do this by +calling :ref:`lang-disabledebugports`. (Note that this means you +won't be able to use JTAG or SW-Debug to debug your program). + +.. TODO [0.1.0] silkscreen pictures + +.. _maple-native-b-pin-map-master: + +Master Pin Map +^^^^^^^^^^^^^^ + +This table shows a summary the available functionality on every GPIO +pin, by peripheral type. The "5 V?" column documents whether or not +the pin is :ref:`5 volt tolerant `. + +Note that this table is not exhaustive; on some pins, more peripherals +are available than are listed here. + +**Top header:** + +.. csv-table:: + :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? + + D0, PB10, -, -, 2_SCL, 3_TX, -, Yes + D1, PB11, -, -, 2_SDA, 3_RX, -, Yes + D2, PB12, -, 1_BKIN, 2_SMBA, 3_CK, 2_NSS, Yes + D3, PB13, -, -, -, 3_CTS, 2_SCK, Yes + D4, PB14, -, -, -, 3_RTS, 2_MISO, Yes + D5, PB15, -, -, -, -, 2_MOSI, Yes + D6, PG15, -, -, -, -, -, Yes + D7, PC0, 1_CH10, -, -, -, -, - + D8, PC1, 1_CH11, -, -, -, -, - + D9, PC2, 1_CH12, -, -, -, -, - + D10, PC3, 1_CH13, -, -, -, -, - + D11, PC4, 1_CH14, -, -, -, -, - + D12, PC5, 1_CH15, -, -, -, -, - + D13, PC6, -, 8_CH1, -, -, -, Yes + D14, PC7, -, 8_CH2, -, -, -, Yes + D15, PC8, -, 8_CH3, -, -, -, Yes + D16, PC9, -, 8_CH4, -, -, -, Yes + D17, PC10, -, -, -, 4_TX, -, Yes + D18, PC11, -, -, -, 4_RX, -, Yes + D19, PC12, -, -, -, 5_TX, -, Yes + D20, PC13, -, -, -, -, -, - + D21, PC14, -, -, -, -, -, - + D22, PC15, -, -, -, -, -, - + D23, PA8, -, 1_CH1, -, 1_CK, -, Yes + D24, PA9, -, 1_CH2, -, 1_TX, -, Yes + D25, PA10, -, 1_CH3, -, 1_RX, -, Yes + D26, PB9, -, 4_CH4, -, -, -, Yes + +**Bottom header:** + +.. note:: ``D48``, ``D49``, ``D50``, ``D51`` are also connected to + Timer 2 channels 1, 2, 3, and 4, respectively. + +.. csv-table:: + :header: Pin, :ref:`GPIO `, :ref:`ADC `, :ref:`Timer `, :ref:`I2C `, :ref:`UART `, :ref:`SPI `, 5 V? + + D27, PD2, -, 3_ETR, -, 5_RX, -, Yes + D28, PD3, -, -, -, -, -, Yes + D29, PD6, -, -, -, -, -, Yes + D30, PG11, -, -, -, -, -, Yes + D31, PG12, -, -, -, -, -, Yes + D32, PG13, -, -, -, -, -, Yes + D33, PG14, -, -, -, -, -, Yes + D34, PG8, -, -, -, -, -, Yes + D35, PG7, -, -, -, -, -, Yes + D36, PG6, -, -, -, -, -, Yes + D37, PB5, -, -, 1_SMBA, -, 3_MOSI, - + D38, PB6, -, 4_CH1, 1_SCL, -, -, Yes + D39, PB7, -, 4_CH2, 1_SDA, -, -, Yes + D40, PF11, -, -, -, -, -, Yes + D41, PF6, 3_CH4, -, -, -, -, - + D42, PF7, 3_CH5, -, -, -, -, - + D43, PF8, 3_CH6, -, -, -, -, - + D44, PF9, 3_CH7, -, -, -, -, - + D45, PF10, 3_CH8, -, -, -, -, - + D46, PB1, 1_CH9, 3_CH4, -, -, -, - + D47, PB0, 1_CH8, 3_CH3, -, -, -, - + D48, PA0, 1_CH0, 5_CH1, -, 2_CTS, -, - + D49, PA1, 1_CH1, 5_CH2, -, 2_RTS, -, - + D50, PA2, 1_CH2, 5_CH3, -, 2_TX, -, - + D51, PA3, 1_CH3, 5_CH4, -, 2_RX, -, - + D52, PA4, 1_CH4, -, -, 2_CK, 1_NSS, - + D53, PA5, 1_CH5, -, -, -, 1_SCK, - + D54, PA6, 1_CH6, 3_CH1, -, -, 1_MISO, - + D55, PA7, 1_CH7, 3_CH2, -, -, 1_MOSI, - + +.. _maple-native-b-fsmc-map: + +**Right (FSMC) header** + +All of the following pins are 5V-tolerant. Note that in the "FSMC" +column below, entries with a "Dn" value (D0, D1, etc.) don't refer to +pins; they refer to FSMC data lines. See :ref:`RM0008 +` for more information. + +.. warning:: Many of the pins on this header are used by the Maple + Native's SRAM chip. Don't use them as GPIOs unless you know what + you're doing, or your program may crash. :ref:`See above + ` for more information. + +.. csv-table:: + :header: Pin, :ref:`GPIO `, :ref:`FSMC ` + + D56, PF0, A0 + D57, PD11, A16 + D58, P14, D0 + D59, PF1, A1 + D60, PD12, A17 + D61, PD15, D1 + D62, PF2, A2 + D63, PD13, A18 + D64, PD0, D2 + D65, PF3, A3 + D66, PE3, A19 + D67, PD1, D3 + D68, PF4, A4 + D69, PE4, A20 + D70, PE7, D4 + D71, PF5, A5 + D72, PE5, A21 + D73, PE8, D8 + D74, PF12, A6 + D75, PE6, A22 + D76, PE9, D6 + D77, PF13, A7 + D78, PE10, D7 + D79, PF14, A8 + D80, PG9, NE2/NCE3 + D81, PE11, D8 + D82, PF15, A9 + D83, PG10, NCE4_1/NE3/NCE4_2 + D84, PE12, D9 + D85, PG0, A10 + D86, PD5, NWE + D87, PE13, D10 + D88, PG1, A11 + D89, PD4, NOE + D90, PE14, D11 + D91, PG2, A12 + D92, PE1, NBL1 + D93, PE15, D12 + D94, PG3, A13 + D95, PE0, NBL0 + D96, PD8, D13 + D97, PG4, A14 + D98, PD9, D14 + D99, PG5, A15 + D100, PD10, D15 + +**JTAG header pins** + +.. note:: See :ref:`above ` for more information on + these pins. + +.. csv-table:: + :header: Pin, :ref:`GPIO `, :ref:`SPI `, 5 V? + + D101, PA13, -, Yes + D102, PA14, -, Yes + D103, PA15, 3_NSS, Yes + D104, PB3, 3_SCK, Yes + D105, PB4, 3_MISO, Yes + +.. _maple-native-b-gpio-port-map: + +GPIO Port Pin Map +^^^^^^^^^^^^^^^^^ + +The following tables show what pins are associated with each +:ref:`GPIO port `. + +.. csv-table:: + :header: GPIOA, GPIOB, GPIOC, GPIOD + + PA0: D48, PB0: D47, PC0: D7, PD0: D64 + PA1: D49, PB1: D46, PC1: D8, PD1: D67 + PA2: D50, PB2: -, PC2: D9, PD2: D27 + PA3: D51, PB3: D104, PC3: D10, PD3: D28 + PA4: D52, PB4: D105, PC4: D11, PD4: D89 + PA5: D53, PB5: D37, PC5: D12, PD5: D86 + PA6: D54, PB6: D38, PC6: D13, PD6: D29 + PA7: D55, PB7: D39, PC7: D14, PD7: - + PA8: D23, PB8: -, PC8: D15, PD8: D96 + PA9: D24, PB9: D26, PC9: D16, PD9: D98 + PA10: D25, PB10: D0, PC10: D17, PD10: D100 + PA11: -, PB11: D1, PC11: D18, PD11: D57 + PA12: -, PB12: D2, PC12: D19, PD12: D60 + PA13: D101, PB13: D3, PC13: D20, PD13: D63 + PA14: D102, PB14: D4, PC14: D21, PD14: D58 + +.. csv-table:: + :header: GPIOE, GPIOF, GPIOG + + PE0: D95, PF0: D56, PG0: D85 + PE1: D92, PF1: D59, PG1: D88 + PE2: - PF2: D62, PG2: D91, + PE3: D66, PF3: D65, PG3: D94 + PE4: D69, PF4: D68, PG4: D97 + PE5: D72, PF5: D71, PG5: D99 + PE6: D75, PF6: D41, PG6: D36 + PE7: D70, PF7: D42, PG7: D35 + PE8: D73, PF8: D43, PG8: D34 + PE9: D76, PF9: D44, PG9: D80 + PE10: D78, PF10: D45, PG10: D83 + PE11: D81, PF11: D40, PG11: D30 + PE12: D84, PF12: D74, PG12: D31 + PE13: D87, PF13: D77, PG13: D32 + PE14: D90, PF14: D79, PG14: D33 + +.. _maple-native-b-timer-map: + +Timer Pin Map +^^^^^^^^^^^^^ + +The following table shows what pins are associated with a particular +timer's capture/compare channels. + +There is no mistake between timers 2 and 5. They really do share +those pins. If you like, you can remap some of the timer 2 channels +to get extra PWM pins; see :ref:`afio_remap() (in gpio.h) +`. + +.. csv-table:: + :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4 + :delim: | + + 1 | D23 | D24 | D25 | + 2 | D48 | D49 | D50 | D51 + 3 | D54 | D55 | D47 | D46 + 4 | D38 | D39 | | D26 + 5 | D48 | D49 | D50 | D51 + 8 | D13 | D14 | D15 | D16 + +.. _maple-native-b-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +`. + +.. list-table:: + :widths: 1 3 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - D7, D47, D48, D56, D64, D85, D95 + * - EXTI1 + - D8, D46, D49, D59, D67, D88, D92 + * - EXTI2 + - D9, D27, D50, D62, D91 + * - EXTI3 + - D10, D28, D51, D65, D66, D94, D104 + * - EXTI4 + - D11, D52, D68, D69, D89, D97, D105 + * - EXTI5 + - D12, D37, D53, D71, D72, D86, D99 + * - EXTI6 + - D13, D29, D36, D38, D41, D54, D75 + * - EXTI7 + - D14, D35, D39, D42, D55, D70 + * - EXTI8 + - D15, D23, D34, D43, D73, D96 + * - EXTI9 + - D16, D24, D26, D44, D76, D80, D98 + * - EXTI10 + - D0, D17, D25, D45, D78, D83, D100 + * - EXTI11 + - D1, D18, D30, D40, D57, D81 + * - EXTI12 + - D2, D19, D31, D60, D74, D84 + * - EXTI13 + - D3, D20, D32, D63, D77, D87, D101 + * - EXTI14 + - D4, D21, D33, D58, D79, D90, D102 + * - EXTI15 + - D5, D6, D22, D61, D82, D93, D103 + +.. _maple-native-b-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +The Maple Native has 3 :ref:`USART ` serial ports. They +communicate using the pins given in the following table. + +.. csv-table:: + :header: Serial port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | D24 | D25 | D23 | | + ``Serial2`` | D50 | D51 | D52 | D48 | D49 + ``Serial3`` | D0 | D1 | D2 | D3 | D4 + +The Maple Native also has 2 UART serial ports. Unlike USARTS, these +only communicate asynchronously, and thus only have TX and RX pins. +These are given in the following table. + +.. csv-table:: + :header: Serial port, TX, RX + :delim: | + + ``Serial4`` | D17 | D18 + ``Serial5`` | D19 | D27 + +.. _maple-native-b-adc-bank: + +Low-Noise ADC Pins +^^^^^^^^^^^^^^^^^^ + +.. TODO [0.0.12] finish this; ask Jess for help and confirmation + +Maple Native has an electrically isolated analog power plane with its +own regulator, and a geometrically isolated ground plane, + +Analog input pins D41 — D55 are laid out to correspond with these +analog planes, and our measurements indicate that they generally ofer +low noise ADC performance. However, analog performance may vary +depending upon the activity of other GPIOs. In particular, using PWM +on any of pins D46 — D51, D54, and D55 may cause digital noise. +Consult the :ref:`Maple Native beta hardware design files +` for more details. + +.. _maple-native-b-board-values: + +Board-Specific Values +--------------------- + +.. TODO [0.0.12] get pwm, used pins + +This section lists the Maple Native's :ref:`board-specific values +`. + +- ``CYCLES_PER_MICROSECOND``: 72 +- ``BOARD_BUTTON_PIN``: 6 +- ``BOARD_LED_PIN``: 22 +- ``BOARD_NR_GPIO_PINS``: 106 +- ``BOARD_NR_PWM_PINS``: +- ``boardPWMPins``: +- ``BOARD_NR_ADC_PINS``: 21 +- ``boardADCPins``: 7, 8, 9, 10, 11, 12, 41, 42, 43, 44, 45, 46, 47, + 48, 49, 50, 51, 52, 53, 54, 55 +- ``BOARD_NR_USED_PINS``: +- ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN`` +- ``BOARD_NR_USARTS``: +- ``BOARD_USART1_TX_PIN``: 24 +- ``BOARD_USART1_RX_PIN``: 25 +- ``BOARD_USART2_TX_PIN``: 50 +- ``BOARD_USART2_RX_PIN``: 51 +- ``BOARD_USART3_TX_PIN``: 0 +- ``BOARD_USART3_RX_PIN``: 1 +- ``BOARD_UART4_TX_PIN``: 17 +- ``BOARD_UART4_RX_PIN``: 18 +- ``BOARD_UART5_TX_PIN``: 19 +- ``BOARD_UART5_RX_PIN``: 27 +- ``BOARD_NR_SPI``: 3 +- ``BOARD_SPI1_NSS_PIN``: 52 +- ``BOARD_SPI1_MOSI_PIN``: 55 +- ``BOARD_SPI1_MISO_PIN``: 54 +- ``BOARD_SPI1_SCK_PIN``: 53 +- ``BOARD_SPI2_NSS_PIN``: 2 +- ``BOARD_SPI2_MOSI_PIN``: 5 +- ``BOARD_SPI2_MISO_PIN``: 4 +- ``BOARD_SPI2_SCK_PIN``: 3 +- ``BOARD_JTMS_SWDIO_PIN``: :ref:`103 ` +- ``BOARD_JTCK_SWCLK_PIN``: 102 +- ``BOARD_JTDI_PIN``: 103 +- ``BOARD_JTDO_PIN``: 104 +- ``BOARD_NJTRST_PIN``: 105 + +.. _maple-native-b-hardware: + +Hardware Design Files +^^^^^^^^^^^^^^^^^^^^^ + +The hardware schematics and board layout files are available in the +`Maple Native GitHub repository +`_. Download the `beta +version's hardware design files +`_ (ZIP format). + +If you're familiar with Git, you can clone the entire repository and +checkout the commit tagged "beta" using the following:: + + $ git clone git://github.com/leaflabs/maplenative.git + $ git checkout beta + +Failure Modes +------------- + +The following known failure modes apply to the Maple Native Beta. The +failure modes aren't design errors, but are easy ways to break or +damage your board permanently. + +* **Reversing Vin and GND**: when powering the Maple Native Beta via + the Vin and ground (GND) pins at the top left of the board, it is + possible to carelessly cause a short or switch the connections, + applying the high voltage to GND and ground to Vin. + + If this happens, you will reverse bias the diode beneath these pins, + most likely damaging it. This may cause excess voltage to + subsequently be delivered to the board once the reversed pins are + connected properly. + +Errata +------ + +This section lists known issues and warnings for the Maple Native +Beta. + +* **PWM on pin 39**: PWM on pin 39 appears to be nonfunctional. We + are looking into this issue. + +Recommended Reading +------------------- + +.. _maple-native-b-stdocs: + +STMicro documentation for STM32F103ZE microcontroller: + +* `Datasheet + `_ + (PDF); covers STM32F103xC, STM3F103xD, STM32F103xE. +* `Reference Manual RM0008 + `_ + (PDF); definitive resource for peripherals on the STM32F1 line. +* `Programming Manual PM0056 + `_ + (PDF); assembly language and register reference. +* `STM32F103RE `_ + overview page with links to further references. + +.. rubric:: Footnotes + +.. [#fusedpins] See :ref:`boardUsedPins ` + for more information. diff --git a/source/index.rst b/source/index.rst index 7886c4f..f24262d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -72,6 +72,7 @@ Have fun! hardware/maple.rst hardware/maple-ret6.rst hardware/maple-mini.rst + hardware/maple-native-beta.rst -.. TODO write/include these upon Mini and Native release +.. TODO write/include upon Native release .. hardware/maple-native.rst -- cgit v1.2.3 From 3bc661cd732edf59cdc96be735951cb68293c038 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 7 Sep 2011 22:49:01 -0400 Subject: stm32.rst: Update with prefixed defines. --- source/libmaple/api/stm32.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/source/libmaple/api/stm32.rst b/source/libmaple/api/stm32.rst index 82280bb..3b26703 100644 --- a/source/libmaple/api/stm32.rst +++ b/source/libmaple/api/stm32.rst @@ -12,6 +12,15 @@ than board-specific, which belongs in :ref:`Wirish Defines ------- +.. doxygendefine:: STM32_PCLK1 +.. doxygendefine:: STM32_PCLK2 +.. doxygendefine:: STM32_NR_INTERRUPTS +.. doxygendefine:: STM32_NR_GPIO_PORTS +.. doxygendefine:: STM32_DELAY_US_MULT + +Deprecated Defines +------------------ + .. doxygendefine:: PCLK1 .. doxygendefine:: PCLK2 .. doxygendefine:: NR_INTERRUPTS -- cgit v1.2.3 From d908fcb9e26113f947d07cb1e15f93d46483ce1a Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 7 Sep 2011 22:49:50 -0400 Subject: stm32.rst: Add STM32_SRAM_END. --- source/libmaple/api/stm32.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/libmaple/api/stm32.rst b/source/libmaple/api/stm32.rst index 3b26703..6e631b0 100644 --- a/source/libmaple/api/stm32.rst +++ b/source/libmaple/api/stm32.rst @@ -17,6 +17,7 @@ Defines .. doxygendefine:: STM32_NR_INTERRUPTS .. doxygendefine:: STM32_NR_GPIO_PORTS .. doxygendefine:: STM32_DELAY_US_MULT +.. doxygendefine:: STM32_SRAM_END Deprecated Defines ------------------ -- cgit v1.2.3 From c2b76b132fc7329aa744bb116a293c5a87cf5df5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 7 Sep 2011 22:50:38 -0400 Subject: gpio.rst: Add ref target for afio_remap(). I can't figure out how to get Breathe to properly put things into the C domain. This will have to do for now. --- source/libmaple/api/gpio.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/libmaple/api/gpio.rst b/source/libmaple/api/gpio.rst index 96058c0..faf0ad2 100644 --- a/source/libmaple/api/gpio.rst +++ b/source/libmaple/api/gpio.rst @@ -47,6 +47,8 @@ Functions .. doxygenfunction:: afio_init .. doxygenfunction:: afio_exti_select + +.. _gpio-h-afio-remap: .. doxygenfunction:: afio_remap .. doxygenfunction:: afio_cfg_debug_ports -- cgit v1.2.3 From b4d13e1abf3314ba66d0f40205463489d6de885f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 7 Sep 2011 22:54:40 -0400 Subject: hardware: Prefix pins in pin maps with "D". EXTI line and USART pin maps are missing "D" prefix. Add these. --- source/hardware/maple-mini.rst | 38 +++++++++++++++++++------------------- source/hardware/maple-ret6.rst | 38 +++++++++++++++++++------------------- source/hardware/maple.rst | 38 +++++++++++++++++++------------------- 3 files changed, 57 insertions(+), 57 deletions(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index 6f3f437..f773973 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -198,37 +198,37 @@ The following table shows which pins connect to which :ref:`EXTI lines * - EXTI Line - Pins * - EXTI0 - - 3, 11 + - D3, D11 * - EXTI1 - - 10, 33 + - D10, D33 * - EXTI2 - - 2, 9 + - D2, D9 * - EXTI3 - - 8, 19 + - D8, D19 * - EXTI4 - - 7, 18 + - D7, D18 * - EXTI5 - - 6, 17 + - D6, D17 * - EXTI6 - - 5, 16 + - D5, D16 * - EXTI7 - - 4, 15 + - D4, D15 * - EXTI8 - - 27, 32 + - D27, D32 * - EXTI9 - - 26 + - D26 * - EXTI10 - - 1, 25 + - D1, D25 * - EXTI11 - - 0, 24 + - D0, D24 * - EXTI12 - - 23, 31 + - D23, D31 * - EXTI13 - - 14, 22, 30 + - D14, D22, D30 * - EXTI14 - - 13, 21, 29 + - D13, D21, D29 * - EXTI15 - - 12, 20, 28 + - D12, D20, D28 .. _maple-mini-usart-map: @@ -243,9 +243,9 @@ table: :header: Serial Port, TX, RX, CK, CTS, RTS :delim: | - ``Serial1`` | 26 | 25 | 27 | 24 | 23 - ``Serial2`` | 9 | 8 | 7 | 11 | 10 - ``Serial3`` | 1 | 0 | 31 | 30 | 29 + ``Serial1`` | D26 | D25 | D27 | D24 | D23 + ``Serial2`` | D9 | D8 | D7 | D11 | D10 + ``Serial3`` | D1 | D0 | D31 | D30 | D29 .. _maple-mini-adc-bank: diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 90be01e..e3cdaec 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -220,37 +220,37 @@ The following table shows which pins connect to which :ref:`EXTI lines * - EXTI Line - Pins * - EXTI0 - - 2, 15, 27 + - D2, D15, D27 * - EXTI1 - - 3, 16, 28 + - D3, D16, D28 * - EXTI2 - - 1, 17, 25 + - D1, D17, D25 * - EXTI3 - - 0, 18, 42 + - D0, D18, D42 * - EXTI4 - - 10, 19 + - D10, D19 * - EXTI5 - - 4, 13, 20 + - D4, D13, D20 * - EXTI6 - - 5, 12, 35 + - D5, D12, D35 * - EXTI7 - - 9, 11, 36 + - D9, D11, D36 * - EXTI8 - - 6, 14, 37 + - D6, D14, D37 * - EXTI9 - - 7, 25, 28 + - D7, D25, D28 * - EXTI10 - - 8, 26, 29 + - D8, D26, D29 * - EXTI11 - - 30 + - D30 * - EXTI12 - - 31 + - D31 * - EXTI13 - - 21, 32, 39 + - D21, D32, D39 * - EXTI14 - - 22, 33, 40 + - D22, D33, D40 * - EXTI15 - - 23, 34, 41 + - D23, D34, D41 .. _maple-ret6-usart-map: @@ -265,9 +265,9 @@ using the pins summarized in the following table: :header: Serial Port, TX, RX, CK, CTS, RTS :delim: | - ``Serial1`` | 7 | 8 | 6 | - | - - ``Serial2`` | 1 | 0 | 10 | 2 | 3 - ``Serial3`` | 29 | 30 | 31 | 32 | 33 + ``Serial1`` | D7 | D8 | D6 | | + ``Serial2`` | D1 | D0 | D10 | D2 | D3 + ``Serial3`` | D29 | D30 | D31 | D32 | D33 Unfortunately, :ref:`UART4 and UART5 aren't completely available `. diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 51bd4e2..90a1203 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -269,37 +269,37 @@ The following table shows which pins connect to which :ref:`EXTI lines * - EXTI Line - Pins * - EXTI0 - - 2, 15, 27 + - D2, D15, D27 * - EXTI1 - - 3, 16, 28 + - D3, D16, D28 * - EXTI2 - - 1, 17, 25 + - D1, D17, D25 * - EXTI3 - - 0, 18, 42 + - D0, D18, D42 * - EXTI4 - - 10, 19 + - D10, D19 * - EXTI5 - - 4, 13, 20 + - D4, D13, D20 * - EXTI6 - - 5, 12, 35 + - D5, D12, D35 * - EXTI7 - - 9, 11, 36 + - D9, D11, D36 * - EXTI8 - - 6, 14, 37 + - D6, D14, D37 * - EXTI9 - - 7, 25, 28 + - D7, D25, D28 * - EXTI10 - - 8, 26, 29 + - D8, D26, D29 * - EXTI11 - - 30 + - D30 * - EXTI12 - - 31 + - D31 * - EXTI13 - - 21, 32, 39 + - D21, D32, D39 * - EXTI14 - - 22, 33, 40 + - D22, D33, D40 * - EXTI15 - - 23, 34, 41 + - D23, D34, D41 .. _maple-usart-map: @@ -314,9 +314,9 @@ summarized in the following table: :header: Serial Port, TX, RX, CK, CTS, RTS :delim: | - ``Serial1`` | 7 | 8 | 6 | - | - - ``Serial2`` | 1 | 0 | 10 | 2 | 3 - ``Serial3`` | 29 | 30 | 31 | 32 | 33 + ``Serial1`` | D7 | D8 | D6 | | + ``Serial2`` | D1 | D0 | D10 | D2 | D3 + ``Serial3`` | D29 | D30 | D31 | D32 | D33 .. _maple-adc-bank: -- cgit v1.2.3 From 8b56515e76646ec1f8e87c59cdab5f2af9abe1a7 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 7 Sep 2011 22:56:28 -0400 Subject: hardware: Cosmetics. --- source/hardware/maple-mini.rst | 4 ++-- source/hardware/maple-ret6.rst | 2 +- source/hardware/maple.rst | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index f773973..986ab4b 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -236,8 +236,8 @@ USART Pin Map ^^^^^^^^^^^^^ The Maple Mini has three serial ports (also known as :ref:`USARTs -`). They communicate using the pins summarized in the following -table: +`). They communicate using the pins given in the following +table. .. csv-table:: :header: Serial Port, TX, RX, CK, CTS, RTS diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index e3cdaec..725c064 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -259,7 +259,7 @@ USART Pin Map The Maple RET6 Edition has three serial ports whose pins are broken out to headers (also known as :ref:`USARTs `). They communicate -using the pins summarized in the following table: +using the pins given in the following table. .. csv-table:: :header: Serial Port, TX, RX, CK, CTS, RTS diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 90a1203..610fdfc 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -306,9 +306,9 @@ The following table shows which pins connect to which :ref:`EXTI lines USART Pin Map ^^^^^^^^^^^^^ -The Maple has three serial ports (also known as USARTs): ``Serial1``, -``Serial2``, and ``Serial3``. They communicate using the pins -summarized in the following table: +The Maple has three serial ports (also known as :ref:`USARTs +`): ``Serial1``, ``Serial2``, and ``Serial3``. They communicate +using the pins given in the following table. .. csv-table:: :header: Serial Port, TX, RX, CK, CTS, RTS -- cgit v1.2.3 From 0c1619918435d0934faf7b155c56fdfa53fe9605 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 00:54:44 -0400 Subject: Add better refs to some systick.h functions. --- source/libmaple/api/systick.rst | 8 ++------ source/timers.rst | 4 ++-- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/source/libmaple/api/systick.rst b/source/libmaple/api/systick.rst index 8dab417..45b6d63 100644 --- a/source/libmaple/api/systick.rst +++ b/source/libmaple/api/systick.rst @@ -1,11 +1,5 @@ .. highlight:: c -.. FIXME [0.0.10] move these to the right places: - -.. _libmaple-systick_disable: - -.. _libmaple-systick_resume: - .. _libmaple-systick: ``systick.h`` @@ -30,7 +24,9 @@ Functions --------- .. doxygenfunction:: systick_init +.. _libmaple-systick-enable: .. doxygenfunction:: systick_enable +.. _libmaple-systick-disable: .. doxygenfunction:: systick_disable .. doxygenfunction:: systick_uptime .. doxygenfunction:: systick_get_count diff --git a/source/timers.rst b/source/timers.rst index b6c0886..ce33f7f 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -118,7 +118,7 @@ periodic or delayed events. Its separate timer does not conflict with any other peripherals, but the associated 1 kHz interrupt can jitter the general purpose timer interrupts. The SysTick peripheral can be disabled by calling :ref:`systick_disable() -`, and re-enabled using -:ref:`systick_resume() `. However, be aware +`, and re-enabled using +:ref:`systick_enable() `. However, be aware that calling ``systick_disable()`` will stop the values coming from :ref:`lang-micros` and :ref:`lang-millis` from increasing. -- cgit v1.2.3 From b4c84cf52b1ee99b70d407bc5185dbdbbf9345a5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 00:55:36 -0400 Subject: [libmaple] dma.rst: Cull a finished TODO. This was figured out a while ago. --- source/libmaple/api/dma.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/libmaple/api/dma.rst b/source/libmaple/api/dma.rst index d4e1683..a9893e2 100644 --- a/source/libmaple/api/dma.rst +++ b/source/libmaple/api/dma.rst @@ -31,8 +31,6 @@ Devices Functions --------- -.. TODO [0.0.11?] figure out the dma_attach_interrupt weirdness - .. doxygenfunction:: dma_init .. doxygenfunction:: dma_setup_transfer .. doxygenfunction:: dma_set_num_transfers -- cgit v1.2.3 From 73389e3e95e6c6d50521531a0d1dba85460af93b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 00:57:04 -0400 Subject: maple-ide-install: Move an "0.0.12" milestone to "RELEASE". We have to do this every time we cut a release branch. The non-numeric milestone RELEASE will now start to be used for any FIXME or TODO that needs doing when the release branch gets cut for a versioned documentation build. --- source/maple-ide-install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 67171dd..0a083f7 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -17,7 +17,7 @@ us directly`_\ ! Download -------- -.. FIXME [0.0.12] Update this for the release. +.. FIXME [RELEASE] Update this for the release. This documentation was built from a development version of libmaple. See the formally released `LeafLabs documentation -- cgit v1.2.3 From dfceabe3a3a83f9c734670147f2db169ec4504e5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 00:58:53 -0400 Subject: index: Adjust TODO milestone. --- source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index.rst b/source/index.rst index f24262d..3c6f520 100644 --- a/source/index.rst +++ b/source/index.rst @@ -74,5 +74,5 @@ Have fun! hardware/maple-mini.rst hardware/maple-native-beta.rst -.. TODO write/include upon Native release +.. TODO [Maple Native] write/include upon finished Native release .. hardware/maple-native.rst -- cgit v1.2.3 From 3b022b71b701a9b78d56dd732586b9840ce69cdc Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 01:30:14 -0400 Subject: detachinterrupt.rst: Comment typo. --- source/lang/api/detachinterrupt.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/lang/api/detachinterrupt.rst b/source/lang/api/detachinterrupt.rst index 82ce974..6eb8e53 100644 --- a/source/lang/api/detachinterrupt.rst +++ b/source/lang/api/detachinterrupt.rst @@ -9,7 +9,7 @@ Used to disable an interrupt specified with Library Documentation --------------------- -.. FIXME [Breathe] once we can get the correct detachInterupt(), +.. FIXME [Breathe] once we can get the correct detachInterrupt(), .. replace with doxygenfunction. .. cpp:function:: void detachInterrupt(uint8 pin) -- cgit v1.2.3 From 6e5d59170853b5ec360ea2de1974b3cbcda3b4ad Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 01:33:33 -0400 Subject: conf.py: Add RELEASE milestone. --- source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 841eadc..7380f8e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -59,7 +59,7 @@ copyright = u'2010, 2011, LeafLabs, LLC' # The short X.Y version. version = '0.0' # The full version, including alpha/beta/rc tags. -# FIXME [0.0.12] update this for the release +# FIXME [RELEASE] update this for the release release = 'custom-build' # The language for content autogenerated by Sphinx. Refer to documentation -- cgit v1.2.3 From 64a89ce0c4dc6adf5fc9dc77f3036e6026d84e29 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 01:46:34 -0400 Subject: Add links to Native Beta pin maps from peripheral pages. --- source/adc.rst | 5 +---- source/external-interrupts.rst | 3 +-- source/timers.rst | 3 +-- source/usart.rst | 3 +-- 4 files changed, 4 insertions(+), 10 deletions(-) diff --git a/source/adc.rst b/source/adc.rst index 451e7f0..f510d2b 100644 --- a/source/adc.rst +++ b/source/adc.rst @@ -57,13 +57,10 @@ additional functionality, cost, and package size. More information on these isolated pins is available in each board's hardware documentation: -.. FIXME [0.0.12, Maple Native] - * :ref:`Maple ` * :ref:`Maple RET6 Edition ` * :ref:`Maple Mini ` - -.. :ref:`Maple Native ` +* :ref:`Maple Native Beta ` That said, there are a number of more general things you can do to try to get good readings. If your input voltage changes relatively diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst index 1ab65be..2cf9aea 100644 --- a/source/external-interrupts.rst +++ b/source/external-interrupts.rst @@ -34,14 +34,13 @@ because every pin on the Maple connects to what is called an *EXTI line*, and only one pin per EXTI line can be used for external interrupts at a time [#fextisports]_. -.. TODO [0.0.12] Maple Native links - The EXTI Line Pin Map for your board lists which pins connect to which EXTI lines: * :ref:`Maple ` * :ref:`Maple RET6 Edition ` * :ref:`Maple Mini ` +* :ref:`Maple Native Beta ` Function Reference ------------------ diff --git a/source/timers.rst b/source/timers.rst index ce33f7f..0fa0976 100644 --- a/source/timers.rst +++ b/source/timers.rst @@ -82,11 +82,10 @@ you want to use both timer interrupts and PWM in the same program. Refer to your board's timer pin map to match up timer channels and pin numbers: -.. TODO [0.0.12] Native links - * :ref:`Maple ` * :ref:`Maple RET6 Edition ` * :ref:`Maple Mini ` +* :ref:`Maple Native Beta ` Overhead ^^^^^^^^ diff --git a/source/usart.rst b/source/usart.rst index fa9c55c..4807431 100644 --- a/source/usart.rst +++ b/source/usart.rst @@ -22,8 +22,6 @@ pin, and your Maple board's ground to your device's ground. .. warning:: Don't connect these pins directly to an RS232 serial port; they operate at +/- 12V and can damage your board. -.. TODO [0.0.12/Maple Native] UART4 and UART5, Native links - Each LeafLabs board has at least 3 separate USART devices. In the most simple use case, the RX and TX pins are used to send data at a predetermined speed (or *baud rate*). Their usage is documented in @@ -36,6 +34,7 @@ available here: * :ref:`Maple ` * :ref:`Maple RET6 Edition ` * :ref:`Maple Mini ` +* :ref:`Maple Native Beta ` If you use a particular serial port, you cannot also use its communication pins for other purposes at the same time. -- cgit v1.2.3 From e654bf72d5c1f20e575c6d3ebb3d78fe8dd82ed2 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 01:46:52 -0400 Subject: maple-quickstart: Add Native note about charge selection jumper. --- source/maple-quickstart.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 976eecf..0cfaa7d 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -73,16 +73,15 @@ window, and then a confirmation message will appear: Upload that program! -------------------- -.. FIXME [Maple Native: add note about power select jumper] - Now it's time to plug in your Maple. Use a USB Mini-B cable (mini, not micro). On the Maple, make sure that the :ref:`power source jumper -` is on the USB header first. We ship Maples with the -power source jumper configured that way, so you shouldn't have to do -anything. For reference, it should look like this (don't worry if a -jumper is hanging half off of the CHRG header): +` is on the USB header first (the same goes for Maple +Native). We ship Maples with the power source jumper configured that +way, so you shouldn't have to do anything. For reference, it should +look like this (don't worry if a jumper is hanging half off of the +CHRG header): .. image:: /_static/img/plugged-in-maple.png :align: center -- cgit v1.2.3 From 2f6d6831bcd187e777cba35aac0d2de391442024 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 01:47:13 -0400 Subject: hardwarespi: Note about disable JTAG+SW when using SPI3. --- source/lang/api/hardwarespi.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst index f90fc07..a44a65f 100644 --- a/source/lang/api/hardwarespi.rst +++ b/source/lang/api/hardwarespi.rst @@ -15,9 +15,6 @@ the :ref:`SPI reference `. Getting Started --------------- -.. TODO [0.1.0] Add a note about calling disableDebugPorts() when -.. using SPI3 on Maple Native - In order to get started, you'll first need to define a ``HardwareSPI`` variable, which you'll use to control the SPI port. Do this by putting the line "``HardwareSPI spi(number);``" with your variables, @@ -47,6 +44,10 @@ function (an example is given below). .. doxygenfunction:: HardwareSPI::begin +.. note:: If you are using SPI port 3 (on a board that supports it; + not all do); you'll need to call :ref:`lang-disabledebugports` + before calling ``begin()``. + The speed at which the SPI port communicates is configured using a ``SPIFrequency`` value: -- cgit v1.2.3 From 6292ecc23f7bc9c1fe73dae1d49515b34a1712a2 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 01:47:29 -0400 Subject: maple-ret6: Cosmetics. --- source/hardware/maple-ret6.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index 725c064..d5bf049 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -14,9 +14,9 @@ the hands of Maple developers. .. contents:: Contents :local: -.. TODO [dma.rst] Ref to dma.rst in sequel instead of libmaple-dma -.. TODO [dac.rst] Ref to dac.rst in sequel instead of libmaple-dac -.. TODO [nvic.rst] Ref to nvic.rst in sequel +.. TODO [dma.rst] Ref to source/dma.rst in sequel instead of libmaple-dma +.. TODO [dac.rst] Ref to source/dac.rst in sequel instead of libmaple-dac +.. TODO [nvic.rst] Ref to source/nvic.rst in sequel Technical Specifications ------------------------ -- cgit v1.2.3 From 1ea03ae822236e1180997eb8e4660d8f53ccd084 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 01:48:47 -0400 Subject: Update README. Add information on how the documentation is maintained, with specific notes on the important use cases (adding a new board, versioned docs build and their maintenance). --- README | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 196 insertions(+), 1 deletion(-) diff --git a/README b/README index 15c1006..d757853 100644 --- a/README +++ b/README @@ -23,7 +23,8 @@ documentation. Older versions are available as well: http://static.leaflabs.com/pub/leaflabs/maple-docs/ -This file contains instructions for generating the HTML files. +This file contains instructions for generating the HTML files. It +also contains guidelines for the documentation's maintainers. About the Documentation ----------------------- @@ -98,6 +99,10 @@ Doxygen XML output, then you can generate the HTML documentation. On Windows, use the batch file make.bat instead. + As of 8 September 2011, building the docs generates a bunch of + errors/warnings. Most of these are spurious and appear to be + Breathe's fault. C'est la vie. + Reading and Modifying the Documentation --------------------------------------- @@ -121,3 +126,193 @@ All of the documentation which isn't pulled out of source code comments lives in source/. The directory source/_static/ is for static content (like style sheets); source/_templates/ is meant to contain Sphinx templates. + +The remaining sections describe what to do under various circumstances +when modifying or building the docs. + +Adding a New Board +------------------ + +Adding documentation for a new board is not just a matter of shoving a +file for it into source/hardware/! + +- Various places in the docs link to particular kinds of pin maps for + each board. When you add a new board, you must update these as + well. Here's the list; please keep it current (files are relative + to the source/ directory): + + * external-interrupts.rst: EXTI line pin maps + * timers.rst: timer pin maps + * adc.rst: low-noise ADC banks + * usart.rst: USART pin maps + +- The quickstart document may not explain how to use the new board. + If the board is different enough, a new, special-purpose quickstart + may need to be written for it. Therefore, read the quickstart in + its entirety and update it appropriately. + + Take this step seriously. The quickstart is the first thing users + read when starting out, and first impressions matter. + +Building Documentation for a Release +------------------------------------ + +This is the procedure to follow when building the documentation for a +versioned release (as such, it's mostly intended for LeafLabs people). + +Read the following "Background" section if you've never done this +before (or haven't done it in a while; things change). Then do the +steps in the "Preparation" and "Cutting the Release" sections that +follow it. + +If you're bugfixing the docs for a release that's already been +shipped, skip to "Maintaining a Release", below. + + ~~~~~~~~~~ + Background + ~~~~~~~~~~ + +As a lightweight form of issue tracking, the documentation sources are +sprinkled (not to say "littered") with comments that begin with FIXME +or TODO, optionally followed by [milestone]. + +Here's a hypothetical example: + + .. TODO [1.4.0] Replace this section; new API is incompatible with 1.3.7 + +This means you should replace the docs section following the comment +before you build the HTML for version 1.4.0. + +Here's a command line you can use on OS X and Linux to list the TODOs +in the documentation sources (run it from the same directory as this +README): + + $ find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)' + +You can use the following to temporarily alias the above mouthful to +'todos': + + $ alias todos="find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)'" + +Then you can just run + + $ todos + +to measure the joy that awaits you. + +Windows users: I'm not sure what the equivalent of grep is on your +system. If you're using Git, I presume you've got a Bash shell +available to you due to msysgit; try running the above commands there. + +BE ADVISED: that only finds the comments embedded within .rst files. +You also need to check for these in source/conf.py; there may be +others. If you have ack (which might be called "ack-grep" on your +system) installed, you can instead use + + $ ack --type-set rst=.rst --type-set txt=.txt --ignore-dir=build '(FIXME|TODO)' + +to get the same output, but for all the file types we care about. + + ~~~~~~~~~~~ + Preparation + ~~~~~~~~~~~ + +- FINISH THE FIXMEs/TODOs FOR THE CURRENT RELEASE! + + You may violate assumptions made elsewhere in the documentation if + you don't. This can lead to incoherent or incorrect documentation, + which is usually worse than none at all. + + If the release you're building is vA.B.C, you can see the relevant + TODOs with: + + $ todos | grep A\.B\.C + + If you find that you really can't finish the TODO, you should bump + the version number in the comment. Don't do this out of laziness. + Seriously, don't. We may have made promises to the users about what + would happen when, and you might be breaking them. + +- Pick the low-hanging fruit on any other FIXMEs/TODOs. + +- Ask Git to tell you what's happened since the most recent libmaple + release, and make sure that any major, potentially + backwards-incompatible, etc. changes are appropriately documented. + + You can use three dots ("...") between the git tags for those + releases in concert with "git log --oneline" to do this. + + For instance, from the libmaple repository, you can use the + following to tell you what happened in between 0.0.9 and 0.0.10: + + $ git log --oneline 0.0.9...0.0.10 + + As an example of what the output might cause you to do, consider the + following line (which appears in the output for 0.0.9...0.0.10): + + 4941335 Adding rcc_dev_clk(), an accessor for a peripheral's clock line. + + Did the author of that commit (or some other interested party) + remember to pull in the documentation for rcc_dev_clk() into the + libmaple API page for rcc.h? Go check! + +- Do something similar for Maple IDE. The IDE changes a lot more + slowly, so there should be less to do. + + ~~~~~~~~~~~~~~~~~~~ + Cutting the Release + ~~~~~~~~~~~~~~~~~~~ + +- Make a release branch in Git. For release A.B.C, call it + vA.B.C-maintenance. You spell that + + $ git checkout -b vA.B.C-maintenance + + DON'T MAKE A TAG. There are inevitably mistakes in the docs, some + of which will be noticed and corrected, making a fixed tag useless. + When you correct the errors, you'll need to update this branch, + possibly also cherry-picking or otherwise adding into master. See + "Maintaining the Release", below. + +- Do all the TODOs which must happen for _every_ release. (These are + distinct from the ones that must happen for some _particular_ + release). You can find most of these with + + $ todos | grep RELEASE + + However, you'll also need to check source/conf.py, as e.g. a + release's configuration file needs to have a version entered into + it. + + Don't forget to commit your changes. + +- Run "$ make mrproper" from the libmaple directory, and "$ make + clean" from this directory, in order to wipe out old docs. + +- Finally, you can actually build the docs. "$ make doxygen" from + libmaple followed by "$ make html" from here. The sources you want + will be in build/html. Wooo! You're done! Distribute the results + appropriately (e.g. by bundling them with the IDE release). + + Don't forget to push the release branch to the leaflabs-docs repo on + GitHub. + +Maintaining a Release +--------------------- + +So a released version's documentation contains unforgivable lies, huh? +It needs to be updated RIGHT AWAY, you say? Here's what you do: + +- Check out the release branch for the version of the docs you care + about (see "Cutting the Release", above). + +- Make your changes. + +- Rebuild the docs (see the last step in "Cutting the Release"). + +- If your changes need to happen on the master branch, make them + appropriately. + +- Push your fixes to GitHub. + +- Distribute the updated docs. -- cgit v1.2.3 From 270143b6f24b3376db042c12bbfec2ae8814a3f5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 8 Sep 2011 02:16:38 -0400 Subject: Minor README correction. --- README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README b/README index d757853..a4ec452 100644 --- a/README +++ b/README @@ -308,7 +308,7 @@ It needs to be updated RIGHT AWAY, you say? Here's what you do: - Make your changes. -- Rebuild the docs (see the last step in "Cutting the Release"). +- Rebuild the docs (see the last two steps in "Cutting the Release"). - If your changes need to happen on the master branch, make them appropriately. -- cgit v1.2.3 From 1f0ba57e33b0c3ad16fb9fa0709e339b45b69eb5 Mon Sep 17 00:00:00 2001 From: Jessica Barber Date: Thu, 8 Sep 2011 11:00:16 -0700 Subject: Fixed TODOs in "ADC Pins", "GPIO Info" section --- source/hardware/maple-native-beta.rst | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst index 8b1dc45..eac78f8 100644 --- a/source/hardware/maple-native-beta.rst +++ b/source/hardware/maple-native-beta.rst @@ -102,15 +102,15 @@ it. .. _maple-native-b-fsmc: .. FIXME [0.0.12] Add note on Native "use SRAM" vs. "no SRAM" builds -.. -.. TODO [0.0.12] Specify which pins are safe, and which aren't Many of the pins on the right header (pins ``D56`` through ``D100``, -the header is labeled "FSMC" on the silkscreen) are connected to -:ref:`FSMC ` lines. Using these pins as GPIOs may render the -memory chip useless, which can cause your program to crash. For this +the header is labeled :ref:`"FSMC" ` on the silkscreen) are +connected to the SRAM chip. Using these pins as GPIOs may render the +memory chip useless, which can cause your program to crash. For this reason, we don't recommend that you use these pins unless you know -what you are doing. +what you are doing. The following pins on the right header are not +connected to the SRAM and may be used with impunity: ``D57``, ``D60``, +``D63``, ``D66``, ``D69``, ``D72``, ``D75``, ``D80``, ``D83``. .. _maple-native-b-jtag: @@ -431,16 +431,19 @@ These are given in the following table. Low-Noise ADC Pins ^^^^^^^^^^^^^^^^^^ -.. TODO [0.0.12] finish this; ask Jess for help and confirmation +There are fifteen pins at the bottom right of the board (``D41`` — +``D55``) that generally offer lower-noise ADC performance than other +pins on the board. If you're concerned about getting good ADC +readings, we recommend using one of these pins to take your +measurements. Maple Native has an electrically isolated analog power plane with its -own regulator, and a geometrically isolated ground plane, - -Analog input pins D41 — D55 are laid out to correspond with these -analog planes, and our measurements indicate that they generally ofer -low noise ADC performance. However, analog performance may vary -depending upon the activity of other GPIOs. In particular, using PWM -on any of pins D46 — D51, D54, and D55 may cause digital noise. +own regulator, and a geometrically isolated ground plane. Analog input +pins D41 — D55 are laid out to correspond with these analog planes, +and our measurements indicate that they generally ofer low noise ADC +performance. However, analog performance may vary depending upon the +activity of other GPIOs. In particular, using PWM on any of pins +``D46`` — ``D51``, ``D54``, and ``D55`` may cause digital noise. Consult the :ref:`Maple Native beta hardware design files ` for more details. -- cgit v1.2.3 From 34f616aaa0e8dadb4adda4341e38e8edb1b41c32 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 9 Sep 2011 15:00:33 -0400 Subject: maple-native-beta: Knock out TODO. --- source/hardware/maple-native-beta.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst index eac78f8..314092a 100644 --- a/source/hardware/maple-native-beta.rst +++ b/source/hardware/maple-native-beta.rst @@ -15,8 +15,6 @@ change slightly between now and the final Maple Native release. Technical Specifications ------------------------ -.. TODO [0.0.12] Verify recommended input voltage - * MCU: `STM32F103ZET6 `_, a 32-bit ARM Cortex M3 microprocessor. * Clock Speed: **72 MHz** -- cgit v1.2.3 From a7730c06101abc1df43099010cbc4f16fd674b20 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 9 Sep 2011 15:01:48 -0400 Subject: bootloader: Remove Maple-specific values. --- source/bootloader.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index d3a1abb..1a0fa6d 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -649,15 +649,13 @@ could use another Maple, an Arduino, etc. -- anything that allows your computer to communicate with the Maple you want to reprogram over a serial interface. -.. FIXME [0.0.12, Maple-specific values] - If you do use an FTDI breakout board, first make sure your Maple is disconnected from an external power source, be it battery, USB, or barrel jack. Then, connect the FTDI board's TX pin to ``Serial1``\ 's -RX pin (pin 8 on Maple), FTDI RX to ``Serial1`` TX (pin 7 on Maple), -FTDI ground to ground (labeled GND), and its 3.3V pin to Vin. On -Maple Mini, you will also need to tie BOOT1 (pin 2) to ground. You -can use the silkscreen for help locating these pins on other boards. +RX pin (labeled "RX1" on the silkscreen), FTDI RX to ``Serial1`` TX +(labeled "TX1"), FTDI ground to ground (labeled GND), and its 3.3V pin +to Vin. On Maple Mini, you will also need to tie BOOT1 (pin 2) to +ground. More information on ``Serial1`` is available :ref:`here `. -- cgit v1.2.3 From 9ece5222028df6f341e61b0bd8b72b3438a90cda Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 9 Sep 2011 15:13:57 -0400 Subject: maple-native-beta: Fix some board-specific values. --- source/hardware/maple-native-beta.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst index 314092a..64809bc 100644 --- a/source/hardware/maple-native-beta.rst +++ b/source/hardware/maple-native-beta.rst @@ -450,8 +450,6 @@ Consult the :ref:`Maple Native beta hardware design files Board-Specific Values --------------------- -.. TODO [0.0.12] get pwm, used pins - This section lists the Maple Native's :ref:`board-specific values `. @@ -459,14 +457,19 @@ This section lists the Maple Native's :ref:`board-specific values - ``BOARD_BUTTON_PIN``: 6 - ``BOARD_LED_PIN``: 22 - ``BOARD_NR_GPIO_PINS``: 106 -- ``BOARD_NR_PWM_PINS``: -- ``boardPWMPins``: +- ``BOARD_NR_PWM_PINS``: 18 +- ``boardPWMPins``: 13, 14, 15, 16, 23, 24, 25, 26, 38, 39, 46, 47, + 48, 49, 50, 51, 54, 55 - ``BOARD_NR_ADC_PINS``: 21 - ``boardADCPins``: 7, 8, 9, 10, 11, 12, 41, 42, 43, 44, 45, 46, 47, - 48, 49, 50, 51, 52, 53, 54, 55 -- ``BOARD_NR_USED_PINS``: -- ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN`` -- ``BOARD_NR_USARTS``: + 48, 49, 50, 51, 52, 53, 54, 55 +- ``BOARD_NR_USED_PINS``: 43 +- ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN``, + ``BOARD_JTMS_SWDIO_PIN``, ``BOARD_JTCK_SWCLK_PIN``, + ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``, ``BOARD_NJTRST_PIN``, and + all pins on FSMC header except those mentioned :ref:`above + `. +- ``BOARD_NR_USARTS``: 5 - ``BOARD_USART1_TX_PIN``: 24 - ``BOARD_USART1_RX_PIN``: 25 - ``BOARD_USART2_TX_PIN``: 50 @@ -486,6 +489,10 @@ This section lists the Maple Native's :ref:`board-specific values - ``BOARD_SPI2_MOSI_PIN``: 5 - ``BOARD_SPI2_MISO_PIN``: 4 - ``BOARD_SPI2_SCK_PIN``: 3 +- ``BOARD_SPI3_NSS_PIN``: 103 (on :ref:`JTAG header `) +- ``BOARD_SPI3_MOSI_PIN``: 37 +- ``BOARD_SPI3_MISO_PIN``: 105 (JTAG header) +- ``BOARD_SPI3_SCK_PIN``: 104 (JTAG header) - ``BOARD_JTMS_SWDIO_PIN``: :ref:`103 ` - ``BOARD_JTCK_SWCLK_PIN``: 102 - ``BOARD_JTDI_PIN``: 103 -- cgit v1.2.3 From 7033cd042aa48d1b9965ccb2065305c22bae8cc5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 9 Sep 2011 15:25:50 -0400 Subject: maple-native-beta: Fix page ref target. --- source/hardware/maple-native-beta.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst index 64809bc..1447db1 100644 --- a/source/hardware/maple-native-beta.rst +++ b/source/hardware/maple-native-beta.rst @@ -1,6 +1,6 @@ .. highlight:: sh -.. _maple-native: +.. _maple-native-b: Maple Native β ============== -- cgit v1.2.3 From 242c4d321604865f46abf1df30014a2718722023 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 9 Sep 2011 15:26:49 -0400 Subject: index: Add fsmc.rst. --- source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/index.rst b/source/index.rst index 3c6f520..e79588a 100644 --- a/source/index.rst +++ b/source/index.rst @@ -52,6 +52,7 @@ Have fun! adc external-interrupts + fsmc gpio i2c jtag -- cgit v1.2.3 From 2f4b336dd3ca8e8642a2405a87a19510caeba93c Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 9 Sep 2011 15:27:10 -0400 Subject: gpio: Add ref to Native Beta master pin map. --- README | 1 + source/gpio.rst | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README b/README index a4ec452..87e8bf1 100644 --- a/README +++ b/README @@ -145,6 +145,7 @@ file for it into source/hardware/! * timers.rst: timer pin maps * adc.rst: low-noise ADC banks * usart.rst: USART pin maps + * gpio.rst: master pin maps - The quickstart document may not explain how to use the new board. If the board is different enough, a new, special-purpose quickstart diff --git a/source/gpio.rst b/source/gpio.rst index af1de20..86f678f 100644 --- a/source/gpio.rst +++ b/source/gpio.rst @@ -69,11 +69,10 @@ GPIO port and bit for each pin number. The GPIO documentation for your board includes its pin map, which also lists the other peripherals by pin number: -.. TODO [0.0.12] Native link - * :ref:`Maple ` * :ref:`Maple RET6 Edition ` * :ref:`Maple Mini ` +* :ref:`Maple Native (Beta) ` .. * :ref:`Maple Native ` -- cgit v1.2.3 From 7f88212718f11b37e8d01fbd957c2dfa36392357 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 13 Sep 2011 04:49:26 -0400 Subject: maple-native-beta: Punt a TODO. Those builds aren't going to happen for 0.0.12. Deal with it. --- source/hardware/maple-native-beta.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst index 1447db1..e7c41d3 100644 --- a/source/hardware/maple-native-beta.rst +++ b/source/hardware/maple-native-beta.rst @@ -99,8 +99,6 @@ it. .. _maple-native-b-fsmc: -.. FIXME [0.0.12] Add note on Native "use SRAM" vs. "no SRAM" builds - Many of the pins on the right header (pins ``D56`` through ``D100``, the header is labeled :ref:`"FSMC" ` on the silkscreen) are connected to the SRAM chip. Using these pins as GPIOs may render the -- cgit v1.2.3 From 0b8f9396c9eff65d6fa36cc56259bf54f16a9443 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 13 Sep 2011 05:18:48 -0400 Subject: fsmc: Half-ass job to get the docs done. --- source/fsmc.rst | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/source/fsmc.rst b/source/fsmc.rst index dfd4916..c8f0125 100644 --- a/source/fsmc.rst +++ b/source/fsmc.rst @@ -4,11 +4,30 @@ FSMC ==== The Flexible Static Memory Controller (FSMC) is a peripheral which an -be configured to control a variety of external memory chips. For -example, it is used on the Maple Native to control the built-in SRAM -chip. - -.. TODO [0.0.12] Add info on: -.. -.. - Address, data, chip-select etc. pins -.. - Memory bank organization +be configured to control a variety of external memory chips. + +Normally, any variables in your program will be allocated space in RAM +(notable exceptions are variables marked with ``const`` or +:ref:`__FLASH__ `). Without the FSMC, this +space is limited to the amount that comes built-in to the chip's +*internal* SRAM. + +The addition of the FSMC peripheral allows addtional memory to be +used. For example, it is used on the Maple Native to interface with +the board's built-in external SRAM chip. However, this extra memory +comes at a cost: the FSMC uses a fairly large number of GPIOs. + +The FSMC peripheral is currently only available on the Maple Native. +On that board, we have broken out a wide variety of the FSMC lines, so +that experienced users can add additional external memory chips to +suit their own applications' purposes. + +.. TODO Find some tutorials on SRAM or write one on FSMC, specifically +.. ones that cover: address, data, chip-select etc. pins, memory bank +.. organization + +Recommended Reading +------------------- + +- Wikipedia article on `SRAM `_ +- :ref:`ST RM0008 ` chapter on FSMC. -- cgit v1.2.3 From 06e210a109333edc5c5deb8df52b28f6a23ff075 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 13 Sep 2011 06:05:23 -0400 Subject: Add copy-to-ide. Until the violence stops. --- copy-to-ide | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100755 copy-to-ide diff --git a/copy-to-ide b/copy-to-ide new file mode 100755 index 0000000..6cd4bdd --- /dev/null +++ b/copy-to-ide @@ -0,0 +1,9 @@ +#!/bin/sh + +IDE_DIRECTORY=$1 + +REFERENCE=$IDE_DIRECTORY/build/shared/reference + +echo copying built docs... +cp -R build/html/* $REFERENCE +echo done -- cgit v1.2.3 From ea004e377421d6b9142ef1a8a3ba0193c2888918 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 20 Sep 2011 18:19:34 -0400 Subject: faq: Fix question on dynamic memory. As of libmaple v0.0.12, dynamic memory is officially supported. Fix the FAQ on malloc() etc. not working to reflect this. --- source/faq.rst | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/source/faq.rst b/source/faq.rst index 4b5b605..da67370 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -21,11 +21,25 @@ of its headers. .. _faq-dynamic-memory: -Why don't ``malloc()``/``new`` work? ------------------------------------- - -Due to our newlib configuration, dynamic memory allocation is -currently not available. +How can I use ``malloc()``/``new``? +----------------------------------- + +For ``malloc()``, just ``#include ``, and everything should +work fine. Be careful, though! This isn't like C programming on a +PC. You're on the bare metal, and probably shouldn't be using dynamic +memory unless you know what you're doing. + +``new`` should work out of the box (the warning about knowing what +you're doing applies here as well). If you find that ``new`` (or +``new[]``, ``delete``, etc.) is broken in some way, that's a bug; +please let us know in the `forum`_. + +Some information on the heap: on boards with an external SRAM chip +(like Maple Native), the heap is located on external SRAM by default. +For other boards, the heap is located immediately after ``.bss``, and +grows towards the stack. (In all cases, statically allocated +variables and the stack are located on internal SRAM, for performance +reasons). .. _faq-flash-tables: -- cgit v1.2.3 From 8dbea21d6105f673a5227a01b8250927f255920b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 20 Sep 2011 19:06:59 -0400 Subject: index: Tweak introductory paragraph. Add a link to the FAQ; hopefully this will help cut down on support requests covered by these. Change the language to be a bit less Maple-centric. Other minor changes. --- source/index.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/index.rst b/source/index.rst index e79588a..e8f0277 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,17 +3,16 @@ LeafLabs Documentation Index ============================ -Welcome! This is the Maple documentation index. +Welcome to the LeafLabs documentation! -If you just bought a Maple board, you probably want to head to the +If you're setting up a board for the first time, try the :ref:`quickstart `. If you're having problems, -check out the :ref:`troubleshooting ` page. +check out the :ref:`troubleshooting ` and :ref:`FAQ +` pages. -If you can't find what you're looking for, try looking on our `wiki +If you can't find what you're looking for here, try the `LeafLabs wiki `_. -Have fun! - .. _index-usage: **Usage Guides:** -- cgit v1.2.3 From 316e94e79059e4f3683231f34ba3b085a1ced2fe Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 20 Sep 2011 22:20:53 -0400 Subject: faq: Added another link on fast I/O. --- source/faq.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/faq.rst b/source/faq.rst index da67370..0d26a48 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -106,4 +106,6 @@ squeeze a little extra out of your board. First, a `general summary try, with measurements of the speed you'll get. Next, a thread featuring a `detailed discussion on pin capability `_, with a focus on -writes. +writes. And finally, `another thread +`_ on the subject which +summarizes a variety of other threads on doing I/O quickly. -- cgit v1.2.3 From 1293fcd872d7257c25f9d4d76b2341bafe553672 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 20 Sep 2011 23:07:40 -0400 Subject: libmaple.rst: Add links to Wirish APIs. This is necessary now that we point to this page from the libmaple GitHub repo. --- source/libmaple.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/libmaple.rst b/source/libmaple.rst index 60bf814..b06e73e 100644 --- a/source/libmaple.rst +++ b/source/libmaple.rst @@ -20,7 +20,9 @@ C, which we call *libmaple proper* (in the `libmaple/ `_ directory of the source repository), and the Wiring-style C++ API written on top of it, called *Wirish* (in `wirish/ -`_). +`_; the +wirish APIs are :ref:`summarized here `, with an :ref:`index +here `). libmaple is bundled with the :ref:`Maple IDE `. However, we develop it separately, and :ref:`release it standalone -- cgit v1.2.3 From 9749a27b095c80b29a66b9007574b4a1106b132f Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 20 Sep 2011 23:13:19 -0400 Subject: contributing.rst: Add link to GitPhraseBook. --- source/libmaple/contributing.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/libmaple/contributing.rst b/source/libmaple/contributing.rst index aeaeacb..7492cdc 100644 --- a/source/libmaple/contributing.rst +++ b/source/libmaple/contributing.rst @@ -123,6 +123,10 @@ resources: marketing department, this is a very good introductory article on basic Git concepts, and a solid primer on Git's internals. +- `GitPhraseBook (openembedded.org) + `_: A + cookbook-style list of common Git problems and their solutions. + * `Understanding Git Conceptually `_: a good, introductory tutorial on Git's fundamental concepts. -- cgit v1.2.3 From d804e810e9538abbeecefbdd4a30cf1e5ddf0f35 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 20 Sep 2011 23:17:34 -0400 Subject: contributing.rst: Mention git commit -s. I guess we'll start doing this too, for consistency with what we ask of our users. Signed-off-by: Marti Bolivar --- source/libmaple/contributing.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/libmaple/contributing.rst b/source/libmaple/contributing.rst index 7492cdc..25c6c17 100644 --- a/source/libmaple/contributing.rst +++ b/source/libmaple/contributing.rst @@ -79,6 +79,10 @@ The steps to submit a pull request are as follows: ``Signed-off-by: John Smith `` + If you've configured Git to know your name and email, you can + instruct it to insert this line automatically by calling ``git + commit`` with the ``-s`` flag. + 4. `Submit a pull request `_ to the LeafLabs version of libmaple. -- cgit v1.2.3 From c8141282a408da76319a91f66341cf0a9cadc143 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 00:43:22 -0400 Subject: arm-gcc: Add note about incomplete syscall support. Add note referencing syscalls.c. This gives people a place to start looking if our newlib stubs don't do what they want. Signed-off-by: Marti Bolivar --- source/arm-gcc.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 129f5e6..4f9d825 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -67,6 +67,10 @@ link against `newlib `_, a C standard library intended for use with embedded applications. You are free to include of any of its headers. +Be advised, however, that a variety of syscalls may only be partially +implemented, if at all. See the :ref:`libmaple` file syscalls.c and +the newlib documentation for more details. + Switching from AVR-GCC ---------------------- -- cgit v1.2.3 From 02a3a119b768d6f303eaebd92de8175bfb5d67dd Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 01:12:28 -0400 Subject: coding-standard: Generify plea for editor configuration help. Signed-off-by: Marti Bolivar --- source/libmaple/coding-standard.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/libmaple/coding-standard.rst b/source/libmaple/coding-standard.rst index 079329b..9ed56cc 100644 --- a/source/libmaple/coding-standard.rst +++ b/source/libmaple/coding-standard.rst @@ -24,7 +24,7 @@ in Emacs (but not on Windows, where it would need to be named ``_dir_locals.el``, and no way, man). There's also some elisp scattered about this file which will provide you additional help. -Vim customizations to do the same thing would be nice! +Configuration for other editors (vim, etc.) would be nice! .. contents:: Contents :local: -- cgit v1.2.3 From 8e80eb006f1fa3925e816b231b8312cac1ef37bc Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 01:17:51 -0400 Subject: arm-gcc: Improve section :ref: names. Signed-off-by: Marti Bolivar --- source/arm-gcc.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 4f9d825..1d55d07 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -29,6 +29,8 @@ LeafLabs maintains `mirrors recent versions of the compiler, including versions for OS X, Win32, and 32-bit Linux. +.. _arm-gcc-compiler-flags: + Compiler Flags Used by libmaple ------------------------------- @@ -56,7 +58,7 @@ The following flags are among those passed to the assembler:: .. highlight:: cpp -.. _arm-gcc-avr-gcc: +.. _arm-gcc-libc: Using the C Standard Library ---------------------------- @@ -71,6 +73,8 @@ Be advised, however, that a variety of syscalls may only be partially implemented, if at all. See the :ref:`libmaple` file syscalls.c and the newlib documentation for more details. +.. _arm-gcc-avr-gcc: + Switching from AVR-GCC ---------------------- -- cgit v1.2.3 From 2b8c61b37780d8acc3ce120267a7d81566323457 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 01:19:16 -0400 Subject: faq: Improve atoi() FAQ. Add reference to strtol() to show we're hip to the times. Add link to arm-gcc section on libc for further reading. Signed-off-by: Marti Bolivar --- source/faq.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/source/faq.rst b/source/faq.rst index 0d26a48..6b32b48 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -11,13 +11,11 @@ .. _faq-atoi: -How can I use ``atoi()``? -------------------------- +How can I use ``atoi()``, ``strol()``, etc? +------------------------------------------- -The :ref:`CodeSourcery GCC compiler ` used to compile your -programs is configured to link against the `newlib -`_ C library, and allows the use of any -of its headers. +Just ``#include ``. See :ref:`arm-gcc-libc` for more +information on the C standard library. .. _faq-dynamic-memory: -- cgit v1.2.3 From 769b560c7e6e9f3ff789bc2832dbadadc09e0440 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 01:22:39 -0400 Subject: faq: Tweak atoi() entry. Remove redundancy in HTML output. Signed-off-by: Marti Bolivar --- source/faq.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/faq.rst b/source/faq.rst index 6b32b48..937eae8 100644 --- a/source/faq.rst +++ b/source/faq.rst @@ -11,11 +11,11 @@ .. _faq-atoi: -How can I use ``atoi()``, ``strol()``, etc? -------------------------------------------- +How can I use ``atoi()``, ``strol()``, etc.? +-------------------------------------------- Just ``#include ``. See :ref:`arm-gcc-libc` for more -information on the C standard library. +information. .. _faq-dynamic-memory: -- cgit v1.2.3 From 15dc9f9096660756a5d64ab63fe402f6aed3ef68 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 03:20:10 -0400 Subject: maple-quickstart: Updates and improvements. Tighten the timeline for updating the images. These are really showing their age. Replace all occurrences of "FLASH" in the running text with "Flash". Replace some usages of "Maple" with "board", to make it clear that the quickstart applies to all Maple line boards. However, don't replace all of these. Reinforcing the "Maple" name distinguishes this quickstart from future ones, e.g. Oak's. Regarding the LED: fix some of the language around the bootloader blinks, and point straight to the throb() troubleshooting item (instead of just the troubleshooting page). Move this paragraph to after the first program upload; I expect that's when users will be most curious about the blinking. (Hopefully, these changes will cut down on support requests about throbbing). Point at our Twitter account instead of asking for a leaflabs hashtag, since we actually maintain the Twitter account now. Other miscellaneous fixups and tweaks. Signed-off-by: Marti Bolivar --- source/maple-quickstart.rst | 78 +++++++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 38 deletions(-) diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 0cfaa7d..a4bc55a 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -6,7 +6,11 @@ Maple Quickstart Guide ======================== -.. TODO [0.1.0] Update the images; we've changed "to FLASH" -> "to Flash" +.. TODO [0.0.13]: Update the images; e.g., "to FLASH" is now "to Flash" +.. +.. Consider putting the images as a bundle somewhere under +.. static.leaflabs.com that gets downloaded and unpacked if they are +.. not present, but don't get crazy. You'll need a `Maple board `_, a `Mini-B USB cable `_, a @@ -39,22 +43,22 @@ From the File menu, select Examples > Digital > Blink: :align: center :alt: Click "Blink" -Next, select Tools > Board > "LeafLabs Maple ... to FLASH": +Next, select Tools > Board > "LeafLabs Maple ... to Flash", where +"..." depends on the board you're using. .. image:: /_static/img/blinky-to-flash.png :align: center - :alt: Upload to FLASH + :alt: Upload to Flash .. note:: - You have the option between RAM and FLASH programming: FLASH saves - the program into permanent memory so the program will be run every - time the Maple is reset, while RAM simply injects the compiled - program into the processor's memory. + You have the choice between Flash and RAM programming. Flash saves + the program into permanent Flash memory. RAM simply puts the + compiled program into the processor's built-in RAM. - Programming to RAM is faster to upload and a buggy program can be - wiped away with a simple reset, while FLASH memory is larger and is - the only option for permanently uploading a program. + Flash memory is larger, and is the only option for permanently + uploading a program. Programming to RAM is faster to upload, and a + buggy program can be wiped away with a simple reset. .. image:: /_static/img/verify_button.png :align: left @@ -90,7 +94,7 @@ CHRG header): .. note:: On OS X, a network interface dialog will pop up every time you plug in - the Maple. + the board. .. image:: /_static/img/osx-unconfigured-popup.png :align: center @@ -105,16 +109,10 @@ CHRG header): :scale: 75% :alt: Click "Apply" -The Maple should blink a short pattern on the blue status LED every -time it is plugged in, reset, or reprogrammed, just to let you know -it's there. If it ever starts throbbing in a slow, smooth pattern, -then you've got a problem: see the :ref:`troubleshooting -` page for help. - -If all systems are go, select the Maple's serial port in the Tools > -Serial Port menu. The Maple will appear as something like -:file:`COMx`, :file:`/dev/ttyACMx`, or :file:`/dev/tty.usbmodemxxxxx`, -depending on your platform, like so: +If all systems are go, select your board's serial port in the Tools > +Serial Port menu. It will appear as something like :file:`COMx`, +:file:`/dev/ttyACMx`, or :file:`/dev/tty.usbmodemxxxxx`, depending on +your platform, like so: Windows XP: @@ -134,21 +132,25 @@ OS X: :align: center :alt: Board type and serial port for the OS X -Then press the "Upload" button to upload your program to the -Maple. +Then press the "Upload" button to upload your program over USB. .. image:: /_static/img/upload-button.png :align: center :alt: Click the "Upload" button You should see some text and a progress bar flash by in the status -window of the IDE, then some blinky patterns on the Maple, and then a +window of the IDE, then some quick blinking patterns, followed a constant blinking on and off. Congratulations! You've successfully -uploaded your first program to the Maple. +uploaded your first program to your Maple. + +The built-in status LED should blink in a short pattern every time the +board is plugged in, reset, or reprogrammed. If it ever starts +throbbing in a smooth, even pattern, then you've got a problem; see +this :ref:`troubleshooting item ` for help. Next, go ahead and modify the file a little bit. If you change the -``delay(1000);`` lines to a different value, the speed of the blink -will change. The value is a time in milliseconds to pause before +number in the ``delay(1000);`` lines, the speed of the blink will +change. The number is a time in milliseconds to pause before continuing with the program, so by default, the LED will be on for 1 second, then off for 1 second, etc. Any time you make any changes, go through the same Verify and Upload process to upload the new version @@ -174,17 +176,16 @@ Use the serial port monitor! As a last step to make sure everything has been configured correctly, let's upload a "Hello, world!" program that will send text from the -Maple back to the IDE over the USB connection. From the File menu, -select Examples > Stubs > HelloWorld (similarly to when you selected -the Blink program), and make sure the correct board and serial port -targets are selected from the Tools menu. +board back to the IDE over the USB connection. + +From the File menu, select Examples > Stubs > HelloWorld (similarly to +how you selected the Blink program), and make sure the correct board +and serial port targets are selected from the Tools menu. Open the Serial Monitor window (on the far right of the toolbar). Then -go back to the code editing window and upload your program (Upload -will recompile your code automatically if there's been any change -since the last Verify). You should get text spit at you over the -serial monitor right after the program is uploaded. Shout back! We -can hear you! +go back to the code editing window and upload your program. You should +get text spit at you over the serial monitor right after the program +is uploaded. Shout back! We can hear you! Go forth exuberantly! --------------------- @@ -202,7 +203,8 @@ computer, you may want to look at the :ref:`Unix toolchain quickstart ` guide. It's the tutorial for getting working with your old friends :command:`make`, :command:`gcc`, and :command:`jtag`. -Let us know what you come up with! Tag us with #leaflabs on Twitter, -post in the `forum`_, post on `our wiki's Projects page +Let us know what you come up with! Reach us at `leaflabs +`_ on Twitter, post in the `forum`_, +post on `our wiki's Projects page `_, track us down in the real world, whatever. We love projects! -- cgit v1.2.3 From c0951f67646ccae0ad4d96752000dafd11477a70 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 03:51:50 -0400 Subject: language.rst: Improvements for C and C++ programmers. Improve the "Looking for Something Else" escape hatches, so people who aren't looking for Wiring can get where they're going more easily. Fix and improve the Note for C/C++ hackers. Remove the note about dynamic memory; that works now. Other tweaks. Signed-off-by: Marti Bolivar --- source/language.rst | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/source/language.rst b/source/language.rst index 82d2e7b..1a8ef30 100644 --- a/source/language.rst +++ b/source/language.rst @@ -9,11 +9,8 @@ The Maple can be programmed in the `Wiring `_ language, which is the same language used to program the `Arduino `_ boards. - -.. TODO [0.2.0?] Wiring tutorial - -C or C++ programmers may wish to skip to the -:ref:`arduino_c_for_c_hackers` or the :ref:`unix-toolchain`. +C or C++ programmers who are new to Wiring may wish to skip to the +:ref:`arduino_c_for_c_hackers`. .. contents:: Contents :local: @@ -22,10 +19,10 @@ C or C++ programmers may wish to skip to the - See the :ref:`libraries` for extra built-in libraries. - - If you want to use C or C++, see the :ref:`unix-toolchain`. + - If you prefer C or C++ over Wiring, see the :ref:`unix-toolchain`. - If you're looking for something from the C standard library (like - ``atoi()``, for instance, see :ref:`this FAQ `. + ``atoi()``, for instance), see :ref:`this FAQ `. - Low-level details are in :ref:`libmaple` and this page's :ref:`Recommended Reading `. @@ -295,24 +292,20 @@ the following is valid Wiring, and ``f()`` returns ``5``:: All of the files in a sketch share the same (global) namespace. That is, the behavior is as if all of a sketch's files were part of the same translation unit, so they don't have to include one another in -order to access each other's definitions. The only other major -difference between Wiring and C++ is that Wiring doesn't support -dynamically allocated memory -- that is, ``new`` and ``delete`` won't -work. As of |today|, Maple only has 20 KB RAM, anyway, so it's -doubtful that static allocation is not what you want. +order to access each other's definitions. The Wiring language also does not require you to define your own ``main`` method (in fact, we currently forbid you from doing so). Instead, you are required to define two functions, ``setup`` and -``loop``, with type signatures :: +``loop``, whose prototypes are :: void setup(void); void loop(void); Once a sketch is uploaded to a Maple and begins to run, ``setup()`` is -called once, and then ``loop()`` is called repeatedly. The IDE -compilation process proceeds via a source-to-source translation from -the files in a sketch to C++. +called once, and then ``loop()`` is called repeatedly, forever. The +IDE compilation process proceeds via a source-to-source translation +from the files in a sketch to C++. This translation process first concatenates the sketch files, then parses the result to produce a list of all functions defined in the @@ -328,7 +321,7 @@ depends on a particular ordering. The concatenated sketch files are then appended onto a file which includes `WProgram.h `_ -(which includes the wirish and libmaple libraries, and declares +(which includes the Wirish and libmaple proper libraries, and declares ``setup()`` and ``loop()``), and then provides declarations for all the function definitions found in the previous step. At this point, we have a file that is a valid C++ translation unit, but lacks -- cgit v1.2.3 From b5a3b928f4816f013c6962ee8fee46702e14d957 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 21 Sep 2011 03:59:33 -0400 Subject: bootloader: Add FIXME for missing Native bootloader link. Signed-off-by: Marti Bolivar --- README | 1 + source/bootloader.rst | 2 ++ 2 files changed, 3 insertions(+) diff --git a/README b/README index 87e8bf1..2fe5092 100644 --- a/README +++ b/README @@ -146,6 +146,7 @@ file for it into source/hardware/! * adc.rst: low-noise ADC banks * usart.rst: USART pin maps * gpio.rst: master pin maps + * bootloader.rst: flashing a custom bootloader - The quickstart document may not explain how to use the new board. If the board is different enough, a new, special-purpose quickstart diff --git a/source/bootloader.rst b/source/bootloader.rst index 1a0fa6d..e3eb65e 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -584,6 +584,8 @@ DFU pipe and bringing up the USB serial port. Flashing A Custom Bootloader ---------------------------- +.. FIXME [0.0.13] Update for Maple Native + .. warning:: This section is for users who want to put a fresh or custom bootloader on their board. It's possible to make a mistake in this process and e.g. render your Maple unable to communicate -- cgit v1.2.3 From bde14c85ed1ddb10a47cded027c240bb7b91c996 Mon Sep 17 00:00:00 2001 From: jess b Date: Sat, 17 Sep 2011 14:05:36 -0700 Subject: Added VREF errata. --- source/hardware/maple-native-beta.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst index e7c41d3..f120c05 100644 --- a/source/hardware/maple-native-beta.rst +++ b/source/hardware/maple-native-beta.rst @@ -540,6 +540,9 @@ Beta. * **PWM on pin 39**: PWM on pin 39 appears to be nonfunctional. We are looking into this issue. +* **VREF is nonfunctional**: Due to a routing error, VREF is + permanently tied to 3.3V at VAA. + Recommended Reading ------------------- -- cgit v1.2.3 From 33dd48cd16e51466188a28a37cc2a2b3b3f4305d Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 22 Sep 2011 10:46:36 -0400 Subject: Fix digitalRead() example bug. Thanks to forum user jumpnowdev. Signed-off-by: Marti Bolivar --- source/lang/api/digitalread.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/lang/api/digitalread.rst b/source/lang/api/digitalread.rst index ccf4a4c..03ccd7f 100644 --- a/source/lang/api/digitalread.rst +++ b/source/lang/api/digitalread.rst @@ -31,7 +31,7 @@ The following example turns the LED on or off when the button is pressed:: void loop() { int val = digitalRead(BOARD_BUTTON_PIN); // reads the input pin - togglePin(BOARD_LED_PIN, val); + togglePin(BOARD_LED_PIN); } Arduino Compatibility -- cgit v1.2.3 From ea6087a26a44ad8c7362b23143eafa2c64dcc125 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 23 Sep 2011 16:34:49 -0400 Subject: unix-toolchain: Add some Fedora instructions. These are preliminary and should be improved. Signed-off-by: Marti Bolivar --- source/unix-toolchain.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index cb23782..ec9e47c 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -46,7 +46,9 @@ Linux ^^^^^ These instructions are oriented towards Linux users using a -contemporary Debian-based distribution. +contemporary, 32-bit Debian-based distribution. If you use another +Linux operating system and you have any tips to offer, please us at +info@leaflabs.com or post in the `forum`_. Thanks! **1. Collect and Install Tools** @@ -55,6 +57,12 @@ First, you'll need some tools:: $ sudo aptitude install build-essential git-core wget screen dfu-util \ openocd python python-serial +A user report says that on Fedora, the following will install Git, +wget, screen, dfu-util, Python, and PySerial, although it won't +install GCC, etc.:: + + $ yum install screen wget git pyserial dfu-util openocd + You'll want to install a bunch of developer "basics" like ``make``, ``tar``, etc. A good catch-all for these tools is the ``build-essential`` meta-package on most Debian platforms: installing -- cgit v1.2.3 From 00b01e470100260655b3994723449f88e434a733 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 24 Sep 2011 15:53:38 -0400 Subject: unix-toolchain: More Fedora instructions. Signed-off-by: Marti Bolivar --- source/unix-toolchain.rst | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index ec9e47c..a9724c3 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -45,29 +45,23 @@ Setup Linux ^^^^^ -These instructions are oriented towards Linux users using a -contemporary, 32-bit Debian-based distribution. If you use another -Linux operating system and you have any tips to offer, please us at -info@leaflabs.com or post in the `forum`_. Thanks! +These instructions are oriented towards Linux users using +contemporary, 32-bit Debian- or Red Hat-based distributions. If you +use another Linux operating system and you have any tips to offer, +please us at info@leaflabs.com or post in the `forum`_. Thanks! **1. Collect and Install Tools** -First, you'll need some tools:: +First, you'll need some tools. + +On Debian-based distributions (including Ubuntu, etc.), do this with:: $ sudo aptitude install build-essential git-core wget screen dfu-util \ openocd python python-serial -A user report says that on Fedora, the following will install Git, -wget, screen, dfu-util, Python, and PySerial, although it won't -install GCC, etc.:: - - $ yum install screen wget git pyserial dfu-util openocd +On Red Hat-based distributions (Fedora, etc.), do this with:: -You'll want to install a bunch of developer "basics" like ``make``, -``tar``, etc. A good catch-all for these tools is the -``build-essential`` meta-package on most Debian platforms: installing -this fake package will pull in dozens of useful tools without bogging -your system down too much. + $ yum install screen wget git python pyserial dfu-util openocd make `Git `_ is a distributed code versioning system we use to track changes in our source code; ``git-core`` is the -- cgit v1.2.3 From 6f231684ac1acf5785cfa8c137e2827f0832d618 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 24 Sep 2011 19:19:28 -0400 Subject: libmaple/scb: Update for fixed SCB. Updates for libmaple commit f3345d6bb096c68bfa59d689daddd14f63a47e30. Signed-off-by: Marti Bolivar --- source/libmaple/api/scb.rst | 137 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 136 insertions(+), 1 deletion(-) diff --git a/source/libmaple/api/scb.rst b/source/libmaple/api/scb.rst index ff6f61b..0c844b1 100644 --- a/source/libmaple/api/scb.rst +++ b/source/libmaple/api/scb.rst @@ -6,6 +6,16 @@ System Control Block (SCB) support. +.. warning:: + + At time of writing, ST PM0056 (which specifies the system control + block) appears to be buggy (some registers required by ARM are not + mentioned). This file is the result of combining material from ARM + and ST, and is subject to change. + + If you notice a problem or have any other input on this, please + `contact`_ us! + .. contents:: Contents :local: @@ -27,4 +37,129 @@ Register Map Base Pointers Register Bit Definitions ------------------------ -None at this time. +CPUID base register (SCB_CPUID) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_CPUID_IMPLEMENTER +.. doxygendefine:: SCB_CPUID_VARIANT +.. doxygendefine:: SCB_CPUID_CONSTANT +.. doxygendefine:: SCB_CPUID_PARTNO +.. doxygendefine:: SCB_CPUID_REVISION + +Interrupt control state register (SCB_ICSR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_ICSR_NMIPENDSET +.. doxygendefine:: SCB_ICSR_PENDSVSET +.. doxygendefine:: SCB_ICSR_PENDSVCLR +.. doxygendefine:: SCB_ICSR_PENDSTSET +.. doxygendefine:: SCB_ICSR_PENDSTCLR +.. doxygendefine:: SCB_ICSR_ISRPENDING +.. doxygendefine:: SCB_ICSR_VECTPENDING +.. doxygendefine:: SCB_ICSR_RETOBASE +.. doxygendefine:: SCB_ICSR_VECTACTIVE + +Vector table offset register (SCB_VTOR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_VTOR_TBLOFF + +Application interrupt and reset control register (SCB_AIRCR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_AIRCR_VECTKEYSTAT +.. doxygendefine:: SCB_AIRCR_VECTKEY +.. doxygendefine:: SCB_AIRCR_ENDIANNESS +.. doxygendefine:: SCB_AIRCR_PRIGROUP +.. doxygendefine:: SCB_AIRCR_SYSRESETREQ +.. doxygendefine:: SCB_AIRCR_VECTCLRACTIVE +.. doxygendefine:: SCB_AIRCR_VECTRESET + +System control register (SCB_SCR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_SCR_SEVONPEND +.. doxygendefine:: SCB_SCR_SLEEPDEEP +.. doxygendefine:: SCB_SCR_SLEEPONEXIT + +Configuration and Control Register (SCB_CCR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_CCR_STKALIGN +.. doxygendefine:: SCB_CCR_BFHFNMIGN +.. doxygendefine:: SCB_CCR_DIV_0_TRP +.. doxygendefine:: SCB_CCR_UNALIGN_TRP +.. doxygendefine:: SCB_CCR_USERSETMPEND +.. doxygendefine:: SCB_CCR_NONBASETHRDENA + +System handler priority registers (SCB_SHPRx) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_SHPR1_PRI6 +.. doxygendefine:: SCB_SHPR1_PRI5 +.. doxygendefine:: SCB_SHPR1_PRI4 + +.. doxygendefine:: SCB_SHPR2_PRI11 + +.. doxygendefine:: SCB_SHPR3_PRI15 +.. doxygendefine:: SCB_SHPR3_PRI14 + +System Handler Control and state register (SCB_SHCSR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_SHCSR_USGFAULTENA +.. doxygendefine:: SCB_SHCSR_BUSFAULTENA +.. doxygendefine:: SCB_SHCSR_MEMFAULTENA +.. doxygendefine:: SCB_SHCSR_SVCALLPENDED +.. doxygendefine:: SCB_SHCSR_BUSFAULTPENDED +.. doxygendefine:: SCB_SHCSR_MEMFAULTPENDED +.. doxygendefine:: SCB_SHCSR_USGFAULTPENDED +.. doxygendefine:: SCB_SHCSR_SYSTICKACT +.. doxygendefine:: SCB_SHCSR_PENDSVACT +.. doxygendefine:: SCB_SHCSR_MONITORACT +.. doxygendefine:: SCB_SHCSR_SVCALLACT +.. doxygendefine:: SCB_SHCSR_USGFAULTACT +.. doxygendefine:: SCB_SHCSR_BUSFAULTACT +.. doxygendefine:: SCB_SHCSR_MEMFAULTACT + +Configurable fault status register (SCB_CFSR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_CFSR_DIVBYZERO +.. doxygendefine:: SCB_CFSR_UNALIGNED +.. doxygendefine:: SCB_CFSR_NOCP +.. doxygendefine:: SCB_CFSR_INVPC +.. doxygendefine:: SCB_CFSR_INVSTATE +.. doxygendefine:: SCB_CFSR_UNDEFINSTR +.. doxygendefine:: SCB_CFSR_BFARVALID +.. doxygendefine:: SCB_CFSR_STKERR +.. doxygendefine:: SCB_CFSR_UNSTKERR +.. doxygendefine:: SCB_CFSR_IMPRECISERR +.. doxygendefine:: SCB_CFSR_PRECISERR +.. doxygendefine:: SCB_CFSR_IBUSERR +.. doxygendefine:: SCB_CFSR_MMARVALID +.. doxygendefine:: SCB_CFSR_MSTKERR +.. doxygendefine:: SCB_CFSR_MUNSTKERR +.. doxygendefine:: SCB_CFSR_DACCVIOL +.. doxygendefine:: SCB_CFSR_IACCVIOL + +Hard Fault Status Register (SCB_HFSR) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. doxygendefine:: SCB_HFSR_DEBUG_VT +.. doxygendefine:: SCB_CFSR_FORCED +.. doxygendefine:: SCB_CFSR_VECTTBL + +Debug Fault Status Register +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: This register is not specified in PM0056, but it is required + by ARM. The bit definitions here are based on the names given in + the ARM v7-M ARM. + +.. doxygendefine:: SCB_DFSR_EXTERNAL +.. doxygendefine:: SCB_DFSR_VCATCH +.. doxygendefine:: SCB_DFSR_DWTTRAP +.. doxygendefine:: SCB_DFSR_BKPT +.. doxygendefine:: SCB_DFSR_HALTED + -- cgit v1.2.3 From bdee24f7cf24eb91a6c5f8d781be78cd2c559817 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 24 Sep 2011 19:20:29 -0400 Subject: libmaple/nvic: Add nvic_sys_reset(). Signed-off-by: Marti Bolivar --- source/libmaple/api/nvic.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/libmaple/api/nvic.rst b/source/libmaple/api/nvic.rst index 11342d2..b22c94b 100644 --- a/source/libmaple/api/nvic.rst +++ b/source/libmaple/api/nvic.rst @@ -31,6 +31,7 @@ Functions .. doxygenfunction:: nvic_irq_enable .. doxygenfunction:: nvic_irq_disable .. doxygenfunction:: nvic_irq_disable_all +.. doxygenfunction:: nvic_sys_reset Register Map Base Pointers -------------------------- -- cgit v1.2.3 From e1e83f547844ba09bb90b3dbc3608c2608974e84 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 26 Sep 2011 09:14:08 -0400 Subject: unix-toolchain: Add Fedora udev recipe. Signed-off-by: Marti Bolivar --- source/unix-toolchain.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index a9724c3..751ec18 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -119,18 +119,25 @@ script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. **3. Install udev Rules** -From the libmaple directory, :: +From the libmaple directory, copy our udev rules to ``/etc/udev/rules.d``:: - $ groups # make sure it includes plugdev; if not, add yourself to it $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules + +On Debian, run ``$ groups``. Make sure the output includes "plugdev". +If not, add yourself to that group. Then run :: + $ sudo restart udev +On Red Hat, run :: + + $ udevadm control --reload-rules + As a security precaution on Linux, unknown USB devices can only be accessed by root. This udev script identifies the Maple based on its -vendor and product IDs, mounts it to :file:`/dev/maple`, and grants -read/write permissions to the ``plugdev`` group. After restarting -``udev`` you'll need to fully unplug or power cycle any Maples -connected to the computer. +vendor and product IDs, mounts it to :file:`/dev/maple`, and (on +Debian-based distros) grants read/write permissions to the ``plugdev`` +group. After restarting ``udev`` you'll need to fully unplug or power +cycle any Maples connected to the computer. **So far, so good?** -- cgit v1.2.3 From 5bd0865c807b5270fdb8af77c3c4104dee96d1e2 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 26 Sep 2011 14:26:39 -0400 Subject: maple-ide-install: Oracle, not Sun. Signed-off-by: Marti Bolivar --- source/maple-ide-install.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 0a083f7..4924bbb 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -119,9 +119,10 @@ Linux The IDE is written in Java and requires a compatible runtime (JRE). - If you don't have one, they're usually pretty easy to install. Sun - Java 1.6 and OpenJDK 1.6 are known to work, and runtimes mostly - compatible with Sun Java 1.5+ should probably get the job done. + If you don't have one, they're usually pretty easy to install. + Oracle Java 1.6 and OpenJDK 1.6 are known to work, and runtimes + mostly compatible with Oracle Java 1.5+ should probably get the job + done. To install Java, try using your distribution's software packaging tool and search for "JRE" or "java". On Debian-based systems -- cgit v1.2.3 From 84956b94ad9a609534449d08cb72f998a1604c32 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 4 Oct 2011 19:39:52 -0400 Subject: [WIP] Overhaul Unix toolchain quickstart. Signed-off-by: Marti Bolivar --- source/_static/img/winxp-bashrc-notepad.png | Bin 0 -> 9678 bytes source/_static/img/winxp-git-bash-screenshot.png | Bin 0 -> 16515 bytes source/_static/img/winxp-open-bashrc-with.png | Bin 0 -> 44928 bytes source/maple-ide-install.rst | 2 + source/unix-toolchain.rst | 387 ++++++++++++++--------- 5 files changed, 246 insertions(+), 143 deletions(-) create mode 100644 source/_static/img/winxp-bashrc-notepad.png create mode 100644 source/_static/img/winxp-git-bash-screenshot.png create mode 100644 source/_static/img/winxp-open-bashrc-with.png diff --git a/source/_static/img/winxp-bashrc-notepad.png b/source/_static/img/winxp-bashrc-notepad.png new file mode 100644 index 0000000..9395f2d Binary files /dev/null and b/source/_static/img/winxp-bashrc-notepad.png differ diff --git a/source/_static/img/winxp-git-bash-screenshot.png b/source/_static/img/winxp-git-bash-screenshot.png new file mode 100644 index 0000000..24d4a7a Binary files /dev/null and b/source/_static/img/winxp-git-bash-screenshot.png differ diff --git a/source/_static/img/winxp-open-bashrc-with.png b/source/_static/img/winxp-open-bashrc-with.png new file mode 100644 index 0000000..18b157f Binary files /dev/null and b/source/_static/img/winxp-open-bashrc-with.png differ diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index 4924bbb..371103d 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -67,6 +67,8 @@ First, extract all the files in the ZIP file to a suitable location on your system (like your Desktop folder). Next, you have to install some drivers. Sorry! +.. _maple-ide-install-windows-drivers: + .. note:: Note that while these instructions work on Windows XP, changes in Windows 7 mean that you won't be able to install the IDE without disabling driver signing on your computer. We're working diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 751ec18..a397cc1 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -6,22 +6,14 @@ Unix Toolchain Quickstart =========================== -This is a tutorial for using the Maple with a standard Unix toolchain -(``make``, ``gcc``, etc.). It's not necessary to do this in order to -program the Maple; you can always :ref:`install the Maple IDE -` instead. This document is intended for users who -are comfortable using C or C++ and would like to use :ref:`libmaple` -directly. - -We currently have instructions for 32- and 64-bit Linux and OS X Snow -Leopard. If you're on another Unix platform, Windows, or an earlier -version of OS X, we imagine you can translate/port these directions on -your own. You might want to begin with these `stripped down -distributions `_ of the -`CodeSourcery GCC compiler tools -`_ (including Win32 -versions). If you do have success on other platforms, please post in -the forums, so we can fold your tips into this document! +This is a tutorial for using a standard Unix toolchain (``make``, +``gcc``, etc.) with Maple. It's intended for C and C++ programmers +who want to use :ref:`libmaple` directly. If you're just beginning, we +recommend installing :ref:`Maple IDE ` instead. + +If you have success on an operating system not covered here, please +post in the `forum`_ (or email us at info@leaflabs.com), so we can +update this document. .. contents:: Contents :local: @@ -29,68 +21,83 @@ the forums, so we can fold your tips into this document! Requirements ------------ -You'll need a Maple board, a Mini-B USB cable, a functional computer, -and root (or Administrator) access to that computer. This guide -assumes you've had success with the IDE on your machine and that you -are fairly comfortable with the Unix command line. Some previous -experience with editing your shell startup script (.bashrc, .tcshrc, -etc.) and using `GCC `_ and `make -`_ is recommended. +You need a Maple board, a Mini-B USB cable, and root (or +Administrator) access to your computer. We assume you've had success +with the IDE on your machine (this is important on Windows, as this +document doesn't cover :ref:`driver installation +`). -.. _toolchain-linux-setup: +On Linux and OS X, some previous experience with editing your shell +startup script (.bashrc, .tcshrc, etc.) and using `GCC +`_ and `make +`_ is recommended. (The Windows +instructions are more detailed, since we assume most Windows users +will be new to the Unix shell). Setup ----- +.. _toolchain-linux-setup: + Linux ^^^^^ -These instructions are oriented towards Linux users using -contemporary, 32-bit Debian- or Red Hat-based distributions. If you -use another Linux operating system and you have any tips to offer, -please us at info@leaflabs.com or post in the `forum`_. Thanks! - **1. Collect and Install Tools** First, you'll need some tools. -On Debian-based distributions (including Ubuntu, etc.), do this with:: +On Debian-based distributions (including Ubuntu):: $ sudo aptitude install build-essential git-core wget screen dfu-util \ openocd python python-serial -On Red Hat-based distributions (Fedora, etc.), do this with:: +On Red Hat-based distributions (including Fedora):: $ yum install screen wget git python pyserial dfu-util openocd make -`Git `_ is a distributed code versioning system -we use to track changes in our source code; ``git-core`` is the -corresponding package. +On other distributions, you'll need to figure this out for yourself +(let us know if you do!). -``wget`` is a simple tool to download files over http from the command -line; installing it is optional (you could pull in the required -downloads using a browser). +The following are **mandatory**: -``screen`` is a screen manager; in the context of Maple, we use it to -connect to serial port devices. +* `Git `_ is a distributed version control + system. We use it to track our source code. -``dfu-util`` is a tool from the `OpenMoko`_ project that we use to -upload programs to the Maple over USB. +* `dfu-util `_ is a tool from + the `OpenMoko`_ project. It is used to upload programs to the Maple + over USB. -.. _OpenMoko: http://openmoko.com/ +* `make `_ is used to direct + compilation. + +* `Python `_ is a programming language. Our reset + script, which sends control signals to the board which cause it to + to reset and enter the :ref:`bootloader `, is written in + Python. (Most Linux distributions these days include Python by + default). -``openocd`` is a `JTAG -`_ control -program used in conjunction with an ARM JTAG device to do in circuit -debugging (pause/resume program execution, upload and download code, -read out register status, etc). It's also optional. +* `PySerial`_ is a Python library for interacting with serial port + devices. It's needed by our reset script. PySerial can also be + installed with `easy_install + `_. -Lastly, our reset script (which sends control signals over the -USB-serial connection to restart and enter the bootloader) is written -in `Python `_, and requires the `PySerial -`_ library available in the -``python-serial`` package. This can also be installed with -`easy_install `_. +The following are **optional**: + +* `wget `_ is a tool for downloading files + from the command line. You could also pull in the required downloads + using a web browser. + +* `screen `_ is a screen manager we use + to connect to serial port devices. Some popular alternatives are + Minicom and Kermit. + +* `openocd `_ is a `JTAG + `_ control + program. It is used with an ARM JTAG device to do in-circuit + debugging (uploading new code, connecting to `GDB + `_, etc.). + +.. _OpenMoko: http://openmoko.com/ **2. Fetch libmaple and Compiler Toolchain** :: @@ -101,16 +108,15 @@ in `Python `_, and requires the `PySerial $ tar xvzf gcc-arm-none-eabi-latest-linux32.tar.gz $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up -This step is fairly straightforward: do a git clone of the `libmaple -repository `_ to some directory, -then download and extract the ARM compiler toolchain. +In this step, you make a Git clone of the `libmaple repository +`_, then download and extract +the ARM compiler toolchain. -The :file:`arm/bin/` directory will need to be added to ``PATH``; you -can check that this worked by entering ``arm-none-`` and hitting tab -to auto-complete (your shell should show a bunch of results). +The directory :file:`arm/bin/` will need to be added to your ``PATH``; +you can check that this worked by entering ``arm-none-`` and hitting +tab to auto-complete (your shell should show a bunch of results). Regardless of where you put the toolchain, make sure to preserve its -internal directory layout, as the binaries make relative path calls -and references. +internal directory layout. After you're done, you'll probably want to update your shell startup script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. @@ -149,108 +155,96 @@ Great! Test your setup by :ref:`compiling a sample program OS X ^^^^ -These instructions have been tested successfully on OS X 10.6.4. As -stated previously, this document assumes a general level of Unix -aptitude on the part of the reader; if you're uncomfortable using -Terminal (or if you don't know what that means), then you should -probably stick with using the :ref:`Maple IDE ` to write -programs. +These instructions have been tested successfully on OS X 10.6.4. **1. Collect and Install Tools** You will need the following tools\ [#fpackman]_ to get started: - 1. `XCode `_: If - you're reading this, you've probably already got this. Provides - compilers and other basic tools of the trade. While XCode was once - free of charge, Apple has since begun charging for it; if you'd - rather not pay, you can probably get by with just a `make - `_ binary. - - 2. `Git `_: All of our code is tracked by a - distributed versioning system called Git. A `Mac installer - `_ - is available. +* `XCode `_: If + you're reading this, you've probably already got this. Provides + compilers and other basic tools of the trade. While XCode was once + free of charge, Apple has since begun charging for it; if you'd + rather not pay, you can probably get by with just a `make + `_ binary. - 3. ``dfu-util``: A tool from `OpenMoko`_ that we use to upload - programs to the Maple over USB. If you prefer to compile from - source, OpenMoko provides instructions for `building dfu-util - `_. +* `Git `_: All of our code is tracked by a + distributed versioning system called Git. A `Mac installer + `_ + is available. - If you're in a hurry, you can steal a dfu-util binary from a program - called `OpenMoko Flasher - `_. To - do this, first `download OpenMoko Flasher - `_, then copy - the OpenMoko application into your :file:`/Applications` folder (or - wherever you like). Let's pretend you saved the .app to the directory +* `dfu-util `_: A tool from + `OpenMoko`_ that we use to upload programs to the Maple over USB. - :file:`/Applications/OpenMoko Flasher.app` + If you prefer to compile from source, OpenMoko provides instructions + for `building dfu-util on OS X + `_. - Then the ``dfu-util`` binary resides in + If you're in a hurry, you can use the dfu-util binary bundled with + `OpenMoko Flasher + `_. To + do this, first `download OpenMoko Flasher + `_, then move + it to your :file:`/Applications` folder (or wherever you + like). Let's say you save it as :file:`/Applications/OpenMoko + Flasher.app`. Then the ``dfu-util`` binary resides in - :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` + :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` - To get access to it from the command line, just make a symbolic link - to the binary from some place on your ``PATH``:: + To run it from the command line, make a symbolic link to the binary + from some place on your ``PATH``:: - $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ - /somewhere/on/your/PATH/dfu-util + $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ + /somewhere/on/your/PATH/dfu-util - .. note:: - Just copying the binary somewhere doesn't work, as it relies on - dynamically linked libraries found elsewhere in the .app - bundle. It's possible to pull just the relevant pieces out of the - .app, but you're on your own. + .. note:: - To make sure this worked, try plugging in your Maple, making sure - it's in :ref:`perpetual bootloader mode - ` (do this by pressing RESET, - then quickly pressing BUT and holding it for several seconds), then - running :: + Copying the binary won't work, as it relies on dynamically linked + libraries found elsewhere in the .app bundle. - $ dfu-util -l + To make sure this worked, plug in your Maple, put it into + :ref:`perpetual bootloader mode + ` (press RESET, then quickly + press and hold BUT for several seconds), and run :: - If you see some lines that look like :: + $ dfu-util -l - Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00" - Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000" + The output should look like this:: - then you're all set. + Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00" + Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000" - 4. PySerial: our reset script (which sends control signals over the - USB-serial connection to restart and enter the bootloader) is written - in Python and requires the `PySerial - `_ library. Download the `latest - version `_. After you download - and untar, install it with :: +* `PySerial`_: our reset script (which sends control signals over the + USB-serial connection to restart and enter the bootloader) is + written in Python, and requires the PySerial library. Download and + untar the `latest version `_, + then install with :: - $ cd /path/to/pyserial-x.y - $ python setup.py build - $ sudo python setup.py install + $ cd /path/to/pyserial-x.y + $ python setup.py build + $ sudo python setup.py install - The package is also available via ``easy_install``, so if you're - comfortable using that, you could also install it with :: + PySerial is also available via ``easy_install``, so if you're + comfortable using that, you could alternatively install it with :: - $ easy_install pyserial + $ easy_install pyserial **2. Fetch libmaple and Compiler Toolchain** You first need to clone libmaple:: $ cd ~ - $ git clone git://github.com/leaflabs/libmaple.git libmaple + $ git clone git://github.com/leaflabs/libmaple.git -Then you need to get the cross-compilers we use to build a -project. These are just modified versions of GCC; you can `download -them for OS X here -`_. Let's -say you saved this file to +Next, `download the cross-compilers +`_ +you'll use to build libmaple and your own programs. (These are just +special-purpose versions of GCC). Let's say you saved these as :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz` -You can then unpack the archive and let OS X know where the compilers -live with :: +You can unpack the archive and let the shell know where everything +lives with :: $ cd ~/Downloads $ tar -xvzf gcc-blah-blah-osx32.tar.gz @@ -262,7 +256,111 @@ script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. **So far, so good?** -Great! Go on to the next section, where you test everything out. +Great! Test your setup by :ref:`compiling a sample program +`. + +.. _toolchain-win-setup: + +Windows +^^^^^^^ + +These instructions have been tested successfully on Windows XP SP3. + +1. First, you'll need Git, a distributed versioning system we use to +track our source code. Follow the steps in `this great guide from +GitHub `_. + +2. `Install Python `_. Choose the latest +**2.7.x version**; Python 3 will not work. + +3. `Install PySerial `_. Choose +the latest **pyserial-x.y-win32.exe version**; the "py3k" version will +not work. + +4. Run Git Bash, and get :ref:`libmaple` by typing the following line +and hitting return. (Do not type the "$". We put these in to remind +you that lines like this are for the Git Bash prompt). :: + + $ git clone git://github.com/leaflabs/libmaple.git + +.. note:: Keep the Git Bash window open as you go. + +You now have the libmaple repository in the folder ``Documents and +Settings\``. + +5. Download this `archive of the CodeSourcery compiler toolchain +`_. +When the download finishes, move the file into the libmaple directory. + +6. Type these two lines into the Git Bash prompt to go to the libmaple +folder and extract the archive:: + + $ cd libmaple + $ tar xzf gcc-arm-none-eabi-latest-win32.tar.gz + +This will create a folder named "arm" inside the libmaple folder. + +7. Now you'll configure your system to use these tools. Type the +following lines into the Git Bash prompt. + +.. warning:: If you've installed Bash on your computer before starting + this guide, and have a ~/.bashrc already, these instructions will + overwrite it. If that is the case, we assume you know what you're + doing, and can modify the shell commands in this step appropriately + for your system. + + If you're using Bash for the first time, don't worry about this + warning. + +:: + + $ cat >~/.bashrc < export PATH=\$PATH:~/libmaple/arm/bin/ + > EOF + +.. note:: The "> " at the beginning of the second and third lines will + appear automatically. + +In case that's hard to read, the part of the first line between +``cat`` and ``bashrc`` is these five characters: space ( ), right +angle bracket (>), tilde (~), forward slash (/), and period (.). + +For reference, here's a screenshot of what your Git Bash window should +look like at this point (the output after the ``git clone`` line will +be slightly different): + +.. _toolchain-git-bash-screenshot: + +.. figure:: /_static/img/winxp-git-bash-screenshot.png + :align: center + :alt: Git Bash screenshot + +8. Let's check that you completed the previous step correctly. If you +did, there should be a file called ".bashrc" (the period is supposed +to be there) in the folder ``Documents and Settings\\``. +Open this file in Notepad by right clicking on it and selecting "Open +With...", like so: + +.. figure:: /_static/img/winxp-open-bashrc-with.png + :align: center + :alt: Open .bashrc With + +Choose "Notepad" from the resulting pop-up window, and click "OK". +The Notepad window should look like this: + +.. figure:: /_static/img/winxp-bashrc-notepad.png + :align: center + :alt: .bashrc in Notepad + +The little box at the end of the line is supposed to be there. Close +the Notepad window (do not save any changes you may have made by +accident). + +9. TODO download dfu-util.exe and put it in ``libmaple\arm\bin``. + +**So far, so good?** + +Great! Go on to the next section, where you'll compile a program. .. _toolchain-test: @@ -270,8 +368,9 @@ Test compilation ---------------- Get back into the libmaple directory (this tutorial assumes you put it -in :file:`~/libmaple`) and test that you've installed all the compilation -tools correctly:: +in :file:`~/libmaple`) and test that you've installed all the +compilation tools correctly (Windows users: use ``cs-make`` instead of +``make``):: $ cd ~/libmaple $ cp main.cpp.example main.cpp @@ -281,7 +380,7 @@ tools correctly:: .. note:: These instructions are for the Maple. If you're compiling for another board, you'll need to set a ``BOARD`` environment variable appropriately. For example, to compile for Maple Mini (in - the bash shell), :: + Bash), :: $ export BOARD=maple_mini $ make @@ -350,8 +449,8 @@ friend. .. _toolchain-serialusb: -Communicate over USB-Serial interface -------------------------------------- +Communicate over USB-Serial +--------------------------- Now let's try out the interactive test session. The serial port device file should look something like :file:`/dev/ttyACMXXX` on Linux @@ -392,8 +491,8 @@ and type ``y`` when prompted if you're sure. .. _toolchain-projects: -Starting your own projects --------------------------- +Start your own project +---------------------- So everything worked, and you want to start your own project? Great! There are two ways to go about it. @@ -425,8 +524,8 @@ want to use one of the officially supported :ref:`libraries main include file for the Wirish library is :file:`~/libmaple/wirish/wirish.h`. -Getting Updates ---------------- +Get updates +----------- We update libmaple fairly frequently with bugfixes and other improvements. In order get access to these in your local copy of @@ -462,11 +561,13 @@ our `wiki `_ which you may find useful. Go forth exuberantly! --------------------- -Let us know what you come up with! Use #leaflabs on `Twitter -`_, post in the `forum`_, join the the +Let us know what you come up with! Mention `@leaflabs on Twitter +`_, post in the `forum`_, join the the #leafblowers IRC channel on `freenode `_, whatever. We love projects! +.. _PySerial: http://pyserial.sourceforge.net/ + .. rubric:: Footnotes .. [#fpackman] Some of these software packages might be available on -- cgit v1.2.3 From 5131f81a73f62890e1fcacbb93522734bf82ffc0 Mon Sep 17 00:00:00 2001 From: jess b Date: Mon, 3 Oct 2011 09:11:36 -0700 Subject: Add power information to hardware pages. Squash from v0.0.12-maintenance: Power information additions. Expanded the section "Powering the Maple", added a new "Power Regulation on the Maple" section. Power info updated for MN and Mini RET6 power info update Fixed broken link. Had wrong link to datasheet for MCP1703. maple-native-beta: 80-column cosmetic fix Signed-off-by: Marti Bolivar --- source/hardware/maple-mini.rst | 51 ++++++++++++++++++++------ source/hardware/maple-native-beta.rst | 65 +++++++++++++++++++++++++-------- source/hardware/maple-ret6.rst | 31 ++++++++++++---- source/hardware/maple.rst | 68 ++++++++++++++++++++++++++--------- 4 files changed, 167 insertions(+), 48 deletions(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index 986ab4b..58e394d 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -50,9 +50,40 @@ directly. .. warning:: The silkscreen on the Maple Mini suggests it will accept an input voltage up to 16 V. We recommend applying **no greater - than 12 V**. - - See :ref:`this erratum ` for more information. + than 12 V**, and potentially even lower depending upon the current + draw requirements of the application. Please see :ref:`Power + Regulation on the Maple Mini ` for + more information. + +.. _maple-mini-power-regulation: + +Power Regulation on the Maple Mini +---------------------------------- + +Power regulation on the Maple is provided by two low dropout linear +voltage regulators. (The part is the MCP1703 from Microchip, in the +SOT-23A package. You can download the datasheet `here +`_ ). One +of the regulators supplies power to the digital voltage plane; the +other supplies power to the analog voltage plane. + +These voltage regulators nominally take an input of up to 16V. In +addition, while the maximum continuous output current for the board is +250mA, if you are powering the board off higher voltages the amount +off current it can supply goes down, due to the regulators needing to +dissipate the extra power. So if you are powering the board off 12V, +the max current is about 40mA at room temperature. In general (again, +at room temperature) the max power dissipation (PD) for the chip is +about .37W, and output current = PD/(Vin-Vout). For exact max current +calculations, please refer to the datasheet linked above. + +If you are planning to draw a lot of current from the Maple board, it +is necessary to provide input power as close to 3.3V as +possible. Powering the microcontroller circuitry and LEDs on the board +alone takes approximately 30mA, so if you are powering the board with +12V that leaves only 10mA (at best) available for powering any user +circuitry. Attempting to draw more than 10mA runs the risk of shorting +out the power regulators and bricking your board. .. _maple-mini-gpios: @@ -339,14 +370,12 @@ This section lists known issues and warnings for the Maple Mini Rev 2 .. _maple-mini-vin: * **Silkscreen Vin voltage mistake**: The silkscreen on the Maple Mini - falsely indicates that Vin may be supplied with up to 16 V. We - recommend an input voltage **no greater than 12 V**. - - The voltage regulator on the Mini is rated up to 16 V. However, our - tests indicate that as its input voltage approaches 16 V, its output - begins to rise to levels higher than those recommended by ST for - supplying the STM32F103CB. The limit of 12 V keeps the voltage - supplied to the processor at safe levels. + falsely indicates that Vin may be supplied with up to 16V. We + recommend an input voltage **no greater than 12V**, and potentially + even lower depending upon the current draw requirements of the + application. Please see :ref:`Power Regulation on the Maple Mini + ` for more information. + Recommended Reading ------------------- diff --git a/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst index f120c05..f1b2284 100644 --- a/source/hardware/maple-native-beta.rst +++ b/source/hardware/maple-native-beta.rst @@ -46,20 +46,57 @@ Technical Specifications Powering the Maple Native ------------------------- -The Maple Native may be powered from the barrel jack connector, USB, -or a LiPo battery. The power source is determined by the header -labeled "PWRSEL" on the silkscreen. Boards are shipped with a jumper -on the USB selector. In order to power it off of an alternative -source, unplug the Maple Native, then move the jumper to the desired -selector before reconnecting power. - -You can also power the Maple Native via the pin labeled "Vin" on the -vertical header to the right of the PWRSEL header. This pin feeds -into both the digital and analog voltage regulators. However, don't -do this while simultaneously powering the board from another source, -or you could damage it. - -We recommend an input voltage no greater than 12 V. +The power source is determined by the header labeled "PWRSEL" on the +silkscreen. The Maple Native may be powered from USB (marked "USB" on +the PWRSEL header), a LiPo battery (marked "BAT"), or one of the two +"Vin" pins (marked "EXT"). Boards are shipped with a jumper on the +USB selector. In order to power it off of an alternative source, +unplug the Maple Native, then move the jumper to the desired selector +before reconnecting power. + +The "Vin" line is available on the pin labeled "Vin" on the vertical +header to the right of the PWRSEL header, as well as on the +unpopulated two-pin connector on the upper left corner of the +board. On this latter connector, polarity was accidentally left +unmarked: the leftmost, round pin should be power, while the square +pin should be ground. + +When powering the Maple Native board from a battery or the Vin lines, +care must be taken not to over-voltage the board. In general, an upper +limit of 12V input is acceptable, but this may vary depending upon the +current draw requirements of the application. Please see :ref:`Power +Regulation on the Maple Native ` for +more information. + +.. _maple-native-b-power-regulation: + +Power Regulation on the Maple Native +------------------------------------ + +Power regulation on the Maple Native is provided by two low dropout +linear voltage regulators. (The part is the MCP1703 from Microchip, in +the SOT-23A package. You can download the datasheet `here +`_). One +of the regulators supplies power to the digital voltage plane; the +other supplies power to the analog voltage plane. + +These voltage regulators nominally take an input of up to 16V. In +addition, while the maximum continuous output current for the board is +250mA, if you are powering the board off higher voltages the amount +off current it can supply goes down, due to the regulators needing to +dissipate the extra power. So if you are powering the board off 12V, +the max current is about 40mA at room temperature. In general (again, +at room temperature) the max power dissipation (PD) for the chip is +about .37W, and output current = PD/(Vin-Vout). For exact max current +calculations, please refer to the datasheet linked above. + +If you are planning to draw a lot of current from the Maple Native +board, it is necessary to provide input power as close to 3.3V as +possible. Powering the microcontroller circuitry and LEDs on the board +alone takes approximately 30mA, so if you are powering the board with +12V that leaves only 10mA (at best) available for powering any user +circuitry. Attempting to draw more than 10mA runs the risk of shorting +out the power regulators and bricking your board. Using the Built-in Battery Charger ---------------------------------- diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst index d5bf049..21c033b 100644 --- a/source/hardware/maple-ret6.rst +++ b/source/hardware/maple-ret6.rst @@ -58,9 +58,20 @@ standard Maple `. .. warning:: The RET6 Edition silkscreen falsely indicates that the barrel jack accepts up to 18 V. We recommend a barrel jack input - voltage **no greater than 12 V**. + voltage **no greater than 12V**, and potentially even lower + depending upon the current draw requirements of the + application. The same goes for powering off LiPo batteries. - See :ref:`this erratum ` for more information. + Please see :ref:`Power Regulation on the Maple + ` for more information. + +.. _maple-ret6power-regulation: + +Power Regulation on the Maple RET6 +---------------------------------- + +Power regulation on the Maple RET6 works in the :ref:`same way as the +standard Maple `. Using the Built-in Battery Charger ---------------------------------- @@ -373,11 +384,17 @@ features only available on the STM32F103RET6. .. _maple-ret6-barrel-jack: -* **Barrel jack power supply voltage mistake**: The silkscreen next to - the barrel jack connector incorrectly indicates that up to an 18 V - input voltage is allowed. **We do not recommend exceeding 12 V**. - - See this :ref:`Maple erratum ` for more +* **Barrel jack power supply voltage mistake**: The acceptable voltage + range given next to the barrel jack on the Maple RET6 is + **incorrect**. The given range is 7V — 18V. In fact, **18V is too + high** and should not be supplied to your board. The original + voltage regulators used on the Maple were rated up to 18V. However, + the voltage regulators on current Maple Revs are rated up to only + 16V, and due to the current draw requirements of the board, operate + properly only up to 12V. The recommended maximum voltage you should + apply is **12V**, and potentially even lower depending upon the + current draw requirements of the application. Please see :ref:`Power + Regulation on the Maple ` for more information. * **Power supply marketing mistake**: We originally sold the Maple diff --git a/source/hardware/maple.rst b/source/hardware/maple.rst index 610fdfc..aff64d5 100644 --- a/source/hardware/maple.rst +++ b/source/hardware/maple.rst @@ -103,15 +103,50 @@ header. This pin feeds into both the digital and analog voltage regulators. However, don't do this while simultaneously powering the board from another source, or you could damage it. +When powering the board from a barrel jack, **double check the +polarity of the barrel.** The appropriate polarity is noted on the +silkscreen right next to the connector. + .. warning:: Silkscreens on Maples up through Rev 5s manufactured in Spring 2011 falsely indicated that the barrel jack could be - supplied by up to 18 V. We recommend a barrel jack input voltage - **no greater than 12 V**. - - Rev5s manufactured after Spring 2011 may still have this error on - the silk, but it has been marked over. - - See :ref:`this erratum ` for more information. + supplied by up to 18V. (Rev5s manufactured after Spring 2011 may + still have this error on the silk, but it has been marked over.) We + recommend a barrel jack input voltage **no greater than 12V**, and + potentially even lower depending upon the current draw requirements + of the application. The same goes for powering off LiPo batteries. + + Please see :ref:`Power Regulation on the Maple + ` for more information. + +.. _maple-power-regulation: + +Power Regulation on the Maple +----------------------------- + +Power regulation on the Maple is provided by two low dropout linear +voltage regulators. (The part is the MCP1703 from Microchip, in the +SOT-23A package. You can download the datasheet `here +`_ ). One +of the regulators supplies power to the digital voltage plane; the +other supplies power to the analog voltage plane. + +These voltage regulators nominally take an input of up to 16V. In +addition, while the maximum continuous output current for the board is +250mA, if you are powering the board off higher voltages the amount +off current it can supply goes down, due to the regulators needing to +dissipate the extra power. So if you are powering the board off 12V, +the max current is about 40mA at room temperature. In general (again, +at room temperature) the max power dissipation (PD) for the chip is +about .37W, and output current = PD/(Vin-Vout). For exact max current +calculations, please refer to the datasheet linked above. + +If you are planning to draw a lot of current from the Maple board, it +is necessary to provide input power as close to 3.3V as +possible. Powering the microcontroller circuitry and LEDs on the board +alone takes approximately 30mA, so if you are powering the board with +12V that leaves only 10mA (at best) available for powering any user +circuitry. Attempting to draw more than 10mA runs the risk of shorting +out the power regulators and bricking your board. Using the Built-in Battery Charger ---------------------------------- @@ -423,15 +458,16 @@ General * **Barrel jack power supply voltage mistake**: The acceptable voltage range given next to the barrel jack on the Maple through Rev 5s - manufactured in Spring 2011 is **incorrect**. The given range is 7 - V — 18 V. In fact, **18 V is too high** and should not be supplied - to your board. The recommended maximum voltage you should apply is - **12 V**. - - The original voltage regulators used on the Maple were rated up to - 18 V. However, the voltage regulators on current Maple Revs are - rated up to 16 V. Our tests indicate that they operate correctly - through 12 V. We do not recommend higher input voltages. + manufactured in Spring 2011 is **incorrect**. The given range is 7V + — 18V. In fact, **18V is too high** and should not be supplied to + your board. The original voltage regulators used on the Maple were + rated up to 18V. However, the voltage regulators on current Maple + Revs are rated up to only 16V, and due to the current draw + requirements of the board, operate properly only up to 12V. The + recommended maximum voltage you should apply is **12V**, and + potentially even lower depending upon the current draw requirements + of the application. Please see :ref:`Power Regulation on the Maple + ` for more information. .. _maple-nrst-pb4: -- cgit v1.2.3 From e51c8c38a44ee1734d3b2af949e45b8984629c87 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 5 Oct 2011 12:52:30 -0400 Subject: Hack: silence warnings about 'void'. Add a void cpp:type:: declaration to build-in-types.rst in order to silence the voluminous warnings about not knowing what type void is. Probably we should see if this is in the Sphinx bug tracker. Signed-off-by: Marti Bolivar --- source/lang/cpp/built-in-types.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/source/lang/cpp/built-in-types.rst b/source/lang/cpp/built-in-types.rst index 28e8cdc..f14dce5 100644 --- a/source/lang/cpp/built-in-types.rst +++ b/source/lang/cpp/built-in-types.rst @@ -86,8 +86,8 @@ Floating-Point Types 64-bit, IEEE-754 double-precision floating-point type. -Other Types ------------ +Miscellaneous Types +------------------- .. cpp:type:: voidFuncPtr @@ -98,3 +98,11 @@ Other Types .. cpp:type:: bool Boolean type. + +Other +----- + +.. cpp:type:: void + + Not really a type. To be honest with you, this only exists here to + silence warnings from our documentation build system. -- cgit v1.2.3 From ee1928e057e04bddd702a4869189c92700056340 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 7 Oct 2011 14:21:15 -0400 Subject: bootloader: Add link to Native bootloader binary. Signed-off-by: Marti Bolivar --- source/bootloader.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/source/bootloader.rst b/source/bootloader.rst index e3eb65e..23b0448 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -584,8 +584,6 @@ DFU pipe and bringing up the USB serial port. Flashing A Custom Bootloader ---------------------------- -.. FIXME [0.0.13] Update for Maple Native - .. warning:: This section is for users who want to put a fresh or custom bootloader on their board. It's possible to make a mistake in this process and e.g. render your Maple unable to communicate @@ -601,9 +599,6 @@ This means that you can **always** follow these instructions to put a new bootloader program on your board; it **doesn't matter** if there's already a copy of the Maple bootloader on it or not. -This section applies to Maple Rev 3 (or higher), Maple Mini, and Maple -RET6 Edition. - If you have a Maple Rev 1; you don't have a BUT button, and won't be able to follow these directions. A workaround is detailed in `this forum posting `_. @@ -629,6 +624,7 @@ In order to follow these instructions, you will need: - `Maple `_ - `Maple Mini `_ - `Maple RET6 Edition `_ +- `Maple Native `_ To flash a customized version of a LeafLabs bootloader, you can run (on a :ref:`suitably configured system `) the -- cgit v1.2.3 From 2e1cf62fa2e24c168300197974f061646a913f5e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 7 Oct 2011 14:45:49 -0400 Subject: libmaple/api/usart: Add usart_rx(). Signed-off-by: Marti Bolivar --- source/libmaple/api/usart.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/libmaple/api/usart.rst b/source/libmaple/api/usart.rst index 1575a8f..68f2c37 100644 --- a/source/libmaple/api/usart.rst +++ b/source/libmaple/api/usart.rst @@ -34,6 +34,7 @@ Functions .. doxygenfunction:: usart_disable .. doxygenfunction:: usart_disable_all .. doxygenfunction:: usart_foreach +.. doxygenfunction:: usart_rx .. doxygenfunction:: usart_tx .. doxygenfunction:: usart_putudec .. doxygenfunction:: usart_putc -- cgit v1.2.3 From 5051a512141f642f90f53f2749ddd8cc815226e4 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 7 Oct 2011 15:21:29 -0400 Subject: README: More on how to maintain releases. Signed-off-by: Marti Bolivar --- README | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/README b/README index 2fe5092..4cdf66f 100644 --- a/README +++ b/README @@ -310,11 +310,34 @@ It needs to be updated RIGHT AWAY, you say? Here's what you do: - Make your changes. -- Rebuild the docs (see the last two steps in "Cutting the Release"). +- Rebuild the docs (see the last two steps in "Cutting the Release") + and look at the changed pages. -- If your changes need to happen on the master branch, make them +- If your changes also need to happen on the master branch, make them appropriately. + Advice: git cherry-pick is your friend. Let's say you're on branch + "vX.Y.Z-maintenance", and you want to get commit C onto master: + + o---C vX.Y.Z-maintenance + / + -o---o---o---o master + + The recipe is: + + $ git checkout master + $ git cherry-pick C + + Which (if there are no conflicts) will result in: + + o---C vX.Y.Z-maintenance + / + -o---o---o---o---C' master + + Where C' performs the same changes as C. + - Push your fixes to GitHub. -- Distribute the updated docs. +- Distribute the updated docs. These are world-visible here: + + http://static.leaflabs.com/pub/leaflabs/maple-docs/ -- cgit v1.2.3 From 0b5fd1df1a87f240b9a93c4f46983ebcb9d71242 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 7 Oct 2011 17:41:30 -0400 Subject: configuration: Cleanups and tweaks. Start coloring visited links differently. I have no idea why that was disabled. Remove ' Documentation' from the HTML title. It's too long. Clean up some whitespace. Remove unused apilist.html and ancillary conf.py. Signed-off-by: Marti Bolivar --- source/_static/apilist.html | 5 ----- source/conf.py | 10 +++------- 2 files changed, 3 insertions(+), 12 deletions(-) delete mode 100644 source/_static/apilist.html diff --git a/source/_static/apilist.html b/source/_static/apilist.html deleted file mode 100644 index 556fcc9..0000000 --- a/source/_static/apilist.html +++ /dev/null @@ -1,5 +0,0 @@ -{# Filename: .static/apilist.html #} -{% set parents = parents.pop() %} -{% if parents %} -{{ parents.title }} -{% endif %} diff --git a/source/conf.py b/source/conf.py index 7380f8e..1e18f25 100644 --- a/source/conf.py +++ b/source/conf.py @@ -14,7 +14,6 @@ import sys, os - # 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. @@ -37,7 +36,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', 'breathe'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates', '_static'] +templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -132,7 +131,7 @@ html_theme_options = { 'relbarbgcolor' : 'green', 'headlinkcolor' : '#000000', 'linkcolor' : 'green', - 'visitedlinkcolor' : 'green', + #'visitedlinkcolor' : 'green', ## Font 'headfont' : 'Georgia', @@ -144,7 +143,7 @@ html_theme_options = { # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = project + ' v' + release + ' Documentation' +html_title = project + ' v' + release # A shorter title for the navigation bar. Default is the same as html_title. html_short_title = 'Index' @@ -172,13 +171,10 @@ html_last_updated_fmt = '%b %d, %Y' #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -# re-add commented line when custom template for api finished html_sidebars = { '**': ['globaltoc.html', 'searchbox.html'], - #'lang/api**':['searchbox.html', 'apilist.html'], } - # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} -- cgit v1.2.3 From f780ea927c32cf0fc72ab0e3f3fda1d4df644b29 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 8 Oct 2011 00:27:46 -0400 Subject: Redo appearance of top-level docs and pages. This is a fairly significant set of changes, aimed at improving the overall usability of the documentation. Add source/_templates/indexcontent.html, which is a Jinja template used to generate index.html. This mimics the Python docs' style of having a short, styled table as main index interface. We're doing this because people keep missing the board hardware pages that are below the fold. Hopefully this will make them (and other important pages) easier to find. The new file source/_static/index-style.css controls the presentation of the generated index.html. Move the contents of source/index.rst to source/contents.rst, and increase the toctree depths to 2. This increase has the ancillary benefit that secondary headers within the current page are displayed in the sidebar, which should aid navigation within the page. contents.rst is meant to be a contents in full, where users who know what they're looking for can go. The "Table of Contents" link on the sidebar points here. Add a new source/_static/leaflabs-docs.css. It's currently unused, but is the place where people should put CSS that wants to override the defaults. Modify source/_templates/layout.html to include aforementioned leaflabs-docs.css. Also tweak the behavior of the rootrellink block, which provides the breadcrumbs in page headers and footers. Change the titles of various top-level docs so they can be referenced from the toctrees in contents.rst directly. Having two names (one in the contents, one at the top of the page) has got to be confusing people. Make an exception for FAQ so that it appears in one line on the sidebar. Adjust conf.py to reflect all of these changes. Also: - Fix "Lucidia" -> "Lucida" typo - Get rid of intersphinx_mapping (we don't use it, and including it makes it impossible to build the docs offline). - Remove the logo from sidebar; it's big and ugly and serves no purpose. Signed-off-by: Marti Bolivar --- README | 7 ++- source/_static/index-style.css | 15 +++++ source/_static/leaflabs-docs.css | 1 + source/_templates/indexcontent.html | 112 ++++++++++++++++++++++++++++++++++++ source/_templates/layout.html | 10 +++- source/arm-gcc.rst | 4 +- source/conf.py | 12 ++-- source/contents.rst | 68 ++++++++++++++++++++++ source/ide.rst | 4 +- source/index.rst | 78 ------------------------- source/language.rst | 6 +- 11 files changed, 222 insertions(+), 95 deletions(-) create mode 100644 source/_static/index-style.css create mode 100644 source/_static/leaflabs-docs.css create mode 100644 source/_templates/indexcontent.html create mode 100644 source/contents.rst delete mode 100644 source/index.rst diff --git a/README b/README index 4cdf66f..f3839cd 100644 --- a/README +++ b/README @@ -110,9 +110,10 @@ Just point your web browser at the file build/html/index.html -It corresponds to the Sphinx file - - source/index.rst +For the most poart, the file build/html/foo.html is built from +source/foo.rst. (The index is an exception, because we needed to +hand-hack the HTML to get the "Contents at a Glance" section to look +nice). Read more about Sphinx and use the existing docs source as an example when writing yours. The directory tmpl/ contains template ReST files diff --git a/source/_static/index-style.css b/source/_static/index-style.css new file mode 100644 index 0000000..a0ef75c --- /dev/null +++ b/source/_static/index-style.css @@ -0,0 +1,15 @@ +/* Contents style */ + +.contents-table { + font-size: large; +} + +.contents-table ul, .contents-table li { + display: inline; +} + +.contents-table ul { + list-style-type: none; + margin: 0em; + padding-left: 0px; +} diff --git a/source/_static/leaflabs-docs.css b/source/_static/leaflabs-docs.css new file mode 100644 index 0000000..18f5bcc --- /dev/null +++ b/source/_static/leaflabs-docs.css @@ -0,0 +1 @@ +/* Any custom CSS you want applied goes here */ diff --git a/source/_templates/indexcontent.html b/source/_templates/indexcontent.html new file mode 100644 index 0000000..49e72b7 --- /dev/null +++ b/source/_templates/indexcontent.html @@ -0,0 +1,112 @@ +{# This file generates the top-level index.html file. We are very + obviously stealing from the Python docs's style ;). +#} + + +{% extends "layout.html" %} + + +{% set css_files = css_files + ["_static/index-style.css"] %} + + +{% set content_sep = "·" %} + + +{% block body %} +

    Index

    + +Welcome! This is the documentation for the LeafLabs Maple boards, +version {{ release }}. + +

    Read This First

    + +

    Just getting started? Try the Quickstart. Having problems? Check +out Troubleshooting and +the FAQ. Can't find what you want +here? Look on the LeafLabs +wiki. +

    + +

    Contents at a Glance

    + + + + + + + + + + +

    Getting Started

    + +

    Boards

    + +

    Programming

    + +

    Peripherals

    + +
    + +{% endblock %} diff --git a/source/_templates/layout.html b/source/_templates/layout.html index 4d92d33..2fd81ce 100644 --- a/source/_templates/layout.html +++ b/source/_templates/layout.html @@ -1,5 +1,11 @@ {% extends "!layout.html" %} + +{% set css_files = css_files + ["_static/leaflabs-docs.css"] %} + {% block rootrellink %} -
  • LeafLabs |
    • - {{ super() }} +
  • + + leaflabs.com + ·
    • +
  • {{ shorttitle }}{{ reldelim1 }}
    • {% endblock %} diff --git a/source/arm-gcc.rst b/source/arm-gcc.rst index 1d55d07..30667a2 100644 --- a/source/arm-gcc.rst +++ b/source/arm-gcc.rst @@ -1,8 +1,8 @@ .. _arm-gcc: -GCC for Maple -============= +GCC and libc +============ This document provides notes on using ``arm-none-eabi-gcc``, the `CodeSourcery `_ version of the GNU `GCC diff --git a/source/conf.py b/source/conf.py index 1e18f25..5b8f2d8 100644 --- a/source/conf.py +++ b/source/conf.py @@ -45,7 +45,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = 'contents' # General information about the project. project = u'Maple' @@ -135,7 +135,7 @@ html_theme_options = { ## Font 'headfont' : 'Georgia', - 'bodyfont' : 'Lucidia' + 'bodyfont' : 'Lucida' } # Add any paths that contain custom themes here, relative to this directory. @@ -150,7 +150,7 @@ html_short_title = 'Index' # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '_static/img/round_logo_60x60.png' +# html_logo = '_static/img/round_logo_60x60.png' # 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 @@ -177,7 +177,9 @@ html_sidebars = { # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +html_additional_pages = { + 'index': 'indexcontent.html' +} # If false, no module index is generated. #html_domain_indices = True @@ -259,7 +261,7 @@ man_pages = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +#intersphinx_mapping = {'http://docs.python.org/': None} # -- Options for breathe integration ------------------------------------------ diff --git a/source/contents.rst b/source/contents.rst new file mode 100644 index 0000000..63aebee --- /dev/null +++ b/source/contents.rst @@ -0,0 +1,68 @@ +.. _index: + +Contents in Full +================ + +.. _index-usage: + +**Getting Started** + +.. toctree:: + :maxdepth: 2 + + maple-quickstart + maple-ide-install + ide + unix-toolchain + +.. _index-maple-programming: + +**Programming** + +.. toctree:: + :maxdepth: 2 + + language + libraries + arduino-compatibility + libmaple + bootloader + troubleshooting + FAQ + arm-gcc + language-index + +.. _index-hardware: + +**Peripherals** + +.. toctree:: + :maxdepth: 2 + + adc + external-interrupts + fsmc + gpio + i2c + jtag + pwm + spi + timers + systick + usb + usart + +.. _index-boards: + +**Boards** + +.. toctree:: + :maxdepth: 2 + + hardware/maple.rst + hardware/maple-ret6.rst + hardware/maple-mini.rst + hardware/maple-native-beta.rst + +.. TODO [Maple Native] write/include upon finished Native release +.. hardware/maple-native.rst diff --git a/source/ide.rst b/source/ide.rst index 6e36e47..e6d49fc 100644 --- a/source/ide.rst +++ b/source/ide.rst @@ -1,7 +1,7 @@ .. _ide: -Maple IDE -========= +Using Maple IDE +=============== This page documents the basic functionality of the Maple IDE. Specifically, it describes the operation of the buttons on the main diff --git a/source/index.rst b/source/index.rst deleted file mode 100644 index e8f0277..0000000 --- a/source/index.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. _index: - -LeafLabs Documentation Index -============================ - -Welcome to the LeafLabs documentation! - -If you're setting up a board for the first time, try the -:ref:`quickstart `. If you're having problems, -check out the :ref:`troubleshooting ` and :ref:`FAQ -` pages. - -If you can't find what you're looking for here, try the `LeafLabs wiki -`_. - -.. _index-usage: - -**Usage Guides:** - -.. toctree:: - :maxdepth: 1 - - Quickstart - IDE Installation - IDE Usage - Command-Line Toolchain - -.. _index-maple-programming: - -**Maple Programming:** - -.. toctree:: - :maxdepth: 1 - - Language - Libraries - Arduino Compatibility - libmaple - Bootloader - Troubleshooting - FAQ - GCC and libc for Maple - Language Index - -.. _index-hardware: - -**Hardware Peripherals:** - -.. toctree:: - :maxdepth: 1 - - adc - external-interrupts - fsmc - gpio - i2c - jtag - pwm - spi - timers - systick - usb - usart - -.. _index-boards: - -**Board Hardware Documentation:** - -.. toctree:: - :maxdepth: 1 - - hardware/maple.rst - hardware/maple-ret6.rst - hardware/maple-mini.rst - hardware/maple-native-beta.rst - -.. TODO [Maple Native] write/include upon finished Native release -.. hardware/maple-native.rst diff --git a/source/language.rst b/source/language.rst index 1a8ef30..20827cc 100644 --- a/source/language.rst +++ b/source/language.rst @@ -2,9 +2,9 @@ .. _language: -========================== - Maple Language Reference -========================== +==================== + Language Reference +==================== The Maple can be programmed in the `Wiring `_ language, which is the same -- cgit v1.2.3 From 8fbb635180b32096ce4f05c2ac2a88a5d3c3ad46 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sat, 8 Oct 2011 00:50:14 -0400 Subject: language-index.rst: Fix outdated information. Signed-off-by: Marti Bolivar --- source/language-index.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/source/language-index.rst b/source/language-index.rst index 6c20605..5e4c609 100644 --- a/source/language-index.rst +++ b/source/language-index.rst @@ -16,11 +16,7 @@ programmers familiar with the Arduino language. with different kinds of hardware. - If you're looking for something from the C standard library (like - ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler - ` used to compile your programs is configured to link - against `newlib `_, and allows the - use of any of its header files. However, dynamic memory allocation - (``malloc()``, etc.) is not available. + ``atoi()``, for instance), see :ref:`this FAQ `. - If you're looking for pointers to low-level details, see the :ref:`Language Recommended Reading -- cgit v1.2.3 From 01eb3ed1df0312c7f021bb257fa359dce68ce850 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 20 Oct 2011 22:31:24 -0400 Subject: Tweak styling of Contents at a Glance. Signed-off-by: Marti Bolivar --- source/_static/index-style.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/_static/index-style.css b/source/_static/index-style.css index a0ef75c..d7c42b3 100644 --- a/source/_static/index-style.css +++ b/source/_static/index-style.css @@ -8,6 +8,10 @@ display: inline; } +.contents-table td { + padding: 0em 1em 0em; +} + .contents-table ul { list-style-type: none; margin: 0em; -- cgit v1.2.3 From 9fe5b2f1128afe7561f2493a189b53cc6fa5fbae Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 10 Feb 2012 20:51:30 -0500 Subject: Fix MCU name on Maple Mini hardware page. Signed-off-by: Marti Bolivar --- source/hardware/maple-mini.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst index 58e394d..36702dd 100644 --- a/source/hardware/maple-mini.rst +++ b/source/hardware/maple-mini.rst @@ -15,7 +15,7 @@ breadboard. Technical Specifications ------------------------ -* MCU: :ref:`STM32F103RCBT6 `, a 32-bit ARM Cortex +* MCU: :ref:`STM32F103CBT6 `, a 32-bit ARM Cortex M3 microprocessor * Clock Speed: **72 MHz** * **128 KB Flash** and **20 KB SRAM** -- cgit v1.2.3 From b071b7bd4b7c7a0b02d49f0e486c29b9caf79700 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 6 May 2012 21:46:15 -0400 Subject: README: fix typo Signed-off-by: Marti Bolivar --- README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README b/README index f3839cd..692d79d 100644 --- a/README +++ b/README @@ -110,7 +110,7 @@ Just point your web browser at the file build/html/index.html -For the most poart, the file build/html/foo.html is built from +For the most part, the file build/html/foo.html is built from source/foo.rst. (The index is an exception, because we needed to hand-hack the HTML to get the "Contents at a Glance" section to look nice). -- cgit v1.2.3 From 373b21acec802a0d1575862ae677fa9aceae31da Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 6 May 2012 21:47:01 -0400 Subject: README: tweak sentence about the template files Signed-off-by: Marti Bolivar --- README | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README b/README index 692d79d..c11fc72 100644 --- a/README +++ b/README @@ -117,8 +117,8 @@ nice). Read more about Sphinx and use the existing docs source as an example when writing yours. The directory tmpl/ contains template ReST files -you should modify when creating a new page, in order to keep the style -consistent. +you should sometimes use when creating a new page, in order to keep +the style consistent. The file source/conf.py is the Sphinx configuration file; you can go read it for more information about our setup. -- cgit v1.2.3 From f6dbfbd376da7ed410b2a6d88c1a074160457f46 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 6 May 2012 22:42:08 -0400 Subject: Split up README into separate files. The README is pretty long (over 1500 words). Nobody's going to read that. Make it short, and put the long-winded bullshit into other files that are clearly labeled as being for docs maintainers. Signed-off-by: Marti Bolivar --- README | 350 +++---------------------------------------------- README-building.txt | 103 +++++++++++++++ README-maintainers.txt | 209 +++++++++++++++++++++++++++++ 3 files changed, 327 insertions(+), 335 deletions(-) create mode 100644 README-building.txt create mode 100644 README-maintainers.txt diff --git a/README b/README index c11fc72..60fb888 100644 --- a/README +++ b/README @@ -1,344 +1,24 @@ -Introduction ------------- - -This repository contains reStructuredText (reST) source files used to -generate the documentation for LeafLabs' libmaple and Maple IDE -projects. For more information on these projects, see their GitHub -pages: - - https://github.com/leaflabs/libmaple - https://github.com/leaflabs/maple-ide - -While the two projects are developed separately, they are released in -lockstep, and Maple IDE depends upon libmaple. (libmaple doesn't -depend on Maple IDE). - -The generated documentation for the latest libmaple and Maple IDE -release is available online in HTML form: +This repository contains source files used to generate the +documentation for LeafLabs' libmaple and Maple IDE projects [*]. The +HTML documentation generated from these sources is available online: http://leaflabs.com/docs/ -The web interface is the recommended way for users to read the -documentation. Older versions are available as well: - - http://static.leaflabs.com/pub/leaflabs/maple-docs/ - -This file contains instructions for generating the HTML files. It -also contains guidelines for the documentation's maintainers. - -About the Documentation ------------------------ - -The docs are written in Sphinx's extensions to reStructuredText -(reST). You can read more about Sphinx here: - - http://sphinx.pocoo.org/tutorial.html - -Much of the documentation is pulled out of the libmaple source code. -libmaple documents itself using Doxygen: - - http://doxygen.org - -We use a Sphinx plugin called Breathe to parse Doxygen's XML output -into a form usable by Sphinx. You can read more about Breathe here: - - http://michaeljones.github.com/breathe/ - -Documentation Build Steps -------------------------- - -First, you will need to install some dependencies (Doxygen, Sphinx, -and Breathe). - -1. You need a recent-ish version of Doxygen in your PATH: - - http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc - -2. Install Breathe, which does Doxygen-to-Sphinx conversion: - - Read/write version (for LeafLabs developers): - - $ git clone git@github.com:leaflabs/breathe.git - - Read-only version (for non-LeafLabs developers): - - $ git clone git://github.com/leaflabs/breathe.git - - After that's done, set an environment variable BREATHE_HOME to - point to where you downloaded it. Something like this on bash: - - $ export BREATHE_HOME=/path/to/breathe/repo/ - - (You'll want to put this in your shell startup script). - -3. Install Sphinx. - - From source or .egg: - - http://pypi.python.org/pypi/Sphinx#downloads - - Via easy_install: - - $ sudo easy_install -U Sphinx - - You need Sphinx version >= 1.0.6. - -You are now ready to build the documentation. First, you'll produce -Doxygen XML output, then you can generate the HTML documentation. - -1. Before the first time you run Sphinx (and any time the Doxygen - comments in the libmaple source code are changed), you'll need to - rebuild libmaple's Doxygen XML output. That is, from within the - libmaple repository (i.e., NOT THIS REPOSITORY), run: - - $ make doxygen - -2. Finally, you can build the documentation (in this folder): - - $ make html - - On Windows, use the batch file make.bat instead. - - As of 8 September 2011, building the docs generates a bunch of - errors/warnings. Most of these are spurious and appear to be - Breathe's fault. C'est la vie. - -Reading and Modifying the Documentation ---------------------------------------- - -Just point your web browser at the file - - build/html/index.html - -For the most part, the file build/html/foo.html is built from -source/foo.rst. (The index is an exception, because we needed to -hand-hack the HTML to get the "Contents at a Glance" section to look -nice). - -Read more about Sphinx and use the existing docs source as an example -when writing yours. The directory tmpl/ contains template ReST files -you should sometimes use when creating a new page, in order to keep -the style consistent. - -The file source/conf.py is the Sphinx configuration file; you can go -read it for more information about our setup. - -All of the documentation which isn't pulled out of source code -comments lives in source/. The directory source/_static/ is for -static content (like style sheets); source/_templates/ is meant to -contain Sphinx templates. - -The remaining sections describe what to do under various circumstances -when modifying or building the docs. - -Adding a New Board ------------------- - -Adding documentation for a new board is not just a matter of shoving a -file for it into source/hardware/! - -- Various places in the docs link to particular kinds of pin maps for - each board. When you add a new board, you must update these as - well. Here's the list; please keep it current (files are relative - to the source/ directory): - - * external-interrupts.rst: EXTI line pin maps - * timers.rst: timer pin maps - * adc.rst: low-noise ADC banks - * usart.rst: USART pin maps - * gpio.rst: master pin maps - * bootloader.rst: flashing a custom bootloader - -- The quickstart document may not explain how to use the new board. - If the board is different enough, a new, special-purpose quickstart - may need to be written for it. Therefore, read the quickstart in - its entirety and update it appropriately. - - Take this step seriously. The quickstart is the first thing users - read when starting out, and first impressions matter. - -Building Documentation for a Release ------------------------------------- - -This is the procedure to follow when building the documentation for a -versioned release (as such, it's mostly intended for LeafLabs people). +The above URL is the recommended way for users to read the +documentation. The docs for the latest release are always available +there. -Read the following "Background" section if you've never done this -before (or haven't done it in a while; things change). Then do the -steps in the "Preparation" and "Cutting the Release" sections that -follow it. +Older versions are here: -If you're bugfixing the docs for a release that's already been -shipped, skip to "Maintaining a Release", below. - - ~~~~~~~~~~ - Background - ~~~~~~~~~~ - -As a lightweight form of issue tracking, the documentation sources are -sprinkled (not to say "littered") with comments that begin with FIXME -or TODO, optionally followed by [milestone]. - -Here's a hypothetical example: - - .. TODO [1.4.0] Replace this section; new API is incompatible with 1.3.7 - -This means you should replace the docs section following the comment -before you build the HTML for version 1.4.0. - -Here's a command line you can use on OS X and Linux to list the TODOs -in the documentation sources (run it from the same directory as this -README): - - $ find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)' - -You can use the following to temporarily alias the above mouthful to -'todos': - - $ alias todos="find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)'" - -Then you can just run - - $ todos - -to measure the joy that awaits you. - -Windows users: I'm not sure what the equivalent of grep is on your -system. If you're using Git, I presume you've got a Bash shell -available to you due to msysgit; try running the above commands there. - -BE ADVISED: that only finds the comments embedded within .rst files. -You also need to check for these in source/conf.py; there may be -others. If you have ack (which might be called "ack-grep" on your -system) installed, you can instead use - - $ ack --type-set rst=.rst --type-set txt=.txt --ignore-dir=build '(FIXME|TODO)' - -to get the same output, but for all the file types we care about. - - ~~~~~~~~~~~ - Preparation - ~~~~~~~~~~~ - -- FINISH THE FIXMEs/TODOs FOR THE CURRENT RELEASE! - - You may violate assumptions made elsewhere in the documentation if - you don't. This can lead to incoherent or incorrect documentation, - which is usually worse than none at all. - - If the release you're building is vA.B.C, you can see the relevant - TODOs with: - - $ todos | grep A\.B\.C - - If you find that you really can't finish the TODO, you should bump - the version number in the comment. Don't do this out of laziness. - Seriously, don't. We may have made promises to the users about what - would happen when, and you might be breaking them. - -- Pick the low-hanging fruit on any other FIXMEs/TODOs. - -- Ask Git to tell you what's happened since the most recent libmaple - release, and make sure that any major, potentially - backwards-incompatible, etc. changes are appropriately documented. - - You can use three dots ("...") between the git tags for those - releases in concert with "git log --oneline" to do this. - - For instance, from the libmaple repository, you can use the - following to tell you what happened in between 0.0.9 and 0.0.10: - - $ git log --oneline 0.0.9...0.0.10 - - As an example of what the output might cause you to do, consider the - following line (which appears in the output for 0.0.9...0.0.10): - - 4941335 Adding rcc_dev_clk(), an accessor for a peripheral's clock line. - - Did the author of that commit (or some other interested party) - remember to pull in the documentation for rcc_dev_clk() into the - libmaple API page for rcc.h? Go check! - -- Do something similar for Maple IDE. The IDE changes a lot more - slowly, so there should be less to do. - - ~~~~~~~~~~~~~~~~~~~ - Cutting the Release - ~~~~~~~~~~~~~~~~~~~ - -- Make a release branch in Git. For release A.B.C, call it - vA.B.C-maintenance. You spell that - - $ git checkout -b vA.B.C-maintenance - - DON'T MAKE A TAG. There are inevitably mistakes in the docs, some - of which will be noticed and corrected, making a fixed tag useless. - When you correct the errors, you'll need to update this branch, - possibly also cherry-picking or otherwise adding into master. See - "Maintaining the Release", below. - -- Do all the TODOs which must happen for _every_ release. (These are - distinct from the ones that must happen for some _particular_ - release). You can find most of these with - - $ todos | grep RELEASE - - However, you'll also need to check source/conf.py, as e.g. a - release's configuration file needs to have a version entered into - it. - - Don't forget to commit your changes. - -- Run "$ make mrproper" from the libmaple directory, and "$ make - clean" from this directory, in order to wipe out old docs. - -- Finally, you can actually build the docs. "$ make doxygen" from - libmaple followed by "$ make html" from here. The sources you want - will be in build/html. Wooo! You're done! Distribute the results - appropriately (e.g. by bundling them with the IDE release). - - Don't forget to push the release branch to the leaflabs-docs repo on - GitHub. - -Maintaining a Release ---------------------- - -So a released version's documentation contains unforgivable lies, huh? -It needs to be updated RIGHT AWAY, you say? Here's what you do: - -- Check out the release branch for the version of the docs you care - about (see "Cutting the Release", above). - -- Make your changes. - -- Rebuild the docs (see the last two steps in "Cutting the Release") - and look at the changed pages. - -- If your changes also need to happen on the master branch, make them - appropriately. - - Advice: git cherry-pick is your friend. Let's say you're on branch - "vX.Y.Z-maintenance", and you want to get commit C onto master: - - o---C vX.Y.Z-maintenance - / - -o---o---o---o master - - The recipe is: - - $ git checkout master - $ git cherry-pick C - - Which (if there are no conflicts) will result in: - - o---C vX.Y.Z-maintenance - / - -o---o---o---o---C' master + http://static.leaflabs.com/pub/leaflabs/maple-docs/ - Where C' performs the same changes as C. +The file README-building.txt explains how to build the HTML docs. -- Push your fixes to GitHub. +The file README-maintainers.txt contains important information for +maintainers of the documentation (e.g. how to add docs for a new +board, how to cut a release version of the docs, etc.). -- Distribute the updated docs. These are world-visible here: +[*] libmaple and Maple IDE themselves are in separate repositories: - http://static.leaflabs.com/pub/leaflabs/maple-docs/ + https://github.com/leaflabs/libmaple + https://github.com/leaflabs/maple-ide diff --git a/README-building.txt b/README-building.txt new file mode 100644 index 0000000..9a1a1ac --- /dev/null +++ b/README-building.txt @@ -0,0 +1,103 @@ +This file explains how to build the HTML documentation. As such, it's +probably only useful to LeafLabs developers. Users can read the HTML +for the latest release here: + + http://leaflabs.com/docs/ + +Install Dependencies +-------------------- + +First, you will need to install some dependencies (Doxygen, Sphinx, +and Breathe). + +1. Much of the documentation is pulled out of the libmaple source + code's Doxygen comments, so you need a recent-ish version of + Doxygen in your PATH: + + http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc + +2. Documentation not taken from the libmaple sources is written in + Sphinx's extensions to the reStructuredText (reST) markup language. + (More about Sphinx: http://sphinx.pocoo.org/tutorial.html). + + These are your choices for how to install Sphinx: + + - From source or .egg: + http://pypi.python.org/pypi/Sphinx#downloads + + - Via easy_install: + $ sudo easy_install -U Sphinx + + You need Sphinx version >= 1.0.6. + +3. We use a Sphinx plugin called Breathe to parse Doxygen's XML output + into a form usable by Sphinx. (More about Breathe: + http://michaeljones.github.com/breathe/). + + LeafLabs sometimes patches Breathe for the purposes of building our + docs, so clone the LeafLabs Breathe tree from GitHub (somewhere + else on your system, NOT in the leaflabs-docs repo): + + - LeafLabs developers, clone with push permissions: + $ git clone git@github.com:leaflabs/breathe.git + + - Everyone else, clone without them: + $ git clone git://github.com/leaflabs/breathe.git + + After that's done, set an environment variable BREATHE_HOME to + point to your clone. Something like this in Bash: + + $ export BREATHE_HOME=/path/to/breathe/repo/ + + (You'll want to put this in your shell startup script.) + +Build the Docs +-------------- + +You are finally ready to build the documentation. First, you'll +produce Doxygen XML output, then you can generate the final HTML docs. + +1. Before the first time you run Sphinx (and any time the Doxygen + comments in the libmaple source code are changed), you'll need to + re-run doxygen on libmaple. + + $ cd /path/to/libmaple + $ make doxygen + + Doxygen will yell at you a lot; it's generally safe to ignore it. + +2. Finally, you can build the HTML (in the leaflabs-docs repository): + + $ cd /path/to/leaflabs-docs + $ make html + + On Windows, you can supposedly use the batch file make.bat instead. + + Breathe will yell at you a lot; it's often safe to ignore this, + too. C'est la vie. + +Read and Modify the Docs +------------------------ + +Point your web browser at the file + + build/html/index.html + +For the most part, the file build/html/foo.html is built from +source/foo.rst. (The index is an exception, because we needed to +hand-hack the HTML to get the "Contents at a Glance" section to look +nice). + +All of the documentation which isn't pulled out of libmaple's Doxygen +comments lives in source/. The directory source/_static/ is for +static content (like style sheets); source/_templates/ is meant to +contain Sphinx templates. + +Read more about Sphinx and use the existing leaflabs-docs source for +examples when writing new docs. The directory tmpl/ contains template +ReST files you should sometimes use when creating a page that follows +a pattern (like a libmaple API page), in order to keep the style +consistent. + +The file source/conf.py is the Sphinx configuration file; you can go +read it for more information about our setup. diff --git a/README-maintainers.txt b/README-maintainers.txt new file mode 100644 index 0000000..90ebfb5 --- /dev/null +++ b/README-maintainers.txt @@ -0,0 +1,209 @@ +This file contains information useful for the documentation's +maintainers. As such, it's probably only useful to LeafLabs +developers. Users can read the HTML for the latest release here: + + http://leaflabs.com/docs/ + +Things you can learn how to do from this file: + +- Cut a release version +- Fix errors in/otherwise maintain the current docs release +- Add docs for a new board + +Building Documentation for a Release +------------------------------------ + +This is the procedure to follow when building the documentation for a +versioned release. + +Read the following "Background" section if you've never done this +before (or haven't done it in a while; things change). Then do the +steps in the "Preparation" and "Cutting the Release" sections that +follow it. + +If you're bugfixing the docs for a release that's already been +shipped, skip to "Maintaining a Release", below. + + ~~~~~~~~~~ + Background + ~~~~~~~~~~ + +As a lightweight form of issue tracking, the documentation sources are +sprinkled (not to say "littered") with comments that begin with FIXME +or TODO, optionally followed by [milestone]. + +Here's a hypothetical example: + + .. TODO [1.4.0] Replace this section; new API is incompatible with 1.3.7 + +This means you should replace the docs section following the comment +before you build the HTML for version 1.4.0. + +Here's a command line you can use to list the TODOs in the +documentation sources (run it from the top-level directory in the +repository): + + $ git grep -n 'FIXME\|TODO' + +You can use the following to temporarily alias the above mouthful to +'todos': + + $ alias todos="git grep -n 'FIXME\|TODO'" + +Then you can just run + + $ todos + +to measure the joy that awaits you. + + ~~~~~~~~~~~ + Preparation + ~~~~~~~~~~~ + +- FINISH THE FIXMEs/TODOs FOR THE CURRENT RELEASE! + + You may violate assumptions made elsewhere in the documentation if + you don't. This can lead to incoherent or incorrect documentation, + which is usually worse than none at all. + + If the release you're building is vA.B.C, you can see the relevant + TODOs with: + + $ todos | grep A\.B\.C + + If you find that you really can't finish the TODO, you should bump + the version number in the comment. Don't do this out of laziness. + Seriously, don't. We may have made promises to the users about what + would happen when, and you might be breaking them. + +- Pick the low-hanging fruit on any other FIXMEs/TODOs. + +- Ask Git to tell you what's happened since the most recent libmaple + release, and make sure that any major, potentially + backwards-incompatible, etc. changes are appropriately documented. + + You can use three dots ("...") between the git tags for those + releases in concert with "git log --oneline" to do this. + + For instance, from the libmaple repository, you can use the + following to tell you what happened in between 0.0.9 and 0.0.10: + + $ git log --oneline 0.0.9...0.0.10 + + As an example of what the output might cause you to do, consider the + following line (which appears in the output for 0.0.9...0.0.10): + + 4941335 Adding rcc_dev_clk(), an accessor for a peripheral's clock line. + + Did the author of that commit (or some other interested party) + remember to pull in the documentation for rcc_dev_clk() into the + libmaple API page for rcc.h? Go check! + +- Do something similar for Maple IDE. The IDE changes a lot more + slowly, so there should be less to do. + + ~~~~~~~~~~~~~~~~~~~ + Cutting the Release + ~~~~~~~~~~~~~~~~~~~ + +- Make a release branch in Git. For release A.B.C, call it + vA.B.C-maintenance. You spell that + + $ git checkout -b vA.B.C-maintenance + + DON'T MAKE A TAG. There are inevitably mistakes in the docs, some + of which will be noticed and corrected, making a fixed tag useless. + When you correct the errors, you'll need to update this branch, + possibly also cherry-picking or otherwise adding into master. See + "Maintaining the Release", below. + +- Do all the TODOs which must happen for _every_ release. (These are + distinct from the ones that must happen for some _particular_ + release). You can find most of these with + + $ todos | grep RELEASE + + However, you'll also need to check source/conf.py, as e.g. a + release's configuration file needs to have a version entered into + it. + + DON'T FORGET TO COMMIT YOUR CHANGES. + +- Run "$ make mrproper" from the libmaple directory, and "$ make + clean" from this directory, in order to wipe out existing old docs. + +- Finally, you can actually build the docs. (See README-building.txt + for instructions if you've never done this before.) + + DON'T FORGET TO PUSH THE RELEASE BRANCH TO GITHUB. + +Maintaining a Release +--------------------- + +So a released version's documentation contains unforgivable lies, huh? +It needs to be updated RIGHT AWAY, you say? Here's what you do: + +- Check out the release branch for the version of the docs you care + about (see "Cutting the Release", above). + +- Make your changes. + +- Rebuild the docs (see the last two steps in "Cutting the Release") + and look at the changed pages. + +- If your changes also need to happen on the master branch, make them + appropriately. + + Advice: git cherry-pick is your friend. Let's say you're on branch + "vX.Y.Z-maintenance", and you want to get commit C onto master: + + o---C vX.Y.Z-maintenance + / + -o---o---o---o master + + The recipe is: + + $ git checkout master + $ git cherry-pick C + + Which (if there are no conflicts) will result in: + + o---C vX.Y.Z-maintenance + / + -o---o---o---o---C' master + + Where C' performs the same changes as C. + +- Push your fixes to GitHub. + +- Distribute the updated docs. These are world-visible here: + + http://static.leaflabs.com/pub/leaflabs/maple-docs/ + +Adding a New Board +------------------ + +Adding documentation for a new board is not just a matter of shoving a +file for it into source/hardware/! + +Other things you must consider: + +- Various places in the docs link to particular kinds of pin maps for + each board. When you add a new board, you must update these as + well. Here's the list; please keep it current (files are relative + to the source/ directory): + + * external-interrupts.rst: EXTI line pin maps + * timers.rst: timer pin maps + * adc.rst: low-noise ADC banks + * usart.rst: USART pin maps + * gpio.rst: master pin maps + * bootloader.rst: flashing a custom bootloader + +- The quickstart document may not explain how to use the new board. + If the board is different enough, a new, special-purpose quickstart + may need to be written for it. Therefore, read the quickstart in + its entirety and update it appropriately. + + Take this step seriously. The quickstart is the first thing users + read when starting out, and first impressions matter. -- cgit v1.2.3 From 2eaeea8aaec50b7506b5686c5a8da8671f0133c4 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Sun, 6 May 2012 22:51:38 -0400 Subject: index: Use non-breaking space when appropriate. We don't want e.g. "Installing Maple IDE" getting a line-break between "Maple" and "IDE". Signed-off-by: Marti Bolivar --- source/_templates/indexcontent.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_templates/indexcontent.html b/source/_templates/indexcontent.html index 49e72b7..18cfe5c 100644 --- a/source/_templates/indexcontent.html +++ b/source/_templates/indexcontent.html @@ -37,9 +37,9 @@ wiki.