diff options
231 files changed, 21803 insertions, 0 deletions
diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..0187b3d --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +build/ +*~ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..5255525 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,134 @@ +# Makefile for LeafLabs documentation (automatically generated by +# Sphinx). + +# 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 <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " 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." + +doxygen: + @echo "Wrong! You need to run this from within libmaple!" + false diff --git a/docs/README b/docs/README new file mode 100644 index 0000000..60fb888 --- /dev/null +++ b/docs/README @@ -0,0 +1,24 @@ +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 above URL is the recommended way for users to read the +documentation. The docs for the latest release are always available +there. + +Older versions are here: + + http://static.leaflabs.com/pub/leaflabs/maple-docs/ + +The file README-building.txt explains how to build the HTML docs. + +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.). + +[*] libmaple and Maple IDE themselves are in separate repositories: + + https://github.com/leaflabs/libmaple + https://github.com/leaflabs/maple-ide diff --git a/docs/README-building.txt b/docs/README-building.txt new file mode 100644 index 0000000..de4a7f7 --- /dev/null +++ b/docs/README-building.txt @@ -0,0 +1,105 @@ +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 + +4. After that's done, set environment variables LIB_MAPLE_HOME to + point to libmaple, and BREATHE_HOME to point to Breathe. Something + like this in Bash: + + $ export LIB_MAPLE_HOME=/path/to/libmaple/repo/ + $ export BREATHE_HOME=/path/to/breathe/repo/ + + (You'll want 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/docs/README-maintainers.txt b/docs/README-maintainers.txt new file mode 100644 index 0000000..48e8e5c --- /dev/null +++ b/docs/README-maintainers.txt @@ -0,0 +1,215 @@ +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. + +- Run "$ make doxygen" from the libmaple directory, and copy its + doxygen/xml directory to doxygen/xml in this directory, and commit + it in the vA.B.C-maintenance branch. + + (This makes later maintenance commits easier, and keeps a single + +- 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. diff --git a/docs/copy-to-ide b/docs/copy-to-ide new file mode 100755 index 0000000..6cd4bdd --- /dev/null +++ b/docs/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 diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..1833a4b --- /dev/null +++ b/docs/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 ^<target^>` where ^<target^> is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. 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/docs/source/_static/.gitignore b/docs/source/_static/.gitignore new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/source/_static/.gitignore diff --git a/docs/source/_static/breathe.css b/docs/source/_static/breathe.css new file mode 100644 index 0000000..d86028c --- /dev/null +++ b/docs/source/_static/breathe.css @@ -0,0 +1 @@ +/* This is a dummy css file to prevent 404 errors */ diff --git a/docs/source/_static/img/blinky-to-flash.png b/docs/source/_static/img/blinky-to-flash.png Binary files differnew file mode 100644 index 0000000..0320c5b --- /dev/null +++ b/docs/source/_static/img/blinky-to-flash.png diff --git a/docs/source/_static/img/blinky.png b/docs/source/_static/img/blinky.png Binary files differnew file mode 100644 index 0000000..bda4cee --- /dev/null +++ b/docs/source/_static/img/blinky.png diff --git a/docs/source/_static/img/button-new.png b/docs/source/_static/img/button-new.png Binary files differnew file mode 100644 index 0000000..3fd98be --- /dev/null +++ b/docs/source/_static/img/button-new.png diff --git a/docs/source/_static/img/button-open.png b/docs/source/_static/img/button-open.png Binary files differnew file mode 100644 index 0000000..466fc10 --- /dev/null +++ b/docs/source/_static/img/button-open.png diff --git a/docs/source/_static/img/button-save.png b/docs/source/_static/img/button-save.png Binary files differnew file mode 100644 index 0000000..7eba286 --- /dev/null +++ b/docs/source/_static/img/button-save.png diff --git a/docs/source/_static/img/button-serial-monitor.png b/docs/source/_static/img/button-serial-monitor.png Binary files differnew file mode 100644 index 0000000..aec9741 --- /dev/null +++ b/docs/source/_static/img/button-serial-monitor.png diff --git a/docs/source/_static/img/button-stop.png b/docs/source/_static/img/button-stop.png Binary files differnew file mode 100644 index 0000000..4812ae9 --- /dev/null +++ b/docs/source/_static/img/button-stop.png diff --git a/docs/source/_static/img/button-upload.png b/docs/source/_static/img/button-upload.png Binary files differnew file mode 100644 index 0000000..0f41eeb --- /dev/null +++ b/docs/source/_static/img/button-upload.png diff --git a/docs/source/_static/img/button-verify.png b/docs/source/_static/img/button-verify.png Binary files differnew file mode 100644 index 0000000..95abeb8 --- /dev/null +++ b/docs/source/_static/img/button-verify.png diff --git a/docs/source/_static/img/codeblocks_build.png b/docs/source/_static/img/codeblocks_build.png Binary files differnew file mode 100644 index 0000000..c98bcdc --- /dev/null +++ b/docs/source/_static/img/codeblocks_build.png diff --git a/docs/source/_static/img/codeblocks_makefile.png b/docs/source/_static/img/codeblocks_makefile.png Binary files differnew file mode 100644 index 0000000..a0ef21f --- /dev/null +++ b/docs/source/_static/img/codeblocks_makefile.png diff --git a/docs/source/_static/img/codeblocks_maketargets.png b/docs/source/_static/img/codeblocks_maketargets.png Binary files differnew file mode 100644 index 0000000..bbb68cb --- /dev/null +++ b/docs/source/_static/img/codeblocks_maketargets.png diff --git a/docs/source/_static/img/codeblocks_newproject.png b/docs/source/_static/img/codeblocks_newproject.png Binary files differnew file mode 100644 index 0000000..8d08d1f --- /dev/null +++ b/docs/source/_static/img/codeblocks_newproject.png diff --git a/docs/source/_static/img/github-clone-in-windows.png b/docs/source/_static/img/github-clone-in-windows.png Binary files differnew file mode 100644 index 0000000..41d76d1 --- /dev/null +++ b/docs/source/_static/img/github-clone-in-windows.png diff --git a/docs/source/_static/img/ide-blinky.png b/docs/source/_static/img/ide-blinky.png Binary files differnew file mode 100644 index 0000000..3cccdb4 --- /dev/null +++ b/docs/source/_static/img/ide-blinky.png diff --git a/docs/source/_static/img/jtag-wiring.png b/docs/source/_static/img/jtag-wiring.png Binary files differnew file mode 100644 index 0000000..8f31f99 --- /dev/null +++ b/docs/source/_static/img/jtag-wiring.png diff --git a/docs/source/_static/img/osx-network-prefs-unconfigured.png b/docs/source/_static/img/osx-network-prefs-unconfigured.png Binary files differnew file mode 100644 index 0000000..70d2fa0 --- /dev/null +++ b/docs/source/_static/img/osx-network-prefs-unconfigured.png diff --git a/docs/source/_static/img/osx-unconfigured-popup.png b/docs/source/_static/img/osx-unconfigured-popup.png Binary files differnew file mode 100644 index 0000000..a43ad57 --- /dev/null +++ b/docs/source/_static/img/osx-unconfigured-popup.png diff --git a/docs/source/_static/img/round_logo_32x32.ico b/docs/source/_static/img/round_logo_32x32.ico Binary files differnew file mode 100644 index 0000000..29fb2bf --- /dev/null +++ b/docs/source/_static/img/round_logo_32x32.ico diff --git a/docs/source/_static/img/round_logo_60x60.png b/docs/source/_static/img/round_logo_60x60.png Binary files differnew file mode 100644 index 0000000..dacd36a --- /dev/null +++ b/docs/source/_static/img/round_logo_60x60.png diff --git a/docs/source/_static/img/serial-monitor.png b/docs/source/_static/img/serial-monitor.png Binary files differnew file mode 100644 index 0000000..6162dab --- /dev/null +++ b/docs/source/_static/img/serial-monitor.png diff --git a/docs/source/_static/img/serial-port-mac.png b/docs/source/_static/img/serial-port-mac.png Binary files differnew file mode 100644 index 0000000..b3a1989 --- /dev/null +++ b/docs/source/_static/img/serial-port-mac.png diff --git a/docs/source/_static/img/serial-port-ubuntu.png b/docs/source/_static/img/serial-port-ubuntu.png Binary files differnew file mode 100644 index 0000000..8038e41 --- /dev/null +++ b/docs/source/_static/img/serial-port-ubuntu.png diff --git a/docs/source/_static/img/serial-port-win.png b/docs/source/_static/img/serial-port-win.png Binary files differnew file mode 100644 index 0000000..90dc1c4 --- /dev/null +++ b/docs/source/_static/img/serial-port-win.png diff --git a/docs/source/_static/img/upload-button.png b/docs/source/_static/img/upload-button.png Binary files differnew file mode 100644 index 0000000..20a663f --- /dev/null +++ b/docs/source/_static/img/upload-button.png diff --git a/docs/source/_static/img/verify-success.png b/docs/source/_static/img/verify-success.png Binary files differnew file mode 100644 index 0000000..6928674 --- /dev/null +++ b/docs/source/_static/img/verify-success.png diff --git a/docs/source/_static/img/verify_button.png b/docs/source/_static/img/verify_button.png Binary files differnew file mode 100644 index 0000000..37100db --- /dev/null +++ b/docs/source/_static/img/verify_button.png diff --git a/docs/source/_static/img/win7-copy-arm-bin-address.png b/docs/source/_static/img/win7-copy-arm-bin-address.png Binary files differnew file mode 100644 index 0000000..a3886d1 --- /dev/null +++ b/docs/source/_static/img/win7-copy-arm-bin-address.png diff --git a/docs/source/_static/img/win7-copy-python-address.png b/docs/source/_static/img/win7-copy-python-address.png Binary files differnew file mode 100644 index 0000000..34d3022 --- /dev/null +++ b/docs/source/_static/img/win7-copy-python-address.png diff --git a/docs/source/_static/img/win7-github-open-in-explorer.png b/docs/source/_static/img/win7-github-open-in-explorer.png Binary files differnew file mode 100644 index 0000000..8320a90 --- /dev/null +++ b/docs/source/_static/img/win7-github-open-in-explorer.png diff --git a/docs/source/_static/img/win7-python-arm-bin-path.png b/docs/source/_static/img/win7-python-arm-bin-path.png Binary files differnew file mode 100644 index 0000000..8dcc8ed --- /dev/null +++ b/docs/source/_static/img/win7-python-arm-bin-path.png diff --git a/docs/source/_static/img/win7-python-path.png b/docs/source/_static/img/win7-python-path.png Binary files differnew file mode 100644 index 0000000..8898a9e --- /dev/null +++ b/docs/source/_static/img/win7-python-path.png diff --git a/docs/source/_static/img/win7-python-prompt.png b/docs/source/_static/img/win7-python-prompt.png Binary files differnew file mode 100644 index 0000000..27ae62a --- /dev/null +++ b/docs/source/_static/img/win7-python-prompt.png diff --git a/docs/source/_static/index-style.css b/docs/source/_static/index-style.css new file mode 100644 index 0000000..d7c42b3 --- /dev/null +++ b/docs/source/_static/index-style.css @@ -0,0 +1,19 @@ +/* Contents style */ + +.contents-table { + font-size: large; +} + +.contents-table ul, .contents-table li { + display: inline; +} + +.contents-table td { + padding: 0em 1em 0em; +} + +.contents-table ul { + list-style-type: none; + margin: 0em; + padding-left: 0px; +} diff --git a/docs/source/_static/leaflabs-docs.css b/docs/source/_static/leaflabs-docs.css new file mode 100644 index 0000000..18f5bcc --- /dev/null +++ b/docs/source/_static/leaflabs-docs.css @@ -0,0 +1 @@ +/* Any custom CSS you want applied goes here */ diff --git a/docs/source/_templates/.gitignore b/docs/source/_templates/.gitignore new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/source/_templates/.gitignore diff --git a/docs/source/_templates/indexcontent.html b/docs/source/_templates/indexcontent.html new file mode 100644 index 0000000..a043f8a --- /dev/null +++ b/docs/source/_templates/indexcontent.html @@ -0,0 +1,117 @@ +{# This file generates the top-level index.html file. We are very + obviously stealing from the Python docs' style ;). +#} + +<!-- Extend our layout.html. So inheritance hierarchy is Sphinx's + layout, then our layout.html, then this file. --> +{% extends "layout.html" %} + +<!-- Pull in extra index stylesheet --> +{% set css_files = css_files + ["_static/index-style.css"] %} + +<!-- Separator for contents lists --> +{% set content_sep = "·" %} + +<!-- Content --> +{% block body %} +<h1>Hi!</h1> + +This is the documentation for the LeafLabs Maple boards, version {{ +release }}. + +<h2>Read This First</h2> + +<p>Just getting started? Try the <a href="{{ +pathto("maple-quickstart") }}">Quickstart</a>. Having problems? Check +out <a href="{{ pathto("troubleshooting") }}">Troubleshooting</a> and +the <a href="{{ pathto("faq") }}">FAQ</a>. Can't find what you want +here? Look on the <a href="http://wiki.leaflabs.com/">LeafLabs +wiki</a>. +</p> + +<p>See the <a href="{{ pathto("whats-new") }}">What's New</a> page for +changes that are new in {{ release }}.</p> + +<h2>Contents at a Glance</h2> + +<table class="contents-table"> + <tr> + <td><p><strong>Getting Started</strong></p> + <ul> + <li><a href="{{ pathto("maple-quickstart") }}">Quickstart</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("maple-ide-install") }}">Installing Maple IDE</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("ide") }}">Using Maple IDE</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("unix-toolchain") }}">Command-Line + Toolchain</a></li> + </ul> + </td> + <td><p><strong>Boards</strong></p> + <ul> + <li><a href="{{ pathto("hardware/maple") }}">Maple</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("hardware/maple-ret6") }}">Maple RET6 Edition</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("hardware/maple-mini") }}">Maple Mini</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("hardware/maple-native-beta") }}">Maple + Native β</a></li> + </ul> + </td> + </tr> + <tr> + <td><p><strong>Programming</strong></p> + <ul> + <li><a href="{{ pathto("language") }}">Language Reference</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("troubleshooting") }}">Troubleshooting</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("faq") }}">FAQ</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("libraries") }}">Libraries</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("libmaple") }}"><tt>libmaple</tt></a> + {{ content_sep }}</li> + <li><a href="{{ pathto("bootloader") }}">Bootloader</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("arm-gcc") }}">GCC and libc</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("arduino-compatibility") }}">Arduino + Compatibility</a></li> + </ul> + </td> + <td><p><strong>Hardware and Peripherals</strong></p> + <ul> + <li><a href="{{ pathto("stm32") }}">STM32</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("adc") }}">ADC</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("external-interrupts") }}">External + Interrupts</a> {{ content_sep }}</li> + <li><a href="{{ pathto("fsmc") }}">FSMC</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("gpio") }}">GPIO</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("i2c") }}">I<sup>2</sup>C</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("jtag") }}">JTAG</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("pwm") }}">PWM</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("spi") }}">SPI</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("systick") }}">SysTick</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("timers") }}">Timers</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("usart") }}">USART</a> + {{ content_sep }}</li> + <li><a href="{{ pathto("usb") }}">USB</a></li> + </ul> + </td> + </tr> +</table> + +{% endblock %} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000..2fd81ce --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,11 @@ +{% extends "!layout.html" %} + +{% set css_files = css_files + ["_static/leaflabs-docs.css"] %} + +{% block rootrellink %} + <li><a href="http://leaflabs.com/"> + <img width="16px" src="_static/img/round_logo_32x32.ico"></img> + leaflabs.com + </a>·</li> + <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li> +{% endblock %} diff --git a/docs/source/adc.rst b/docs/source/adc.rst new file mode 100644 index 0000000..937b178 --- /dev/null +++ b/docs/source/adc.rst @@ -0,0 +1,104 @@ +.. _adc: + +===== + ADC +===== + +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 <ide>` contains a basic example. To see it, choose +Analog > AnalogInSerial from the :ref:`examples menu <ide-examples>`. + +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 <gpio>` 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 +<lang-pinmode>` to ``INPUT_ANALOG`` by calling ``pinMode(<your_pin>, +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` +* :ref:`libmaple-adc` (low-level ADC support) + +.. _adc-noise-bias: + +Noise and Bias +-------------- + +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: + +* :ref:`Maple <maple-adc-bank>` +* :ref:`Maple RET6 Edition <maple-ret6-adc-bank>` +* :ref:`Maple Mini <maple-mini-adc-bank>` +* :ref:`Maple Native Beta <maple-native-b-adc-bank>` + +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. 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: + +In the case of a variable reading, it is best if the voltage varies +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 +<http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener diodes +<http://en.wikipedia.org/wiki/Zener_diode>`_\ +. However, `operational amplifiers +<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other +powered components can also be used if greater precision is required. + +.. _adc-recommended-reading: + +Recommended Reading +------------------- + +* `Wikipedia: Analog-to-Digital Converter + <http://en.wikipedia.org/wiki/Analog-to-digital_converter>`_ +* `Arduino Analog Input Tutorial + <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ +* ST documentation: + + * `Application Note on ADC Modes + <http://www.st.com/stonline/products/literature/an/16840.pdf>`_ (PDF) + * `Application Note on ADC Oversampling + <http://www.st.com/stonline/products/literature/an/14183.pdf>`_ (PDF) diff --git a/docs/source/arduino-cc-attribution.txt b/docs/source/arduino-cc-attribution.txt new file mode 100644 index 0000000..ad1c1e0 --- /dev/null +++ b/docs/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 <http://arduino.cc/en/Reference/HomePage>`_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License <http://creativecommons.org/licenses/by-sa/3.0/>`_. diff --git a/docs/source/arduino-compatibility.rst b/docs/source/arduino-compatibility.rst new file mode 100644 index 0000000..f7d3210 --- /dev/null +++ b/docs/source/arduino-compatibility.rst @@ -0,0 +1,275 @@ +.. 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 programs) is +incompatible between the two, and a different compiler (actually just +a different version of `gcc <http://gcc.gnu.org/>`_) is required. + +The compiler for the regular Arduino IDE is the popular `avr-gcc +<http://www.nongnu.org/avr-libc/>`_ 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 <arm-gcc>` is available. + +The bitwidth of the processor means that the Maple can process 32-bit +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 +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 <lang-disabledebugports>`...). On the Arduino, the +analog pins are numbered separately (A0-A5) from the digital pins (D0\ +-D13). + +The incompatible hardware differences are: + +* :ref:`I2C <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 <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 <jtag>`. + + +Software Language/Library Changes +--------------------------------- + +With :ref:`a few exceptions <language-missing-features>`, 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 <lang-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() <lang-pinmode>` **types**: any :ref:`GPIO <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 <gpio>` + for more information. + +* :ref:`Serial port <lang-serial>` **syntax**: like the `Arduino Mega + <http://arduino.cc/en/Main/ArduinoBoardMega>`_, the Maple has + multiple :ref:`USART ports <lang-serial>`. By default, ``Serial`` + is not mapped to any of them. Use ``Serial1`` through ``Serial3`` + instead. + +* **16-bit** :ref:`PWM <pwm>`: Arduino boards support 8-bit PWM, which + means that calls to :ref:`analogWrite() <lang-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 <adc>`: Arduino boards support 10-bit ADC, which + means that calls to :ref:`analogRead() <lang-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 +------------------------------- + +**Can't find your shield?** Check out the `Compatible Shields +<http://wiki.leaflabs.com/index.php?title=Compatible_Shields>`_ page +on our wiki. + +.. 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 <libraries-wire>`. + + * - LiquidCrystal + - **Yes** + - :ref:`Included since IDE 0.0.7 <libraries-liquid-crystal>` + + * - 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 + <http://akb77.com/g/stm32/maple-eeprom-emulation-library/>`_ by + `x893 <http://akb77.com/g/>`_, but we haven't tested it. + + * - Firmata + - Not yet + - Planned + + * - Matrix + - Not yet + - Planned + + * - Servo + - **Yes** + - :ref:`Included since IDE 0.0.9 <libraries-servo>` + + * - 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 <language>` pages useful. As +appropriate, these have "Arduino Compatibility" sections; one good +example is the :ref:`analogWrite() <lang-analogwrite-compatibility>` +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! <libmaple-contributing>`). + +- 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 + <lang-serial>`. 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/docs/source/arm-gcc.rst b/docs/source/arm-gcc.rst new file mode 100644 index 0000000..30667a2 --- /dev/null +++ b/docs/source/arm-gcc.rst @@ -0,0 +1,107 @@ + +.. _arm-gcc: + +GCC and libc +============ + +This document provides notes on using ``arm-none-eabi-gcc``, the +`CodeSourcery <http://www.codesourcery.com/>`_ version of the GNU `GCC +<http://gcc.gnu.org/>`_ compilers used for the Maple boards. It is +not intended as a reference manual for GCC; such manuals are available +`elsewhere <http://gcc.gnu.org/>`_. + +.. contents:: Contents + :local: + +Obtaining ``arm-none-eabi-gcc`` +------------------------------- + +Recent versions of ``arm-none-eabi-gcc`` and associated tools are +included with the :ref:`Maple IDE <ide>`. + +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 maintains `mirrors +<http://static.leaflabs.com/pub/codesourcery/>`_ for some of the more +recent versions of the compiler, including versions for OS X, Win32, +and 32-bit Linux. + +.. _arm-gcc-compiler-flags: + +Compiler Flags Used by libmaple +------------------------------- + +This section documents the flags passed to ``arm-none-eabi-gcc`` by +the :ref:`Maple IDE <ide>` and the default Makefile provided with the +:ref:`Unix toolchain <unix-toolchain>`. The information in this +section is subject to change between :ref:`libmaple <libmaple>` +releases. + +.. 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 + +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 + +The following flags are among those passed to the assembler:: + + -mcpu=cortex-m3 -march=armv7-m -mthumb + +.. highlight:: cpp + +.. _arm-gcc-libc: + +Using the C Standard Library +---------------------------- + +By default (under both the :ref:`Maple IDE <ide>` and the :ref:`Unix +toolchain <unix-toolchain>`), ``arm-none-eabi-gcc`` is configured to +link against `newlib <http://sourceware.org/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. + +.. _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: + +- 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}; + + 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) diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst new file mode 100644 index 0000000..23b0448 --- /dev/null +++ b/docs/source/bootloader.rst @@ -0,0 +1,750 @@ +.. highlight:: sh + +.. _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, +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**: https://github.com/leaflabs/maple-bootloader + +.. contents:: Contents + :local: + +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 +<https://github.com/leaflabs/libmaple>`_! + +Arduino +------- + +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 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 +----------- + +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 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 custom drivers across several platforms to +make everything work this way. + +.. _bootloader-rev3: + +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 +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 <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() <lang-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 +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) +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 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 +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: + +.. 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 <http://www.libusb.org/>`_) 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 +.. <http://savannah.nongnu.org/projects/avrdude/>`_. 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 <bootloader-commands>` + +.. * - CHECKSUM +.. - 4 +.. - XOR of all other 32-bit words in packet +.. - See :ref:`below <bootloader-checksum>` + +.. .. _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 +.. <bootloader-get-info>`), 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: + +.. 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. + +.. 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: + +.. GET_INFO +.. """""""" + +.. Used to query device characteristics. + +.. GET_INFO Query: + +.. .. list-table:: +.. :header-rows: 1 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - GET_INFO +.. - 1 +.. - Value 0 + +.. GET_INFO Response: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 2 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - 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 +.. - Usually 0x08005000 + +.. * - Starting Address (RAM) +.. - 4 +.. - Usually 0x200000C0 + +.. * - Bootloader Version +.. - 4 +.. - Current version 0x00060000 (MAJ,MIN) + +.. .. _bootloader-erase-page: + +.. ERASE_PAGE +.. """""""""" + +.. Used to erase flash pages. + +.. ERASE_PAGE query: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 2 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - ERASE_PAGE +.. - 1 +.. - Value 1 + +.. * - ADDRESS +.. - 4 +.. - Will erase whichever page contains ADDRESS + +.. ERASE_PAGE response: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 3 2 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - ERASE_PAGE +.. - 1 +.. - Value 1 + +.. * - SUCCESS +.. - 1 +.. - Either 0 (failure) or 1 (success) + +.. WRITE_BYTES +.. """"""""""" + +.. Used to write to RAM or flash. + +.. WRITE_BYTES query: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 4 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - WRITE_BYTES +.. - 1 +.. - Value 2 + +.. * - Starting Address +.. - 4 +.. - Can address arbitrary RAM, or :ref:`cleared +.. <bootloader-erase-page>` flash pages. + +.. * - DATA +.. - MESSAGE_SIZE - 5 +.. - See :ref:`Packet Structure <bootloader-packet-structure>` + +.. WRITE_BYTES response: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - 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). + +.. READ_BYTES +.. """""""""" + +.. 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. + +.. * - 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: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - 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`. + +.. JUMP_TO_USER +.. """""""""""" + +.. Causes the bootloader to jump to user code's starting address. + +.. JUMP_TO_USER query: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - 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:: +.. :header-rows: 1 +.. :widths: 2 1 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - 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. + + +.. SOFT_RESET +.. """""""""" + +.. Engages a full software reset. + +.. SOFT_RESET query: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - SOFT_RESET +.. - 1 +.. - Value 5 + +.. SOFT_RESET response: + +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 + +.. * - Field +.. - Bytes +.. - Comments + +.. * - SOFT_RESET +.. - 1 +.. - Value 5 + +.. * - SUCCESS +.. - 1 +.. - Either 0 or 1 (FAILED and OK, respectively). Will end this +.. bootloader session and reset the processor. + +.. _bootloader-reflashing: + +Flashing A Custom Bootloader +---------------------------- + +.. 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. 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. + +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 <http://forums.leaflabs.com/topic.php?id=32#post-126>`_. + +.. highlight:: sh + +Setup +^^^^^ + +In order to follow these instructions, you will need: + +- A binary of the bootloader you want to upload (see below). +- Hardware for communicating between the Maple and your computer over + serial. +- `Python <http://python.org>`_, version 2.5 or higher. +- The `PySerial <http://pyserial.sourceforge.net/>`_ library (this + must be installed separately; it is not part of the Python standard + library). + +**Step 1: Obtain a bootloader binary**. If you want to re-flash the +"factory-default" bootloader, LeafLabs hosts pre-compiled copies: + +- `Maple <http://static.leaflabs.com/pub/leaflabs/maple-bootloader/maple_boot.bin>`_ +- `Maple Mini <http://static.leaflabs.com/pub/leaflabs/maple-bootloader/maple_mini_boot.bin>`_ +- `Maple RET6 Edition <http://static.leaflabs.com/pub/leaflabs/maple-bootloader/maple_RET6_boot.bin>`_ +- `Maple Native <http://static.leaflabs.com/pub/leaflabs/maple-bootloader/maple_native_boot.bin>`_ + +To flash a customized version of a LeafLabs bootloader, you can run +(on a :ref:`suitably configured system <unix-toolchain>`) 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 + +.. 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 +breakout boards <http://www.sparkfun.com/products/718>`_, 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 (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 +<lang-serial>`. + +At this point, you're ready to plug the FTDI board into your computer +(via USB). + +**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 bootloader mode +<troubleshooting-perpetual-bootloader>`. + +**Step 4: Get stm32loader.py**. You can download it directly from +`libmaple's GitHub page +<https://github.com/leaflabs/libmaple/raw/master/support/stm32loader.py>`_ +(click the link, then save the file somewhere on your system). If you +have set up the :ref:`Unix toolchain <unix-toolchain>`, it's the file +libmaple/support/stm32loader.py. + +Flashing the new Bootloader +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 + +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 + +You can also run the following to get usage information:: + + # Unix: + python stm32loader.py -h + + # Windows: + python.exe stm32loader.py -h + +If all goes well, you'll see a bunch of output, then "Verification +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 <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 + <bootloader-rev3>` 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, + and communicates over :ref:`usb`. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..f4a9bbb --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,283 @@ +# -*- 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 +import os.path + +# 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 the 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 = 'contents' + +# General information about the project. +project = u'Maple' +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 +# built documents. +# +# The short X.Y version. +version = '0.0' +# The full version, including alpha/beta/rc tags. +# FIXME [RELEASE] update this for the release +release = 'custom-build' + +# 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 = '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 = { + ## 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' : 'Lucida' +} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = ['_static'] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<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' + +# 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 = { + 'index': 'indexcontent.html' +} + +# 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 <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = '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 ------------------------------------------ + +# We allow people to check in Doxygen XML into maintenance branches. +doxygen_xml_maybe = os.path.join(os.path.dirname(os.path.dirname(__file__)), + 'doxygen', 'xml') +if os.path.isdir(doxygen_xml_maybe): + # There's a doxygen/xml/ directory in this repository root, use that. + doxygen_xml_dir = doxygen_xml_maybe +else: + # Nothing there, assume it's in LIB_MAPLE_HOME. + doxygen_xml_dir = os.path.join(os.environ['LIB_MAPLE_HOME'], + 'doxygen', 'xml') + +breathe_projects = {'libmaple' : doxygen_xml_dir} + +breathe_default_project = 'libmaple' diff --git a/docs/source/contents.rst b/docs/source/contents.rst new file mode 100644 index 0000000..7be7aec --- /dev/null +++ b/docs/source/contents.rst @@ -0,0 +1,73 @@ +.. _index: + +Contents in Full +================ + +.. _index-usage: + +**Getting Started** + +.. toctree:: + :maxdepth: 2 + + maple-quickstart + maple-ide-install + ide + unix-toolchain + unix-toolchain-linux-setup + unix-toolchain-osx-setup + unix-toolchain-win-setup + whats-new + +.. _index-maple-programming: + +**Programming** + +.. toctree:: + :maxdepth: 2 + + language + libraries + arduino-compatibility + libmaple + bootloader + troubleshooting + FAQ <faq> + arm-gcc + language-index + +.. _index-hardware: + +**Hardware and Peripherals** + +.. toctree:: + :maxdepth: 2 + + stm32 + 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/docs/source/epilog.rst b/docs/source/epilog.rst new file mode 100644 index 0000000..b548001 --- /dev/null +++ b/docs/source/epilog.rst @@ -0,0 +1,14 @@ +.. 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/ +.. _contact us directly: http://leaflabs.com/contact/ +.. _Python: http://python.org/download/ +.. _PySerial: http://pyserial.sourceforge.net/ +.. _OpenMoko: http://openmoko.com/ +.. _Git: http://git-scm.com/ +.. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util +.. _easy_install: http://packages.python.org/distribute/easy_install.html diff --git a/docs/source/external-interrupts.rst b/docs/source/external-interrupts.rst new file mode 100644 index 0000000..209d5af --- /dev/null +++ b/docs/source/external-interrupts.rst @@ -0,0 +1,68 @@ +.. highlight:: cpp + +.. _external-interrupts: + +External Interrupts +=================== + +External interrupts can be used to make a voltage change on a +:ref:`pin <gpio>` (the pin going from :ref:`LOW <lang-constants-low>` +to :ref:`HIGH <lang-constants-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: + +Overview +-------- + +External interrupts are often used to detect when events happen +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: + +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 +line*, and only one pin per EXTI line can be used for external +interrupts at a time [#fextisports]_. + +The EXTI Line Pin Map for your board lists which pins connect to which +EXTI lines: + +* :ref:`Maple <maple-exti-map>` +* :ref:`Maple RET6 Edition <maple-ret6-exti-map>` +* :ref:`Maple Mini <maple-mini-exti-map>` +* :ref:`Maple Native Beta <maple-native-b-exti-map>` + +Function Reference +------------------ + +- :ref:`attachInterrupt() <lang-attachinterrupt>` +- :ref:`detachInterrupt() <lang-detachinterrupt>` +- :ref:`libmaple-exti` + +Recommended Reading +------------------- + +* ST manual `RM0008 + <http://www.st.com/web/en/resource/technical/document/reference_manual/CD00171190.pdf>`_ + (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 <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. diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..bd155ae --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,115 @@ +.. highlight:: cpp + +.. _faq: + +================================== + Frequently Asked Questions (FAQ) +================================== + +.. contents:: Contents + :local: + +.. _faq-atoi: + +Can I use ``atoi()``, ``strol()``, etc.? +---------------------------------------- + +Just ``#include <stdlib.h>``. See :ref:`arm-gcc-libc` for more +information. + +.. _faq-dynamic-memory: + +Can I use ``malloc()``/``new``? +------------------------------- + +For ``malloc()``, just ``#include <stdlib.h>``, 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: + +How do I replace ``PROGMEM``/put data into Flash? +------------------------------------------------- + +See :ref:`this note <arm-gcc-attribute-flash>`. + +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 <gpio-ports>` 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 <maple-pin-map-master>` 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 +<gpio-pin-maps>`). + +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<port>, <bit>, HIGH/LOW)``, where +``<port>`` is the GPIO port, ``<bit>`` 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 +<http://forums.leaflabs.com/topic.php?id=860>`_ of other things to +try, with measurements of the speed you'll get. Next, a thread +featuring a `detailed discussion on pin capability +<http://forums.leaflabs.com/topic.php?id=774>`_, with a focus on +writes. And finally, `another thread +<http://forums.leaflabs.com/topic.php?id=895>`_ on the subject which +summarizes a variety of other threads on doing I/O quickly. + +Can I use Maple without Maple IDE? +---------------------------------- + +Yes. See :ref:`unix-toolchain` for the details. + diff --git a/docs/source/fsmc.rst b/docs/source/fsmc.rst new file mode 100644 index 0000000..c8f0125 --- /dev/null +++ b/docs/source/fsmc.rst @@ -0,0 +1,33 @@ +.. _fsmc: + +FSMC +==== + +The Flexible Static Memory Controller (FSMC) is a peripheral which an +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__ <arm-gcc-attribute-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 <http://en.wikipedia.org/wiki/Static_random-access_memory>`_ +- :ref:`ST RM0008 <maple-native-b-stdocs>` chapter on FSMC. diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst new file mode 100644 index 0000000..caaae3d --- /dev/null +++ b/docs/source/gpio.rst @@ -0,0 +1,106 @@ +.. _gpio: + +GPIO +==== + +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 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 <lang-pinmode-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 +<gpio-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 <lang-board-values-led>` 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 +-------- + +Part of :ref:`Maple IDE's <ide>` 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: + +* :ref:`Maple <maple-gpios>` +* :ref:`Maple RET6 Edition <maple-ret6-gpios>` +* :ref:`Maple Mini <maple-mini-gpios>` +* :ref:`Maple Native (Beta) <maple-native-b>` + +.. * :ref:`Maple Native <maple-native-gpios>` + +.. _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.3V to a non-5V tolerant pin may damage your +board. + +.. _gpio-recommended-reading: + +Recommended Reading +------------------- + +* ST Documentation for the STM32F103 series of microcontrollers: + + * `Reference Manual RM0008 + <http://www.st.com/web/en/resource/technical/document/reference_manual/CD00171190.pdf>`_ + (PDF); general, definitive resource for STM32F1 line. + * `Programming Manual PM0056 + <http://www.st.com/st-web-ui/static/active/en/resource/technical/document/programming_manual/CD00228163.pdf>`_ + (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. diff --git a/docs/source/hardware/maple-mini.rst b/docs/source/hardware/maple-mini.rst new file mode 100644 index 0000000..c28211d --- /dev/null +++ b/docs/source/hardware/maple-mini.rst @@ -0,0 +1,402 @@ +.. _maple-mini: + +Maple Mini +========== + +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: :ref:`STM32F103CBT6 <maple-mini-stdocs>`, a 32-bit ARM Cortex + M3 microprocessor +* Clock Speed: **72 MHz** +* **128 KB Flash** and **20 KB SRAM** +* 34 :ref:`digital I/ pins (GPIOs) <gpio>` +* 12 :ref:`PWM <pwm>` pins at 16 bit resolution +* 9 :ref:`analog input (ADC) <adc>` pins at 12 bit resolution +* 2 :ref:`SPI <spi>` peripherals +* 2 :ref:`I2C <i2c>` peripherals +* 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) +* 3 :ref:`USART (serial port) <usart>` peripherals +* 1 advanced and 3 general-purpose :ref:`timers <timers>` +* Dedicated :ref:`USB <usb>` port for programming and communications +* :ref:`jtag` +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt <external-interrupts>` on GPIOs) +* Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital + and analog regulators <maple-mini-adc-bank>` for low-noise analog + performance +* :ref:`Open source, four layer design <maple-mini-hardware>` +* 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**, and potentially even lower depending upon the current + draw requirements of the application. Please see :ref:`Power + Regulation on the Maple Mini <maple-mini-power-regulation>` 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 +<http://ww1.microchip.com/downloads/en/DeviceDoc/22049a.pdf>`_ ). 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 +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: + +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 <usb>` D+ line, and ``D24`` is the USB D- +line. To use them as GPIOs, your program will need to :ref:`disable +SerialUSB <lang-serialusb-end>` first. Be aware, however, that +disabling SerialUSB means that the :ref:`bootloader <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 <lang-board-values-but>`. +It is thus mainly useful as an :ref:`input <lang-pin-levels>`. The +pin will :ref:`read <lang-digitalread>` ``HIGH`` when the :ref:`button +is pressed <lang-isbuttonpressed>`. + +.. _maple-mini-led: + +Pin ``D33`` is the Mini's :ref:`LED pin <lang-board-values-led>`. It +is thus mainly useful as an :ref:`output <lang-pin-levels>`. The LED +will glow when ``HIGH`` is :ref:`written <lang-digitalwrite>` 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 :ref:`5 volt tolerant <gpio-5v-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 <gpio>`, :ref:`ADC <adc>`, :ref:`Timer <timers>`, :ref:`I2C <i2c>`, :ref:`UART <usart>`, :ref:`SPI <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-gpio-port-map: + +GPIO Port Pin Map +^^^^^^^^^^^^^^^^^ +The following table shows what pins are associated with each +:ref:`GPIO port <gpio-ports>`. + +.. 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 +^^^^^^^^^^^^^ + +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 <maple-mini-led>` + 4 | D16 | D15 | :ref:`D32 <maple-mini-but>` | + +.. _maple-mini-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +<external-interrupts-exti-line>`. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - D3, D11 + * - EXTI1 + - D10, D33 + * - EXTI2 + - D2, D9 + * - EXTI3 + - D8, D19 + * - EXTI4 + - D7, D18 + * - EXTI5 + - D6, D17 + * - EXTI6 + - D5, D16 + * - EXTI7 + - D4, D15 + * - EXTI8 + - D27, D32 + * - EXTI9 + - D26 + * - EXTI10 + - D1, D25 + * - EXTI11 + - D0, D24 + * - EXTI12 + - D23, D31 + * - EXTI13 + - D14, D22, D30 + * - EXTI14 + - D13, D21, D29 + * - EXTI15 + - D12, D20, D28 + +.. _maple-mini-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +The Maple Mini has three serial ports (also known as :ref:`USARTs +<usart>`). They communicate using the pins given in the following +table. + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | D26 | D25 | D27 | D24 | D23 + ``Serial2`` | D9 | D8 | D7 | D11 | D10 + ``Serial3`` | D1 | D0 | D31 | D30 | D29 + +.. _maple-mini-adc-bank: + +Low-Noise ADC Pins +^^^^^^^^^^^^^^^^^^ + +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. 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 <maple-mini-hardware>` for more details. + +.. _maple-mini-board-values: + +Board-Specific Values +--------------------- + +This section lists the Maple Mini's :ref:`board-specific values +<lang-board-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 <maple-mini-usb-pins>`) +- ``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 <https://github.com/leaflabs/maplemini>`_. + +From the GitHub repository main page, you can download the entire +repository by clicking the "Download" button. If you are familiar +with `Git <http://git-scm.com/>`_, 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 + <maple-mini-pin-map-master>` details which pins are :ref:`5 + V-tolerant <gpio-5v-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 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 + <maple-mini-power-regulation>` for more information. + + +Recommended Reading +------------------- + +.. _maple-mini-stdocs: + +STMicro documentation for STM32F103CB microcontroller: + +* `Datasheet + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00161566.pdf>`_ + (PDF); covers STM32F103x8, STM32F103xB. +* `Reference Manual RM0008 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_ + (PDF); definitive resource for peripherals on the STM32F1 line. +* `Programming Manual PM0056 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_ + (PDF); assembly language and register reference. +* `STM32F103CB <http://www.st.com/internet/mcu/product/189782.jsp>`_ + overview page with links to further references. + +.. rubric:: Footnotes + +.. [#fusedpins] See :ref:`boardUsedPins <lang-board-values-used-pins>` + for more information. diff --git a/docs/source/hardware/maple-native-beta.rst b/docs/source/hardware/maple-native-beta.rst new file mode 100644 index 0000000..bdfd216 --- /dev/null +++ b/docs/source/hardware/maple-native-beta.rst @@ -0,0 +1,605 @@ +.. highlight:: sh + +.. _maple-native-b: + +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 +------------------------ + +* MCU: `STM32F103ZET6 <maple-native-b-stdocs>`, 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 <gpio>` +* 17 :ref:`PWM <pwm>` pins at 16 bit resolution +* 21 :ref:`analog input (ADC) <adc>` pins at 12-bit resolution +* 3 :ref:`SPI <spi>` peripherals +* 2 :ref:`I2C <i2c>` peripherals +* 12 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) + with 2 DMA controllers +* 3 :ref:`USART (serial port) <usart>` peripherals, 2 **UART** peripherals +* 2 advanced, 4 general-purpose, and 2 basic :ref:`timers <timers>` +* Dedicated :ref:`USB <usb>` port for programming and communications +* :ref:`JTAG <jtag>` +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt <lang-attachinterrupt>` on GPIOs) +* Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital + and analog regulators <maple-native-b-adc-bank>` for low-noise analog + performance +* :ref:`Open-source, four layer design <maple-native-b-hardware>` +* 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 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 <maple-native-b-power-regulation>` 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 +<http://ww1.microchip.com/downloads/en/DeviceDoc/22049a.pdf>`_). 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 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 +---------------------------------- + +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 <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 <lang-board-values-but>`. +It is thus mainly useful as an :ref:`input <lang-pin-levels>`. The +pin will :ref:`read <lang-digitalread>` ``HIGH`` when the :ref:`button +is pressed <lang-isbuttonpressed>`. + +.. _maple-native-b-led: + +Pin ``D22`` is the Native's :ref:`LED pin <lang-board-values-led>`. +It is thus mainly useful as an :ref:`output <lang-pin-levels>`. The +LED will glow when ``HIGH`` is :ref:`written <lang-digitalwrite>` to +it. + +.. _maple-native-b-fsmc: + +Many of the pins on the right header (pins ``D56`` through ``D100``, +the header is labeled :ref:`"FSMC" <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. 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: + +Pins ``D101`` through ``D105`` are connected to the pads on the +:ref:`JTAG <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 <gpio-5v-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 <gpio>`, :ref:`ADC <adc>`, :ref:`Timer <timers>`, :ref:`I2C <i2c>`, :ref:`UART <usart>`, :ref:`SPI <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 <gpio>`, :ref:`ADC <adc>`, :ref:`Timer <timers>`, :ref:`I2C <i2c>`, :ref:`UART <usart>`, :ref:`SPI <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 +<maple-native-b-stdocs>` 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 + <maple-native-b-fsmc>` for more information. + +.. csv-table:: + :header: Pin, :ref:`GPIO <gpio>`, :ref:`FSMC <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 <maple-native-b-jtag>` for more information on + these pins. + +.. csv-table:: + :header: Pin, :ref:`GPIO <gpio>`, :ref:`SPI <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 <gpio-ports>`. + +.. 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) +<gpio-h-afio-remap>`. + +.. 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 +<external-interrupts-exti-line>`. + +.. 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 <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 +^^^^^^^^^^^^^^^^^^ + +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. +Consult the :ref:`Maple Native beta hardware design files +<maple-native-b-hardware>` for more details. + +.. _maple-native-b-board-values: + +Board-Specific Values +--------------------- + +This section lists the Maple Native's :ref:`board-specific values +<lang-board-values>`. + +- ``CYCLES_PER_MICROSECOND``: 72 +- ``BOARD_BUTTON_PIN``: 6 +- ``BOARD_LED_PIN``: 22 +- ``BOARD_NR_GPIO_PINS``: 106 +- ``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``: 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 + <maple-native-b-fsmc>`. +- ``BOARD_NR_USARTS``: 5 +- ``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_SPI3_NSS_PIN``: 103 (on :ref:`JTAG header <maple-native-b-jtag>`) +- ``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 <maple-native-b-jtag>` +- ``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 +<https://github.com/leaflabs/maplenative/>`_. Download the `beta +version's hardware design files +<https://github.com/leaflabs/maplenative/tree/beta>`_ (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. + +* **VREF is nonfunctional**: Due to a routing error, VREF is + permanently tied to 3.3V at VAA. + +Recommended Reading +------------------- + +.. _maple-native-b-stdocs: + +STMicro documentation for STM32F103ZE microcontroller: + +* `Datasheet + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00191185.pdf>`_ + (PDF); covers STM32F103xC, STM3F103xD, STM32F103xE. +* `Reference Manual RM0008 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_ + (PDF); definitive resource for peripherals on the STM32F1 line. +* `Programming Manual PM0056 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_ + (PDF); assembly language and register reference. +* `STM32F103RE <http://www.st.com/internet/mcu/product/164485.jsp>`_ + overview page with links to further references. + +.. rubric:: Footnotes + +.. [#fusedpins] See :ref:`boardUsedPins <lang-board-values-used-pins>` + for more information. diff --git a/docs/source/hardware/maple-native.rst b/docs/source/hardware/maple-native.rst new file mode 100644 index 0000000..79115fc --- /dev/null +++ b/docs/source/hardware/maple-native.rst @@ -0,0 +1,6 @@ +.. _hardware-maple-native: + +Maple Native +============ + +Stub. diff --git a/docs/source/hardware/maple-ret6.rst b/docs/source/hardware/maple-ret6.rst new file mode 100644 index 0000000..3d2d037 --- /dev/null +++ b/docs/source/hardware/maple-ret6.rst @@ -0,0 +1,466 @@ +.. highlight:: sh + +.. _maple-ret6: + +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 (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: + +.. 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 +------------------------ + +* MCU: :ref:`STM32F103RET6 <maple-ret6-stdocs>`, a 32-bit ARM Cortex + M3 microprocessor +* Clock Speed: **72 MHz** +* **512 KB Flash** and **64 KB SRAM** +* 43 :ref:`digital I/O pins (GPIOs) <gpio>` +* 18 :ref:`PWM <pwm>` pins at 16 bit resolution +* 15 :ref:`analog input (ADC) <adc>` pins at 12 bit resolution +* Built-in, 2 channel **DAC** at 12 bit resolution (:ref:`libmaple-dac`). +* 2 :ref:`SPI <spi>` peripherals with **I2S** support +* 2 :ref:`I2C <i2c>` peripherals +* 12 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) + with 2 DMA controllers +* 3 :ref:`USART (serial port) <usart>` peripherals +* 2 advanced, 4 general-purpose, and 2 basic :ref:`timers <timers>` +* Dedicated :ref:`USB <usb>` port for programming and communications +* :ref:`JTAG <jtag>` +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt <lang-attachinterrupt>` on GPIOs) +* Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital + and analog regulators <maple-ret6-adc-bank>` for low-noise analog + performance +* :ref:`Open-source, four layer design <maple-ret6-hardware>` +* 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 is powered in the :ref:`same way as the +standard Maple <maple-powering>`. + +.. 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 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 + <maple-power-regulation>` 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 <maple-power-regulation>`. + +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 light up. + +.. _maple-ret6-gpios: + +GPIO Information +---------------- + +The RET6 Edition 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 <lang-board-values-but>`. +It is thus mainly useful as an :ref:`input <lang-pin-levels>`. The +pin will :ref:`read <lang-digitalread>` ``HIGH`` when the :ref:`button +is pressed <lang-isbuttonpressed>`. + +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 <lang-board-values-debug>` for more information. +(See :ref:`this erratum <maple-ret6-nrst-pb4>` for information about +the pin numbered ``43`` on the silkscreen). + +.. TODO [0.1.0] silkscreen pictures which expand abbreviations + +.. _maple-ret6-pin-map-master: + +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 :ref:`5 volt tolerant <gpio-5v-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 <gpio>`, :ref:`ADC <adc>`, :ref:`Timer <timers>`, :ref:`I2C <i2c>`, :ref:`UART/USART <usart>`, :ref:`SPI <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-gpio-port-map: + +GPIO Port Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows what pins are associated with each +:ref:`GPIO port <gpio-ports>`. + +.. 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 +^^^^^^^^^^^^^ + +The following table shows what pins are associated with a particular +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 + :delim: | + + 1 | D6 | D7 | D8 | - + 2 | D2 | D3 | D1 | D0 + 3 | D12 | D11 | D27 | D28 + 4 | D5 | D9 | D14 | D24 + 8 | D35 | D36 | D37 | :ref:`D38 <maple-ret6-but>` + +.. _maple-ret6-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +<external-interrupts-exti-line>` on the Maple RET6 Edition. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - D2, D15, D27 + * - EXTI1 + - D3, D16, D28 + * - EXTI2 + - D1, D17, D25 + * - EXTI3 + - D0, D18, D42 + * - EXTI4 + - D10, D19 + * - EXTI5 + - D4, D13, D20 + * - EXTI6 + - D5, D12, D35 + * - EXTI7 + - D9, D11, D36 + * - EXTI8 + - D6, D14, D37 + * - EXTI9 + - D7, D24, D38 + * - EXTI10 + - D8, D26, D29 + * - EXTI11 + - D30 + * - EXTI12 + - D31 + * - EXTI13 + - D21, D32, D39 + * - EXTI14 + - D22, D33, D40 + * - EXTI15 + - D23, D34, D41 + +.. _maple-ret6-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 <usart>`). They communicate +using the pins given in the following table. + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``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 +<maple-ret6-uarts>`. + +.. _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 <maple-adc-bank>`. + +Board-Specific Values +--------------------- + +This section lists the Maple RET6 Edition's :ref:`board-specific +values <lang-board-values>`. + +- ``CYCLES_PER_MICROSECOND``: 72 +- ``BOARD_BUTTON_PIN``: 38 +- ``BOARD_LED_PIN``: 13 +- ``BOARD_NR_GPIO_PINS``: 44 (however, :ref:`pin D43 is not usable + <maple-nrst-pb4>`) +- ``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, 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, :ref:`due to the Maple Rev 5 + design <maple-ret6-uarts>`, 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``: 2 (unfortunately, :ref:`due to the Maple Rev 5 + design <maple-ret6-nrst-pb4>`, SPI3 is unavailable). +- ``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``: :ref:`43 <maple-ret6-nrst-pb4>` + +.. _maple-ret6-hardware: + +Hardware Design Files +--------------------- + +The hardware schematics and board layout files are available in the +`Maple GitHub repository <https://github.com/leaflabs/maple>`_. 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 <http://git-scm.com/>`_, 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 + <maple-ret6-pin-map-master>` details which pins are + :ref:`5V-tolerant <gpio-5v-tolerant>`. + +Errata +------ + +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. + +.. _maple-ret6-barrel-jack: + +* **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 <maple-power-regulation>` 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-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). 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 that of the Maple Rev 5. The DAC + output channel is still available, and (if you use the + :ref:`standard libmaple DAC interface <libmaple-dac>`) 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 can reset your board. This + has other implications. Since PB4 is also the JTAG NJTRST line, + this prevents the :ref:`JTAG <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 +------------------- + +.. _maple-ret6-stdocs: + +STMicro documentation for STM32F103RE microcontroller: + +* `Datasheet + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00191185.pdf>`_ + (PDF); covers STM32F103xC, STM32F103xD, STM32F103xE. +* `Reference Manual RM0008 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_ + (PDF); definitive resource for peripherals on the STM32F1 line. +* `Programming Manual PM0056 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_ + (PDF); assembly language and register reference. +* `STM32F103RE <http://www.st.com/internet/mcu/product/164485.jsp>`_ + overview page with links to further references. diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst new file mode 100644 index 0000000..b187115 --- /dev/null +++ b/docs/source/hardware/maple.rst @@ -0,0 +1,618 @@ +.. highlight:: sh + +.. _maple: + +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: :ref:`STM32F103RBT6 <maple-stdocs>`, a 32-bit ARM Cortex M3 + microprocessor +* Clock Speed: **72 MHz** +* **128 KB Flash** and **20 KB SRAM** +* 43 :ref:`digital I/O pins (GPIOs) <gpio>` +* 15 :ref:`PWM <pwm>` pins at 16 bit resolution +* 15 :ref:`analog input (ADC) <adc>` pins at 12-bit resolution +* 2 :ref:`SPI <spi>` peripherals +* 2 :ref:`I2C <i2c>` peripherals +* 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) +* 3 :ref:`USART (serial port) <usart>` peripherals +* One advanced and three general-purpose :ref:`timers <timers>` +* Dedicated :ref:`USB <usb>` port for programming and communications +* :ref:`JTAG <jtag>` +* Nested Vectored Interrupt Controller (NVIC) (including + :ref:`external interrupt <external-interrupts>` 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:`Open source, four layer design <maple-hardware>` +* 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: + +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. + +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 + +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. + +.. figure:: /_static/img/maple_rev3.png + :align: center + :alt: Maple Rev 3 + +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 + +.. _maple-powering: + +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. 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 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 + <maple-power-regulation>` 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 +<http://ww1.microchip.com/downloads/en/DeviceDoc/22049a.pdf>`_ ). 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 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 +---------------------------------- + +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 light up. + +.. _maple-gpios: + +GPIO Information +---------------- + +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 <lang-board-values-but>`. +It is thus mainly useful as an :ref:`input <lang-pin-levels>`. The +pin will :ref:`read <lang-digitalread>` ``HIGH`` when the :ref:`button +is pressed <lang-isbuttonpressed>`. + +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 +<lang-board-values-debug>` for more information. (See :ref:`this +erratum <maple-nrst-pb4>` for information about the pin numbered +``43`` on the silkscreen). + +.. TODO [0.1.0] silkscreen pictures which expand abbreviations + +.. _maple-pin-map-master: + +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 :ref:`5 volt tolerant <gpio-5v-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 <gpio>`, :ref:`ADC <adc>`, :ref:`Timer <timers>`, :ref:`I2C <i2c>`, :ref:`UART <usart>`, :ref:`SPI <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-gpio-port-map: + +GPIO Port Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows what pins are associated with each +:ref:`GPIO port <gpio-ports>`. + +.. 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 +^^^^^^^^^^^^^ + +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 +<external-interrupts-exti-line>` on the Maple. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - D2, D15, D27 + * - EXTI1 + - D3, D16, D28 + * - EXTI2 + - D1, D17, D25 + * - EXTI3 + - D0, D18, D42 + * - EXTI4 + - D10, D19 + * - EXTI5 + - D4, D13, D20 + * - EXTI6 + - D5, D12, D35 + * - EXTI7 + - D9, D11, D36 + * - EXTI8 + - D6, D14, D37 + * - EXTI9 + - D7, D24, D38 + * - EXTI10 + - D8, D26, D29 + * - EXTI11 + - D30 + * - EXTI12 + - D31 + * - EXTI13 + - D21, D32, D39 + * - EXTI14 + - D22, D33, D40 + * - EXTI15 + - D23, D34, D41 + +.. _maple-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +The Maple has three serial ports (also known as :ref:`USARTs +<usart>`): ``Serial1``, ``Serial2``, and ``Serial3``. They communicate +using the pins given in the following table. + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | D7 | D8 | D6 | | + ``Serial2`` | D1 | D0 | D10 | D2 | D3 + ``Serial3`` | D29 | D30 | D31 | D32 | D33 + +.. _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 <maple-hardware>` for more details. + +Board-Specific Values +--------------------- + +This section lists the Maple's :ref:`board-specific values +<lang-board-values>`. + +- ``CYCLES_PER_MICROSECOND``: 72 +- ``BOARD_BUTTON_PIN``: 38 +- ``BOARD_LED_PIN``: 13 +- ``BOARD_NR_GPIO_PINS``: 44 (however, :ref:`pin D43 is not usable + <maple-nrst-pb4>`) +- ``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, 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 +- ``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``: :ref:`43 <maple-nrst-pb4>` + +.. _maple-hardware: + +Hardware Design Files +--------------------- + +The hardware schematics and board layout files are available in the +`Maple GitHub repository <https://github.com/leaflabs/maple>`_. 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 <http://git-scm.com/>`_, you can also clone the repository +at the command line with :: + + $ git clone git://github.com/leaflabs/maple.git + +.. _maple-failure-modes: + +Failure Modes +------------- + +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 master table + <maple-pin-map-master>` details which pins are :ref:`5 V tolerant + <gpio-5v-tolerant>`. + +Errata +------ + +This section documents design flaws and other errors. + +General +^^^^^^^ + +.. _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 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 + <maple-power-regulation>` for more information. + +.. _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 <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 + <maple-adc-led>`, 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 +^^^^^^ + +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 + 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. + +.. _maple-rev3-bad-buttons: + +* **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 (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 <lang-serial>`), 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 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. + +Rev 1 +~~~~~ + +* **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 + :ref:`geometrically isolated ADC Vref plane <maple-adc-bank>`. + +* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on + USART2 (:ref:`Serial2 <lang-serial>`), 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 + <http://forums.leaflabs.com/topic.php?id=32#post-126>`_. + +Recommended Reading +------------------- + +.. _maple-stdocs: + +STMicro documentation for STM32F103RB microcontroller: + +* `Datasheet + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00161566.pdf>`_ + (PDF); covers STM32F103x8, STM32F103xB. +* `Reference Manual RM0008 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_ + (PDF); definitive resource for peripherals on the STM32F1 line. +* `Programming Manual PM0056 + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_ + (PDF); assembly language and register reference. +* `STM32F103RB <http://www.st.com/internet/mcu/product/164487.jsp>`_ + overview page with links to further references. + +.. rubric:: Footnotes + +.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal + testing. diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst new file mode 100644 index 0000000..a206ed4 --- /dev/null +++ b/docs/source/i2c.rst @@ -0,0 +1,77 @@ +.. _i2c: + +|i2c| +===== + +|i2c| is a crude and easy-to-hack serial protocol that requires only +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 +code) and slave device (responding to requests via configurable +interrupt handlers) at the same time (though slave mode is currently +unimplemented). + +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 +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 <i2c-recommended-reading>` below), starting +with a slow clock rate (10kHz), and, if possible, using an +oscilloscope to debug any issues. + +Function Reference +------------------ + +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, but software +for it is not yet implemented. + +.. _i2c-recommended-reading: + +Recommended Reading +------------------- + +* `I2C Bus <http://www.i2c-bus.org/>`_ +* `Wikipedia: I2C <http://en.wikipedia.org/wiki/I%C2%B2C>`_ +* `Arduino I2C/TWI reference <http://www.arduino.cc/en/Reference/Wire>`_ +* ST `Application note STM32F10xxx I2C optimized examples + <http://www.st.com/st-web-ui/static/active/en/resource/technical/document/application_note/CD00209826.pdf>`_ (PDF) diff --git a/docs/source/ide.rst b/docs/source/ide.rst new file mode 100644 index 0000000..e6d49fc --- /dev/null +++ b/docs/source/ide.rst @@ -0,0 +1,166 @@ +.. _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 +toolbar. It is expected to become more comprehensive over time. + +If you're new to Maple, you should begin with the :ref:`Maple +Quickstart <maple-quickstart>`. + +If you need to install the IDE for the first time, see the +:ref:`maple-ide-install` page. + +.. 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. 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. 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 make a fresh sketch. + +.. _ide-open: + +Open +~~~~ + +.. image:: /_static/img/button-open.png + :align: left + +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. 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 :ref:`SerialUSB <lang-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 +<maple-quickstart-upload>`. + +If all else fails, try putting your Maple in :ref:`perpetual +bootloader mode <troubleshooting-perpetual-bootloader>` before +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 communication channel between your +PC and the Maple's :ref:`SerialUSB <lang-serialusb>` virtual serial +port. + +If the serial monitor is open, any information sent to the computer +(for example, using :ref:`SerialUSB.println() +<lang-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() +<lang-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 > +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 <ide-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. diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst new file mode 100644 index 0000000..caba223 --- /dev/null +++ b/docs/source/jtag.rst @@ -0,0 +1,81 @@ +.. highlight:: cpp + +.. _jtag: + +JTAG +==== + +.. 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 +allows data to be read and written to arbitrary memory and register +locations. It is typically used with a debugging tool like `gdb +<http://www.gnu.org/software/gdb/>`_ when hacking low level routines +and hardware peripherals (we use it when working on :ref:`libmaple +<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 +:ref:`lang-assert` allows basic debugging over 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 + :target: _images/jtag-wiring.png + + JTAG wiring diagram (`large version <_images/jtag-wiring.png>`_) + 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. 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 +<http://www.olimex.com/dev/arm-usb-ocd.html>`_ device, which costs +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) + <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ + +* `STM32, GDB, OpenOCD How To + <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_ + +* `LeafLabs Wiki JTAG How To + <http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ + +* `LeafLabs forum thread on JTAG + <http://forums.leaflabs.com/topic.php?id=536>`_ + +* ST documentation: + + * Reference Manual `RM0008 + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + (PDF), Chapter 31, "Debug support", and Chapter 9, + "General-purpose and alternate function I/Os". diff --git a/docs/source/lang/api/abs.rst b/docs/source/lang/api/abs.rst new file mode 100644 index 0000000..d9f1ca3 --- /dev/null +++ b/docs/source/lang/api/abs.rst @@ -0,0 +1,48 @@ +.. 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst new file mode 100644 index 0000000..6665a94 --- /dev/null +++ b/docs/source/lang/api/analogread.rst @@ -0,0 +1,119 @@ +.. 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 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`\ . + +Parameter Discussion +-------------------- + +The pin parameter is the number of the analog input pin to read from. +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 +<lang-board-values-adc-pins>` 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 +<index-boards>` 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 +---- + +If the analog input pin is not connected to anything, the value +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 val = 0; // variable to store the value read + + void setup() { + pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input + } + + 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 <lang-bitshift>` 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; + +.. FIXME [0.1.0] Mention that Native can do analogReference() + +On the Arduino, the input range and resolution can be changed using +the `analogReference() +<http://arduino.cc/en/Reference/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 <adc-range>` for +more information. + +See Also +-------- + +- :ref:`ADC tutorial <adc>` +- `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst new file mode 100644 index 0000000..0169976 --- /dev/null +++ b/docs/source/lang/api/analogwrite.rst @@ -0,0 +1,181 @@ +.. highlight:: cpp + +.. _lang-analogwrite: + +.. _lang-api-analogwrite: + + +analogWrite() +============= + +analogWrite() is used to create a :ref:`PWM <pwm>` wave on a pin. + +.. note:: + + On the Maple, calling analogWrite() is the same as calling + :ref:`lang-pwmwrite`. We recommend writing pwmWrite() instead of + analogWrite(). + + This is because PWM is not true analog output (it's not the output + of a `DAC + <http://en.wikipedia.org/wiki/Digital-to-analog_converter>`_\ ), so + the function is very badly named. For instance, **analogWrite() + has nothing to do with** :ref:`lang-analogread`\ , which can be + confusing. + + We provide analogWrite() for the sake of compatibility with Arduino + only. + +.. contents:: Contents + :local: + +.. _lang-analogwrite-compatibility: + +Arduino Compatibility +--------------------- + +There are a few important differences between Arduino's `analogWrite() +<http://arduino.cc/en/Reference/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 <lang-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,535, which is the correct default range for all of the timers +which control PWM output. See the :ref:`timers reference <timers>` +for more information. + +Another fix is to consult your board's :ref:`pin maps <gpio-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 <lang-hardwaretimer-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, 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. + +* **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, then any other 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 <pwm>`\ ). + +If your application definitely requires Arduino's PWM frequency, then +the steps are: + +1. Figure out which :ref:`timer <lang-hardwaretimer>` controls PWM + output on your pin (\ :ref:`your board's Timer Pin Map + <gpio-pin-maps>` is your friend here). + +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 + <lang-hardwaretimer-getting-started>` 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 +<lang-hardwaretimer-interrupts>` and :ref:`PWM +<timers-pwm-conflicts>`\ . + +See Also +-------- + +- :ref:`pwm` +- :ref:`lang-pwmwrite` +- :ref:`BOARD_NR_PWM_PINS <lang-board-values-nr-pwm-pins>` +- :ref:`boardPWMPins <lang-board-values-pwm-pins>` + +.. 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/assert.rst b/docs/source/lang/api/assert.rst new file mode 100644 index 0000000..76330b6 --- /dev/null +++ b/docs/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/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst new file mode 100644 index 0000000..58e4764 --- /dev/null +++ b/docs/source/lang/api/attachinterrupt.rst @@ -0,0 +1,114 @@ +.. highlight:: cpp + +.. _lang-attachinterrupt: + +attachInterrupt() +================= + +Used to specify a function to call when an :ref:`external interrupt +<external-interrupts>` occurs. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. 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) + + 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 + +.. doxygentypedef:: voidFuncPtr + +.. note:: + + You should set the :ref:`pin mode <lang-pinmode>` of your desired + pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``, + ``INPUT_PULLDOWN``). + +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 some limits you should be aware of if you're using +``attachInterrupt()`` with more than one pin; the :ref:`External +Interrupts <external-interrupts-exti-line>` 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); + pinMode(0, INPUT); + attachInterrupt(0, blink, CHANGE); + } + + void loop() { + digitalWrite(BOARD_LED_PIN, state); + } + + void blink() { + 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 +--------------------- + +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:`lang-detachinterrupt` +- :ref:`external-interrupts` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bit.rst b/docs/source/lang/api/bit.rst new file mode 100644 index 0000000..3df042c --- /dev/null +++ b/docs/source/lang/api/bit.rst @@ -0,0 +1,38 @@ +.. _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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitclear.rst b/docs/source/lang/api/bitclear.rst new file mode 100644 index 0000000..f487059 --- /dev/null +++ b/docs/source/lang/api/bitclear.rst @@ -0,0 +1,39 @@ +.. _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 +------- + +Nothing. + +Arduino Compatibility +--------------------- + +The Maple implementation of ``bitClear()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`bit <lang-bit>`\ () +- :ref:`bitRead <lang-bitread>`\ () +- :ref:`bitWrite <lang-bitwrite>`\ () +- :ref:`bitSet <lang-bitset>`\ () + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitread.rst b/docs/source/lang/api/bitread.rst new file mode 100644 index 0000000..fd9fbbe --- /dev/null +++ b/docs/source/lang/api/bitread.rst @@ -0,0 +1,39 @@ +.. _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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitset.rst b/docs/source/lang/api/bitset.rst new file mode 100644 index 0000000..83ab5f8 --- /dev/null +++ b/docs/source/lang/api/bitset.rst @@ -0,0 +1,39 @@ +.. _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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitwrite.rst b/docs/source/lang/api/bitwrite.rst new file mode 100644 index 0000000..6106545 --- /dev/null +++ b/docs/source/lang/api/bitwrite.rst @@ -0,0 +1,45 @@ +.. 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 implementation of ``bitWrite()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`bit() <lang-bit>` +- :ref:`bitRead() <lang-bitRead>` +- :ref:`bitSet() <lang-bitSet>` +- :ref:`bitClear() <lang-bitClear>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst new file mode 100644 index 0000000..d944c8d --- /dev/null +++ b/docs/source/lang/api/board-values.rst @@ -0,0 +1,189 @@ +.. highlight:: cpp + +.. _lang-board-values: + +Board-Specific Values +===================== + +There are a number of board-specific values: constants or variables +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 <index-boards>`. + +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 +<lang-board-values-examples>`. + +.. contents:: Contents + :local: + +Constants +--------- + +- ``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`` × 1,000,000. + +- ``SYSTICK_RELOAD_VAL``: Value used when reloading the :ref:`systick` + timer's counter [#fmillis]_. + +.. _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 <gpio>` 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() + <lang-boardusespin>` (and also :ref:`boardUsedPins + <lang-board-values-used-pins>`). + +.. _lang-board-values-nr-pwm-pins: + +- ``BOARD_NR_PWM_PINS``: Total *number* of GPIO pins that can be used + for :ref:`PWM <pwm>`. The actual *pins* that can do PWM are in the + :ref:`boardPWMPins <lang-board-values-pwm-pins>` 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 <adc>`. The actual pins that + can do ADC conversion are in the :ref:`boardADCPins + <lang-board-values-adc-pins>` 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 <lang-board-values-used-pins>` array. To see if + a pin is already in use, use the :ref:`boardUsesPin() + <lang-boardusespin>` function. + +.. _lang-board-values-usart: + +- :ref:`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. + +- :ref:`SPI <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``, + ``BOARD_JTCK_SWCLK_PIN``, ``BOARD_JTDI_PIN``, ``BOARD_JTDO_PIN``, + and ``BOARD_NJTRST_PIN``. + + These constants are the pin numbers for :ref:`GPIOs <gpio>` 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 + <lang-board-values-used-pins>`). However, they can be used as + ordinary GPIOs if you call the :ref:`lang-disabledebugports` + 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 <maple-nrst-pb4>`\ !). + +.. _lang-board-values-pwm-pins: + +.. _lang-board-values-adc-pins: + +.. _lang-board-values-used-pins: + +Pin Arrays +---------- + +Some :ref:`arrays <lang-array>` of pin numbers are available which you +can use to find out certain important information about a given pin. + +- ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM + <pwm>` output, using :ref:`pwmWrite() <lang-pwmwrite>`. The total + number of these pins is :ref:`BOARD_NR_PWM_PINS + <lang-board-values-nr-pwm-pins>`. + +- ``boardADCPins``: Pin numbers of each pin capable of :ref:`ADC + <adc>` conversion, using :ref:`analogRead() <lang-analogread>`. The + total number of these pins is :ref:`BOARD_NR_ADC_PINS + <lang-board-values-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 <lang-board-values-nr-used-pins>`. + To check if a pin is used for a special purpose, use + :ref:`boardUsesPin() <lang-boardusespin>`. + +.. _lang-board-values-examples: + +Examples +-------- + +:ref:`BOARD_LED_PIN <lang-board-values-led>` 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 both boards using :ref:`this example <lang-toggleled-example>`. + +:ref:`BOARD_BUTTON_PIN <lang-board-values-but>`: 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 +<lang-waitforbuttonpress-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 +-------- + +- :ref:`lang-boardusespin` +- :ref:`lang-isbuttonpressed` +- :ref:`lang-waitforbuttonpress` +- :ref:`lang-pinmode` +- :ref:`lang-toggleled` +- :ref:`lang-analogread` +- :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/docs/source/lang/api/boardusespin.rst b/docs/source/lang/api/boardusespin.rst new file mode 100644 index 0000000..126c4a0 --- /dev/null +++ b/docs/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 pins connected to 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 <lang-board-values>` +- :ref:`boardUsedPins <lang-board-values-used-pins>` +- :ref:`BOARD_LED_PIN <lang-board-values-led>` +- :ref:`toggleLED() <lang-toggleled>` +- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>` +- :ref:`isButtonPressed() <lang-isbuttonpressed>` +- :ref:`waitForButtonPress() <lang-waitforbuttonpress>` diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst new file mode 100644 index 0000000..6f69dfe --- /dev/null +++ b/docs/source/lang/api/constants.rst @@ -0,0 +1,318 @@ +.. _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 <lang-booleanvariables>`. 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). + +.. _lang-pin-levels: + +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() +<lang-pinmode>`), and read with :ref:`digitalRead() +<lang-digitalread>`, 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 +``HIGH`` with :ref:`digitalWrite() <lang-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() <lang-pinmode>`, and +read with :ref:`digitalRead() <lang-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() <lang-digitalwrite>`, the +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.3 V, 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() <lang-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() <lang-pinmode>` reference page. + +.. _lang-constants-input: + +INPUT +^^^^^ + +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: + +OUTPUT +^^^^^^ + +Pins configured as ``OUTPUT`` with :ref:`pinMode() <lang-pinmode>` are +said to be in a low-impedance state. This means that they can provide +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 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 are numbers used directly in a sketch, like +``123``. By default, an integer constant is treated as a (signed) +:ref:`int <lang-int>`, but you can change this with the U and L +modifiers (see :ref:`below <lang-constants-integers-u-l>`). You can +specify negative numbers by putting a minus sign in front, like +``-123``. + +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 explained 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. You shouldn't use them +in new programs. + +.. _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``. + +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 + 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 +can be typed in upper or lower case (a-f). + +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 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 +``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 <lang-int>` +(and must be in the int type's :ref:`range limits +<lang-int-overflow>`). 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 <lang-unsignedint>`. + +- an ``l`` or ``L`` to interpret the constant as a long value. For + example, ``100000L`` is a :ref:`long <lang-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 <lang-unsignedlong>`. 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 + <lang-longlong>` value. + +- a ``ull`` or ``ULL`` to interpret the constant as an :ref:`unsigned + long long <lang-unsignedlonglong>`. + +.. _lang-constants-fp: + +Floating-Point Constants +------------------------ + +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 +<lang-double>`. In order for the constant to be interpreted as a +:ref:`float <lang-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 +exponent indicators. Some examples are given in the following table: + + +.. list-table:: + :header-rows: 1 + + * - Floating-point constant + - 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`` + +.. _lang-constants-board: + +Board-Specific Constants +------------------------ + +There are several :ref:`board-specific constants <lang-board-values>` +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 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 +:ref:`BOARD_LED_PIN <lang-board-values-led>` will always be the +correct value for each board. + +See Also +-------- + +- :ref:`pinMode() <lang-pinmode>` +- :ref:`Boolean Variables <lang-booleanvariables>` +- :ref:`#define <lang-define>` +- :ref:`int <lang-int>` +- :ref:`unsigned int <lang-unsignedint>` +- :ref:`long <lang-long>` +- :ref:`unsigned long <lang-unsignedlong>` +- :ref:`long long <lang-longlong>` +- :ref:`unsigned long long <lang-unsignedlonglong>` +- :ref:`float <lang-float>` +- :ref:`double <lang-double>` +- :ref:`Board-Specific Values <lang-board-values>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/constrain.rst b/docs/source/lang/api/constrain.rst new file mode 100644 index 0000000..28af1e3 --- /dev/null +++ b/docs/source/lang/api/constrain.rst @@ -0,0 +1,68 @@ +.. 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() <lang-min>` +- :ref:`max() <lang-max>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/cos.rst b/docs/source/lang/api/cos.rst new file mode 100644 index 0000000..c340f09 --- /dev/null +++ b/docs/source/lang/api/cos.rst @@ -0,0 +1,30 @@ +.. _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 +<http://sourceware.org/newlib/>`_\ , while Arduino's is that of +`avr-libc <http://avr-libc.nongnu.org/>`_\ . + +See Also +-------- + +- :ref:`sin() <lang-sin>` +- :ref:`tan() <lang-tan>` +- :ref:`float <lang-float>` +- :ref:`double <lang-double>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/delay.rst b/docs/source/lang/api/delay.rst new file mode 100644 index 0000000..30bd436 --- /dev/null +++ b/docs/source/lang/api/delay.rst @@ -0,0 +1,69 @@ +.. 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() <lang-millis>` function +and the "Blink Without Delay" sketch cited :ref:`below +<lang-delay-seealso>`\ . 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() <lang-pwmwrite>`\ ) values +and pin states are maintained, and :ref:`interrupts +<lang-attachinterrupt>` will work as they should. + + +Example +------- + +:: + + void setup() { + // set up the built-in LED pin for output: + pinMode(BOARD_LED_PIN, OUTPUT); + } + + void loop() { + 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: + +See Also +-------- + +- :ref:`millis() <lang-millis>` +- :ref:`micros() <lang-micros>` +- :ref:`delayMicroseconds() <lang-delayMicroseconds>` +- (Arduino) `Blink Without Delay + <http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ example (works + unmodified on Maple) + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/delaymicroseconds.rst b/docs/source/lang/api/delaymicroseconds.rst new file mode 100644 index 0000000..7078660 --- /dev/null +++ b/docs/source/lang/api/delaymicroseconds.rst @@ -0,0 +1,62 @@ +.. 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 <lang-millis>` +- :ref:`micros <lang-micros>` +- :ref:`delay <lang-delay>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/detachinterrupt.rst b/docs/source/lang/api/detachinterrupt.rst new file mode 100644 index 0000000..6eb8e53 --- /dev/null +++ b/docs/source/lang/api/detachinterrupt.rst @@ -0,0 +1,43 @@ +.. _lang-detachinterrupt: + +detachInterrupt() +================= + +Used to disable an interrupt specified with +:ref:`lang-attachinterrupt`\ . + +Library Documentation +--------------------- + +.. FIXME [Breathe] once we can get the correct detachInterrupt(), +.. replace with doxygenfunction. + +.. cpp:function:: void detachInterrupt(uint8 pin) + + Disable any registered external interrupt on the given pin. + + *Parameters* + + - ``pin`` Maple pin number + +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() <lang-attachInterrupt>` +- :ref:`external-interrupts` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/digitalread.rst b/docs/source/lang/api/digitalread.rst new file mode 100644 index 0000000..03ccd7f --- /dev/null +++ b/docs/source/lang/api/digitalread.rst @@ -0,0 +1,51 @@ +.. highlight:: cpp + +.. _lang-digitalread: + +digitalRead() +============= + +Reads the value from a specified digital pin, either :ref:`HIGH +<lang-constants-high>` or :ref:`LOW <lang-constants-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 or off when the button is pressed:: + + void setup() { + pinMode(BOARD_LED_PIN, OUTPUT); + pinMode(BOARD_BUTTON_PIN, INPUT); + } + + void loop() { + int val = digitalRead(BOARD_BUTTON_PIN); // reads the input pin + togglePin(BOARD_LED_PIN); + } + +Arduino Compatibility +--------------------- + +The Maple version of ``digitalRead()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>` +- :ref:`lang-isButtonPressed` +- :ref:`lang-pinmode` +- :ref:`lang-digitalWrite` +- :ref:`lang-togglepin` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/digitalwrite.rst b/docs/source/lang/api/digitalwrite.rst new file mode 100644 index 0000000..bae8db9 --- /dev/null +++ b/docs/source/lang/api/digitalwrite.rst @@ -0,0 +1,56 @@ +.. highlight:: cpp + +.. _lang-digitalwrite: + +digitalWrite() +============== + +Write a :ref:`HIGH <lang-constants-high>` or a :ref:`LOW +<lang-constants-low>` value to a pin configured as :ref:`OUTPUT +<lang-constants-output>`. + +Library Documentation +--------------------- + +.. doxygenfunction:: digitalWrite + +Discussion +---------- + +If the pin has been configured as an ``OUTPUT`` with :ref:`pinMode() +<lang-pinmode>` its voltage will be set to the corresponding value: +3.3V for ``HIGH``, and 0V (ground) for ``LOW``. + +Because it is soldered to an LED and resistor in series, your board's +:ref:`BOARD_LED_PIN <lang-board-values-led>` will respond slightly +more slowly as an output than the other pins. + +Example +------- + +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 + } + + void loop() { + 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 +-------- + +- :ref:`pinMode <lang-pinmode>` +- :ref:`digitalRead <lang-digitalread>` +- :ref:`BOARD_LED_PIN <lang-board-values-led>` +- :ref:`lang-toggleled` +- :ref:`lang-togglepin` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/disabledebugports.rst b/docs/source/lang/api/disabledebugports.rst new file mode 100644 index 0000000..283cdbf --- /dev/null +++ b/docs/source/lang/api/disabledebugports.rst @@ -0,0 +1,33 @@ +.. 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 (the pins on the JTAG + // header on the Maple) as ordinary pins. + } + +See Also +-------- + +- :ref:`lang-enabledebugports` +- :ref:`Important erratum on Maple pin 43 <maple-nrst-pb4>` diff --git a/docs/source/lang/api/enabledebugports.rst b/docs/source/lang/api/enabledebugports.rst new file mode 100644 index 0000000..bee2b0a --- /dev/null +++ b/docs/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` diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst new file mode 100644 index 0000000..a44a65f --- /dev/null +++ b/docs/source/lang/api/hardwarespi.rst @@ -0,0 +1,170 @@ +.. highlight:: cpp + +.. _lang-hardwarespi: + +HardwareSPI +=========== + +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 <spi>`. + +.. contents:: Contents + :local: + +Getting Started +--------------- + +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. + +Here's an example (we'll fill in :ref:`setup() <lang-setup>` and +:ref:`loop() <lang-loop>` later):: + + // Use SPI port number 1 + HardwareSPI spi(1); + + void setup() { + // Your setup code + } + + void loop() { + // Do stuff with SPI + } + +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 [Breathe] Output doesn't include the class; fix & submit pull req + +.. 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: + +.. 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. + +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 +before, we'll add a call to ``begin()`` to our ``setup()``:: + + // Use SPI port number 1 + HardwareSPI spi(1); + + void setup() { + // Turn on the SPI port + spi.begin(SPI_18MHZ, MSBFIRST, 0); + } + + void loop() { + // Do stuff with SPI + } + +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);``". + +Communicating Over 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:: void HardwareSPI::write(byte data) + + Send a single byte of data. + + **Parameters**: + + - ``data``: Byte to send + +.. cpp:function:: byte HardwareSPI::read() + + 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::transfer(byte data) + + Send a byte, then return the next byte received. + + **Parameters:** + + - ``data``: Byte to send + + **Returns:** Next unread byte + +Continuing our example from before, let's send a number over SPI and +print out whatever we get back over :ref:`lang-serialusb`:: + + // Use SPI port number 1 + HardwareSPI spi(1); + + void setup() { + // Turn on the SPI port + spi.begin(SPI_18MHZ, MSBFIRST, 0); + } + + 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. + +.. doxygenclass:: HardwareSPI + :members: HardwareSPI, begin, beginSlave, end, read, write, transfer + +Deprecated Functions +-------------------- + +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) + + 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. diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst new file mode 100644 index 0000000..b919e52 --- /dev/null +++ b/docs/source/lang/api/hardwaretimer.rst @@ -0,0 +1,345 @@ +.. highlight:: cpp + +.. _lang-hardwaretimer: + +HardwareTimer +============= + +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 <timers>`. + +.. 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. + + 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`. + +.. contents:: Contents + :local: + +.. _lang-hardwaretimer-getting-started: + +Getting Started +--------------- + +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. + +Here's an example (we'll fill in :ref:`setup() <lang-setup>` and +:ref:`loop() <lang-loop>` later):: + + // Use timer 1 + HardwareTimer timer(1); + + void setup() { + // Your setup code + } + + void loop() { + // ... + } + +Configuring the Prescaler and Overflow +-------------------------------------- + +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. + +.. _lang-hardwaretimer-setprescalefactor: + +.. doxygenfunction:: HardwareTimer::setPrescaleFactor + :no-link: + +.. _lang-hardwaretimer-setoverflow: + +.. doxygenfunction:: HardwareTimer::setOverflow + :no-link: + +For example:: + + // Use timer 1 + HardwareTimer timer(1); + + void setup() { + timer.setPrescaleFactor(5); + timer.setOverflow(255); + } + + void loop() { + // ... + } + +You may also find the ``setPeriod()`` function useful: + +.. _lang-hardwaretimer-setperiod: + +.. doxygenfunction:: HardwareTimer::setPeriod + :no-link: + +For example:: + + // Use timer 1 + HardwareTimer timer(1); + + void setup() { + // Have the timer repeat every 20 milliseconds + int microseconds_per_millisecond = 1000; + timer.setPeriod(20 * microseconds_per_millisecond); + } + + void loop() { + // ... + } + +.. _lang-hardwaretimer-interrupts: + +Using Timer Interrupts +---------------------- + +.. TODO [0.2.0] Improve the interrupts section, here or in timers.rst + +In order to use timer interrupts, we recommend the following sequence: + +* Pause the timer. +* Configure the prescaler and overflow. +* Pick a timer channel to handle the interrupt and set the channel's + :ref:`mode <lang-hardwaretimer-timermode>` 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. + +Here are two complete examples. + +**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 + + // We'll use timer 2 + HardwareTimer timer(2); + + void setup() { + // Set up the LED to blink + pinMode(BOARD_LED_PIN, OUTPUT); + + // Pause the timer while we're configuring it + timer.pause(); + + // Set up period + timer.setPeriod(LED_RATE); // in microseconds + + // Set up an interrupt on channel 1 + timer.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE); + timer.setCompare(TIMER_CH1, 1); // Interrupt 1 count after each update + timer.attachInterrupt(1, handler_led); + + // Refresh the timer's count, prescale, and overflow + timer.refresh(); + + // Start the timer counting + timer.resume(); + } + + void loop() { + // Nothing! It's all in the handler_led() interrupt: + } + + void handler_led(void) { + toggleLED(); + } + +**Racing Counters**: This example shows how to use multiple timers at +the same time. :: + + int count3 = 0; + int count4 = 0; + + // We'll use timers 3 and 4 + HardwareTimer timer3(3); + HardwareTimer timer4(4); + + void setup() { + // Set up the button for input + pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); + + // 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(); + } + + 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); + } + } + + void handler3(void) { + count3++; + } + + void handler4(void) { + count4++; + } + +``HardwareTimer`` Class Reference +--------------------------------- + +This section gives a full listing of the capabilities of a +``HardwareTimer``. + +.. doxygenclass:: HardwareTimer + :members: HardwareTimer, pause, resume, getPrescaleFactor, setPrescaleFactor, getOverflow, setOverflow, getCount, setCount, setPeriod, setMode, getCompare, setCompare, attachInterrupt, detachInterrupt, refresh + +.. _lang-hardwaretimer-timermode: + +.. doxygenenum:: timer_mode + +Deprecated Functionality +------------------------ + +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 ``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. + +.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) + + Use ``attachInterrupt(1, handler)`` instead. + +.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) + + Use ``attachInterrupt(2, handler)`` instead. + +.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) + + Use ``attachInterrupt(3, handler)`` instead. + +.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) + + Use ``attachInterrupt(4, handler)`` instead. + +.. _lang-hardwaretimer-setchannelmode: + +.. cpp:function:: void HardwareTimer::setChannelMode(int channel, timer_mode mode) + + Use ``setMode(channel, mode)`` instead. + +.. cpp:function:: void HardwareTimer::setChannel1Mode(timer_mode mode) + + Use ``setMode(1, mode)`` instead. + +.. cpp:function:: void HardwareTimer::setChannel2Mode(timer_mode mode) + + Use ``setMode(2, mode)`` instead. + +.. cpp:function:: void HardwareTimer::setChannel3Mode(timer_mode mode) + + Use ``setMode(3, mode)`` instead. + +.. cpp:function:: void HardwareTimer::setChannel4Mode(timer_mode mode) + + Use ``setMode(4, mode)`` instead. + +.. cpp:function:: uint16 HardwareTimer::getCompare1() + + Use ``getCompare(1, mode)`` instead. + +.. cpp:function:: uint16 HardwareTimer::getCompare2() + + Use ``getCompare(2, mode)`` instead. + +.. cpp:function:: uint16 HardwareTimer::getCompare3() + + Use ``getCompare(3, mode)`` instead. + +.. cpp:function:: uint16 HardwareTimer::getCompare4() + + Use ``getCompare(4, mode)`` instead. + +.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) + + Use ``setCompare(1, compare)`` instead. + +.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) + + Use ``setCompare(2, compare)`` instead. + +.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) + + Use ``setCompare(3, compare)`` instead. + +.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) + + Use ``setCompare(4, compare)`` instead. + +.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() + + Use ``detachInterrupt(1)`` instead. + +.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() + + Use ``detachInterrupt(2)`` instead. + +.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() + + Use ``detachInterrupt(3)`` instead. + +.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() + + Use ``detachInterrupt(4)`` instead. + +.. cpp:function:: void HardwareTimer::generateUpdate() + + Use ``refresh()`` instead. + +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/docs/source/lang/api/highbyte.rst b/docs/source/lang/api/highbyte.rst new file mode 100644 index 0000000..4cb6f9b --- /dev/null +++ b/docs/source/lang/api/highbyte.rst @@ -0,0 +1,55 @@ +.. 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() <lang-lowbyte>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/interrupts.rst b/docs/source/lang/api/interrupts.rst new file mode 100644 index 0000000..58fd2cc --- /dev/null +++ b/docs/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() <lang-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() <lang-nointerrupts>` +- :ref:`attachInterrupt() <lang-attachinterrupt>` +- :ref:`detachInterrupt() <lang-detachinterrupt>` +- :ref:`Timers reference <timers>` +- :ref:`Timer API <lang-hardwaretimer>` +- :ref:`External interrupts <external-interrupts>` + +.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/api/isbuttonpressed.rst b/docs/source/lang/api/isbuttonpressed.rst new file mode 100644 index 0000000..8c350b9 --- /dev/null +++ b/docs/source/lang/api/isbuttonpressed.rst @@ -0,0 +1,20 @@ +.. _lang-isbuttonpressed: + +isButtonPressed() +================= + +Check whether the board's built-in button (labeled BUT on the +silkscreen) is pressed. The pin number of the built-in button is +given by the constant ``BOARD_BUTTON_PIN``. + +Library Documentation +--------------------- + +.. doxygenfunction:: isButtonPressed + +See Also +-------- + +- :ref:`Board-specific values <lang-board-values>` +- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>` +- :ref:`lang-waitforbuttonpress` diff --git a/docs/source/lang/api/loop.rst b/docs/source/lang/api/loop.rst new file mode 100644 index 0000000..c2a5097 --- /dev/null +++ b/docs/source/lang/api/loop.rst @@ -0,0 +1,44 @@ +.. highlight:: cpp + +.. _lang-loop: + +loop() +====== + +After creating a :ref:`setup() <lang-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() <lang-setup>` + + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/lowbyte.rst b/docs/source/lang/api/lowbyte.rst new file mode 100644 index 0000000..c513711 --- /dev/null +++ b/docs/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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/map.rst b/docs/source/lang/api/map.rst new file mode 100644 index 0000000..69661a0 --- /dev/null +++ b/docs/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() <lang-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 <lang-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() <lang-constrain>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/max.rst b/docs/source/lang/api/max.rst new file mode 100644 index 0000000..d356f08 --- /dev/null +++ b/docs/source/lang/api/max.rst @@ -0,0 +1,64 @@ +.. 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() + <lang-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 implementation of ``max()`` is compatible with Arduino. + +See Also +-------- + +- :ref:`min() <lang-min>` +- :ref:`constrain() <lang-constrain>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/micros.rst b/docs/source/lang/api/micros.rst new file mode 100644 index 0000000..de85303 --- /dev/null +++ b/docs/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() <lang-millis>` +- :ref:`delay() <lang-delay>` +- :ref:`delayMicroseconds() <lang-delaymicroseconds>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/millis.rst b/docs/source/lang/api/millis.rst new file mode 100644 index 0000000..b6fbf55 --- /dev/null +++ b/docs/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 + SerialUSB.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 +<lang-unsignedlong>`, overflow errors may occur if you try to do math +with other data types, such as :ref:`chars <lang-char>`. + +See Also +-------- + +- :ref:`micros <lang-micros>` +- :ref:`delay <lang-delay>` +- :ref:`delayMicroseconds <lang-delaymicroseconds>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/min.rst b/docs/source/lang/api/min.rst new file mode 100644 index 0000000..3307105 --- /dev/null +++ b/docs/source/lang/api/min.rst @@ -0,0 +1,65 @@ +.. 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() <lang-max>` +- :ref:`constrain() <lang-constrain>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/nointerrupts.rst b/docs/source/lang/api/nointerrupts.rst new file mode 100644 index 0000000..68f0498 --- /dev/null +++ b/docs/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() <lang-interrupts>` +- :ref:`attachInterrupt() <lang-attachinterrupt>` +- :ref:`detachInterrupt() <lang-detachinterrupt>` +- :ref:`Timers reference <timers>` +- :ref:`Timer API <lang-hardwaretimer>` +- :ref:`External interrupts <external-interrupts>` + +.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/api/pinmode.rst b/docs/source/lang/api/pinmode.rst new file mode 100644 index 0000000..643e26e --- /dev/null +++ b/docs/source/lang/api/pinmode.rst @@ -0,0 +1,80 @@ +.. highlight:: cpp + +.. _lang-pinmode: + +pinMode() +========= + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: pinMode + +.. _lang-pinmode-wiringpinmode: + +.. 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 +------- + +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. + +:: + + void setup() { + pinMode(BOARD_LED_PIN, OUTPUT); // sets the LED pin as output + } + + void loop() { + 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 +--------------------- + +.. TODO check out Arduino vs. Maple static discilpline cutoffs to +.. ensure accuracy of following: + +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 +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: + +.. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and +.. ``PWM_OPEN_DRAIN`` modes represent functionality not currently +.. available on Arduino boards. + +See Also +-------- + +- :ref:`lang-board-values` +- :ref:`lang-constants` +- :ref:`lang-digitalwrite` +- :ref:`lang-digitalread` +- :ref:`gpio` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/pow.rst b/docs/source/lang/api/pow.rst new file mode 100644 index 0000000..219a866 --- /dev/null +++ b/docs/source/lang/api/pow.rst @@ -0,0 +1,20 @@ +.. _lang-pow: + +pow() +===== + +Calculates the value of a number raised to a power. + +Library Documentation +--------------------- + +.. doxygenfunction:: pow + +See Also +-------- + +- :ref:`sqrt() <lang-sqrt>` +- :ref:`float <lang-float>` +- :ref:`double <lang-double>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst new file mode 100644 index 0000000..5cc112e --- /dev/null +++ b/docs/source/lang/api/pwmwrite.rst @@ -0,0 +1,61 @@ +.. highlight:: cpp + +.. _lang-pwmwrite: + +pwmWrite() +========== + +Writes a :ref:`PWM wave <pwm>` 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. + +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 <lang-board-values-pwm-pins>` +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 <index-boards>` pages. + +The Arduino function :ref:`analogWrite() <lang-analogwrite>` is an +alias for ``pwmWrite()``, but it is badly named, and its use is +discouraged. + +.. contents:: Contents + :local: + +Library Documentation +--------------------- + +.. doxygenfunction:: pwmWrite + +Example +------- + +Sets the output to the LED proportional to the value read from the +potentiometer:: + + int analogPin = 3; // potentiometer connected to analog pin 3 + + void setup() { + pinMode(BOARD_LED_PIN, OUTPUT); // sets the LED pin as output + + pinMode(analogPin, INPUT_ANALOG); // sets the potentiometer pin as + // analog input + } + + void loop() { + int val = analogRead(analogPin); // read the input pin + + pwmWrite(BOARD_LED_PIN, val * 16); // analogRead values go from 0 + // to 4095, pwmWrite values + // from 0 to 65535, so scale roughly + } + +See Also +-------- + +- :ref:`Maple PWM tutorial <pwm>` +- :ref:`boardPWMPins <lang-board-values-pwm-pins>` diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst new file mode 100644 index 0000000..9875ee6 --- /dev/null +++ b/docs/source/lang/api/random.rst @@ -0,0 +1,71 @@ +.. highlight:: cpp + +.. _lang-random: + +random() +======== + +The ``random()`` function generates pseudo-random numbers. + +Library Documentation +--------------------- + +.. FIXME [Breathe] use doxygenfunction when possible + +.. 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() <lang-random>` to differ, on subsequent executions of a +sketch, use :ref:`randomSeed() <lang-randomseed>` to initialize the +random number generator with a fairly random input, such as +:ref:`analogRead() <lang-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 +<adc>` reading of pin 0. If this pin is unconnected, the Sketch +should print different values to the :ref:`serial monitor +<ide-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() <lang-randomseed>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/randomseed.rst b/docs/source/lang/api/randomseed.rst new file mode 100644 index 0000000..ca7b75f --- /dev/null +++ b/docs/source/lang/api/randomseed.rst @@ -0,0 +1,60 @@ +.. highlight:: cpp + +.. _lang-randomseed: + +randomSeed() +============ + +``randomSeed()`` initializes the `pseudorandom number generator +<http://en.wikipedia.org/wiki/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() <lang-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() +<lang-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 +<adc>` reading of pin 0. If this pin is unconnected, the Sketch +should print different values to the :ref:`serial monitor +<ide-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() <lang-random>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/serial.rst b/docs/source/lang/api/serial.rst new file mode 100644 index 0000000..e287015 --- /dev/null +++ b/docs/source/lang/api/serial.rst @@ -0,0 +1,282 @@ +.. FIXME [0.0.13] This doesn't include UART4/5, or USART6 +.. highlight:: cpp + +.. _lang-serial: + +Serial Ports (``Serial1``, ``Serial2``, ``Serial3``) +==================================================== + +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: + +Getting Started +--------------- + +First, decide which serial port you wish to use, and :ref:`connect its +pins to the device you're communicating with <usart-circuit>`. (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 +--------------------- + +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:: 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() + <lang-setup>` function). + +.. cpp:function:: void 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 + <HardwareSerial::available>`), the call will block until one + becomes available. + +.. 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:: void HardwareSerial::print(unsigned char b) + + Print the given byte over the USART. + +.. 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:: void HardwareSerial::print(const char *str) + + Print the given null-terminated string over the USART. + +.. 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:: void HardwareSerial::print(unsigned int n) + + Print the argument's digits over the USART, in decimal format. + +.. 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:: void HardwareSerial::print(unsigned long n) + + Print the argument's digits over the USART, in decimal format. + +.. 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:: void HardwareSerial::print(double n) + + Print ``n``, accurate to 2 digits after the decimal point. + +.. _lang-serial-println: + +.. cpp:function:: void HardwareSerial::println(char c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(const char *c) + + Like ``print(c)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(unsigned char b) + + Like ``print(b)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(unsigned int n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(unsigned long n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(long n, int base) + + Like ``print(n, b)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println(double n) + + Like ``print(n)``, followed by ``"\r\n"``. + +.. cpp:function:: void HardwareSerial::println() + + Prints ``"\r\n"`` over the USART. + +.. cpp:function:: void HardwareSerial::write(unsigned char ch) + + Sends one character over the USART. This function is currently + 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:: void 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:: 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. + + 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:: 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 +-------------------------- + +Unlike the Arduino, none of the Maple's serial ports is connected to +the USB port on the Maple board. If you want to communicate using the +built-in USB port, use :ref:`SerialUSB <lang-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 + +.. Examples +.. -------- + +.. - `ASCII Table <http://arduino.cc/en/Tutorial/ASCIITable>`_ +.. - `Dimmer <http://arduino.cc/en/Tutorial/Dimmer>`_ +.. - `Graph <http://arduino.cc/en/Tutorial/Graph>`_ +.. - `Physical Pixel <http://arduino.cc/en/Tutorial/PhysicalPixel>`_ +.. - `Virtual Color Mixer <http://arduino.cc/en/Tutorial/VirtualColorMixer>`_ +.. - `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_ +.. - `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_ + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/serialusb.rst b/docs/source/lang/api/serialusb.rst new file mode 100644 index 0000000..ed466f2 --- /dev/null +++ b/docs/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 <lang-serial>`, 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. 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 +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 ``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 <lang-serialusb-safe-print>` (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 + (singleton) instance. + +.. _lang-serialusb-begin: + +.. 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. 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 + <troubleshooting-perpetual-bootloader>`. + +.. 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 + <USBSerial::available>`), the call will block until one + becomes available. + +.. 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 BOARD_LED_PIN + + void setup() { + /* Set up the LED to blink */ + pinMode(LED_PIN, OUTPUT); + } + + void loop() { + // 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() 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); + } + } + digitalWrite(LED_PIN, 0); + delay(100); + } + diff --git a/docs/source/lang/api/setup.rst b/docs/source/lang/api/setup.rst new file mode 100644 index 0000000..1e8e3b8 --- /dev/null +++ b/docs/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 <lang-variables>`, :ref:`pin modes +<lang-pinmode>`, start using :ref:`libraries <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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/shiftout.rst b/docs/source/lang/api/shiftout.rst new file mode 100644 index 0000000..1d9ba12 --- /dev/null +++ b/docs/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 +<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 <lang-constants-output>` mode by a call to +:ref:`pinMode() <lang-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 +<http://arduino.cc/en/Tutorial/ShiftOut>`_. + +:: + + //**************************************************************// + // 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/docs/source/lang/api/sin.rst b/docs/source/lang/api/sin.rst new file mode 100644 index 0000000..3e28c0b --- /dev/null +++ b/docs/source/lang/api/sin.rst @@ -0,0 +1,31 @@ +.. _lang-sin: + +sin() +===== + +Calculates the `sine <http://en.wikipedia.org/wiki/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 +<http://sourceware.org/newlib/>`_\ , while Arduino's is that of +`avr-libc <http://avr-libc.nongnu.org/>`_\ . + +See Also +-------- + +- :ref:`cos <lang-cos>` +- :ref:`tan <lang-tan>` +- :ref:`float <lang-float>` +- :ref:`double <lang-double>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/sq.rst b/docs/source/lang/api/sq.rst new file mode 100644 index 0000000..96724d3 --- /dev/null +++ b/docs/source/lang/api/sq.rst @@ -0,0 +1,45 @@ +.. 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/tan.rst b/docs/source/lang/api/tan.rst new file mode 100644 index 0000000..b1aed31 --- /dev/null +++ b/docs/source/lang/api/tan.rst @@ -0,0 +1,30 @@ +.. _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 +<http://sourceware.org/newlib/>`_\ , while Arduino's is that of +`avr-libc <http://avr-libc.nongnu.org/>`_\ . + +See Also +-------- + +- :ref:`sin <lang-sin>` +- :ref:`cos <lang-cos>` +- :ref:`float <lang-float>` +- :ref:`double <lang-double>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/toggleled.rst b/docs/source/lang/api/toggleled.rst new file mode 100644 index 0000000..cad347f --- /dev/null +++ b/docs/source/lang/api/toggleled.rst @@ -0,0 +1,37 @@ +.. highlight:: cpp + +.. _lang-toggleled: + +toggleLED() +=========== + +*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 +-------- + +- :ref:`BOARD_LED_PIN <lang-board-values-led>` +- :ref:`togglePin() <lang-togglepin>` diff --git a/docs/source/lang/api/togglepin.rst b/docs/source/lang/api/togglepin.rst new file mode 100644 index 0000000..290718d --- /dev/null +++ b/docs/source/lang/api/togglepin.rst @@ -0,0 +1,17 @@ +.. _lang-togglepin: + +togglePin() +=========== + +Switches a digital output pin from :ref:`HIGH <lang-constants-high>` +to :ref:`LOW <lang-constants-low>`, or from LOW to HIGH. + +Library Documentation +--------------------- + +.. doxygenfunction:: togglePin + +See Also +-------- + +- :ref:`toggleLED() <lang-toggleled>` diff --git a/docs/source/lang/api/volatile.rst b/docs/source/lang/api/volatile.rst new file mode 100644 index 0000000..1b72897 --- /dev/null +++ b/docs/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 <arm-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 +<external-interrupts>`. (The only place that this is likely to occur +in most programs is inside of code called by 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 <external-interrupts>` +- :ref:`lang-attachinterrupt` +- :ref:`lang-detachinterrupt` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/waitforbuttonpress.rst b/docs/source/lang/api/waitforbuttonpress.rst new file mode 100644 index 0000000..0e0fbaf --- /dev/null +++ b/docs/source/lang/api/waitforbuttonpress.rst @@ -0,0 +1,43 @@ +.. highlight:: cpp + +.. _lang-waitforbuttonpress: + +waitForButtonPress() +==================== + +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 +<lang-board-values-but>`. + +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 +-------- + +- :ref:`Board-specific values <lang-board-values>` +- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>` +- :ref:`lang-isbuttonpressed` diff --git a/docs/source/lang/cc-attribution.txt b/docs/source/lang/cc-attribution.txt new file mode 100644 index 0000000..11302b2 --- /dev/null +++ b/docs/source/lang/cc-attribution.txt @@ -0,0 +1,10 @@ +.. Included in all this directory's files in order to satisfy the +.. Arduino CC Attribution-ShareAlike 3.0 License + +.. admonition:: License and Attribution + + Some information in this page was adapted from the `Arduino + Reference Documentation + <http://arduino.cc/en/Reference/HomePage>`_\ , which is released + under a `Creative Commons Attribution-ShareAlike 3.0 License + <http://creativecommons.org/licenses/by-sa/3.0/>`_. diff --git a/docs/source/lang/cpp/arithmetic.rst b/docs/source/lang/cpp/arithmetic.rst new file mode 100644 index 0000000..cef3954 --- /dev/null +++ b/docs/source/lang/cpp/arithmetic.rst @@ -0,0 +1,124 @@ +.. 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 <lang-int>`. + +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 <http://www2.research.att.com/~bs/3rd.html>`_\ , by Bjarne + Stroustroup, Appendix C, especially §§C.4-C.6, or `this WikiBooks + entry on C++ type conversion + <http://en.wikibooks.org/wiki/C%2B%2B_Programming/Programming_Languages/C%2B%2B/Code/Statements/Variables/Type_Casting#Automatic_type_conversion>`_. + +.. note:: For more information on how computers represent integers, + see the Wikipedia page on `two's complement + <http://en.wikipedia.org/wiki/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 <lang-constants-integers>` + default to :ref:`int <lang-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 :ref:`libmaple_types.h <libmaple-libmaple_types>`. + +- :ref:`sizeof <lang-sizeof>`\ () + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/array.rst b/docs/source/lang/cpp/array.rst new file mode 100644 index 0000000..39d4d91 --- /dev/null +++ b/docs/source/lang/cpp/array.rst @@ -0,0 +1,121 @@ +.. 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 <http://en.wikipedia.org/wiki/Null-terminated_string>`_. + + +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 <lang-for>`, 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 +<http://www.arduino.cc/en/Tutorial/KnightRider>`_\ (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 <arm-gcc-attribute-flash>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/assignment.rst b/docs/source/lang/cpp/assignment.rst new file mode 100644 index 0000000..6379298 --- /dev/null +++ b/docs/source/lang/cpp/assignment.rst @@ -0,0 +1,60 @@ +.. 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 + 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) +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 +-------- + +- :ref:`if <lang-if>` +- :ref:`char <lang-char>` +- :ref:`int <lang-int>` +- :ref:`long long <lang-longlong>` + +.. 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 + <http://icu-project.org/docs/papers/cpp_report/the_anatomy_of_the_assignment_operator.html>`_ + for more information. + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/bitshift.rst b/docs/source/lang/cpp/bitshift.rst new file mode 100644 index 0000000..47413f2 --- /dev/null +++ b/docs/source/lang/cpp/bitshift.rst @@ -0,0 +1,143 @@ +.. highlight:: cpp + +.. _lang-bitshift: + +Bit Shift Operators (``<<``, ``>>``) +==================================== + +(Adapted from `The Bit Math Tutorial +<http://www.arduino.cc/playground/Code/BitMath>`_ in `The Arduino +Playground <http://www.arduino.cc/playground/Main/HomePage>`_\ ) + +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 +<http://en.wikipedia.org/wiki/Bitwise_operation>`_\ , especially the +section on shifts in `C, C++, and Java +<http://en.wikipedia.org/wiki/Bitwise_operation#Shifts_in_C.2C_C.2B.2B.2C_C.23_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 + <lang-arithmetic-int-sizes>`\ ). + + + +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 +<http://en.wikipedia.org/wiki/Two%27s_complement>`_\ , 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 +<lang-arithmetic-int-sizes>` 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/bitwisemath.rst b/docs/source/lang/cpp/bitwisemath.rst new file mode 100644 index 0000000..cfe34f2 --- /dev/null +++ b/docs/source/lang/cpp/bitwisemath.rst @@ -0,0 +1,185 @@ +.. 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 +<http://www.arduino.cc/playground/Code/BitMath>`_\ . Another great +resource is the Wikipedia article on `bitwise operations +<http://en.wikipedia.org/wiki/Bitwise_operation>`_\ . + +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 toggle the built-in LED pin (you can also accomplish this +with :ref:`lang-toggleled`):: + + // Toggle built-in LED pin + + int toggle = 0; + + // demo for Exclusive OR + void setup(){ + pinMode(BOARD_LED_PIN, OUTPUT); + } + + void loop(){ + toggle = toggle ^ 1; + digitalWrite(BOARD_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. <http://en.wikipedia.org/wiki/Twos_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 +<http://en.wikipedia.org/wiki/Mask_%28computing%29>`_\ . 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 <http://www.hackersdelight.org/>`_\ . + + +See Also +-------- + +- :ref:`Boolean operations <lang-boolean>` (``&&``, ``||``) +- :ref:`Compound bitwise operations <lang-compoundbitwise>` (``&=``, + ``|=``, ``^=``). + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/boolean.rst b/docs/source/lang/cpp/boolean.rst new file mode 100644 index 0000000..f09345e --- /dev/null +++ b/docs/source/lang/cpp/boolean.rst @@ -0,0 +1,90 @@ +.. highlight:: cpp + +.. _lang-boolean: + +Boolean Operators +================= + +These can be used inside the condition of an :ref:`if <lang-if>` +statement. Evaluate to :ref:`true <lang-constants-true>` or +:ref:`false <lang-constants-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 + <lang-bitwisemath-and>` ``&`` (single ampersand). They are + entirely different beasts. + + Similarly, do not confuse the boolean OR operator ``||`` (double + pipe) with the :ref:`bitwise OR operator <lang-bitwisemath-or>` + ``|`` (single pipe). + + The :ref:`bitwise NOT operator <lang-bitwisemath-not>` ``~`` + (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 <lang-bitwisemath>` (``&``, ``|``, ``^``, ``~``) +- :ref:`Compound bitwise operators <lang-compoundbitwise>` (``&=``, + ``|=``, ``^=``). +- :ref:`if statement <lang-if>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/booleanvariables.rst b/docs/source/lang/cpp/booleanvariables.rst new file mode 100644 index 0000000..e032c74 --- /dev/null +++ b/docs/source/lang/cpp/booleanvariables.rst @@ -0,0 +1,47 @@ +.. highlight:: cpp + +.. _lang-booleanvariables: + +Booleans +======== + +A **boolean** holds one of two values, :ref:`true +<lang-constants-true>` or :ref:`false <lang-constants-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 +------- + +:: + + // running is a boolean variable: + bool running = false; + + void setup() { + pinMode(BOARD_LED_PIN, OUTPUT); + pinMode(BOARD_BUTTON_PIN, INPUT); + } + + void loop() { + if (isButtonPressed()) { + // button is pressed + running = !running; // toggle running variable + digitalWrite(BOARD_LED_PIN, running) // indicate via LED + } + } + +See Also +-------- + +- :ref:`Boolean constants <lang-constants-bool>` +- :ref:`Boolean operators <lang-boolean>` +- :ref:`Variables <lang-variables>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/break.rst b/docs/source/lang/cpp/break.rst new file mode 100644 index 0000000..f367b99 --- /dev/null +++ b/docs/source/lang/cpp/break.rst @@ -0,0 +1,32 @@ +.. highlight:: cpp + +.. _lang-break: + +``break`` +========= + +``break`` is used to exit from a :ref:`while <lang-while>`\ , +:ref:`for <lang-for>`\ , or :ref:`do/while <lang-dowhile>` loop, +bypassing the normal loop condition. It is also used to exit from a +:ref:`switch <lang-switchcase>` 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/built-in-types.rst b/docs/source/lang/cpp/built-in-types.rst new file mode 100644 index 0000000..f14dce5 --- /dev/null +++ b/docs/source/lang/cpp/built-in-types.rst @@ -0,0 +1,108 @@ +.. 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 <unix-toolchain>` will have access to +these types as long as they have imported `wirish.h +<https://github.com/leaflabs/libmaple/blob/master/wirish/wirish.h>`_; +several are defined in in `libmaple_types.h +<https://github.com/leaflabs/libmaple/blob/master/libmaple/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 + + 32-bit integer value. + +.. cpp:type:: long long + + 64-bit integer value. + +.. cpp:type:: int8 + + 8-bit integer value. Synonym for ``signed char``. + +.. cpp:type:: uint8 + + 8-bit unsigned integer value. Synonym for ``unsigned char``. + +.. cpp:type:: byte + + 8-bit unsigned integer value. Synonym for ``unsigned char``. + +.. cpp:type:: int16 + + 16-bit integer value. Synonym for ``short``. + +.. cpp:type:: uint16 + + 16-bit unsigned integer value. Synonym for ``unsigned short``. + +.. cpp:type:: int32 + + 32-bit integer value. Synonym for ``int``. + +.. cpp:type:: uint32 + + Unsigned 32-bit integer value. Synonym for ``unsigned int`` + +.. cpp:type:: int64 + + 64-bit integer value. Synonym for ``long long`` + +.. cpp:type:: uint64 + + 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. + +.. cpp:type:: double + + 64-bit, IEEE-754 double-precision floating-point type. + +Miscellaneous Types +------------------- + +.. cpp:type:: voidFuncPtr + + Pointer to a function that takes no arguments and returns nothing, i.e. :: + + typedef void (*voidFuncPtr)(void); + +.. 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. diff --git a/docs/source/lang/cpp/byte.rst b/docs/source/lang/cpp/byte.rst new file mode 100644 index 0000000..4634594 --- /dev/null +++ b/docs/source/lang/cpp/byte.rst @@ -0,0 +1,33 @@ +.. 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() <lang-bytecast>` (casting a value to a byte) +- :ref:`Variables <lang-variables>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/bytecast.rst b/docs/source/lang/cpp/bytecast.rst new file mode 100644 index 0000000..24c3b9e --- /dev/null +++ b/docs/source/lang/cpp/bytecast.rst @@ -0,0 +1,44 @@ +.. highlight:: cpp + +.. _lang-bytecast: + +byte() (cast) +============= + +Converts a value to the :ref:`byte <lang-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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/cc-attribution.txt b/docs/source/lang/cpp/cc-attribution.txt new file mode 100644 index 0000000..e100140 --- /dev/null +++ b/docs/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 <http://arduino.cc/en/Reference/HomePage>`_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License <http://creativecommons.org/licenses/by-sa/3.0/>`_. diff --git a/docs/source/lang/cpp/char.rst b/docs/source/lang/cpp/char.rst new file mode 100644 index 0000000..686c0d1 --- /dev/null +++ b/docs/source/lang/cpp/char.rst @@ -0,0 +1,44 @@ +.. 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 +<http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters>`_\ +. 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() +<lang-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() <lang-serial-println>` + +.. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/charcast.rst b/docs/source/lang/cpp/charcast.rst new file mode 100644 index 0000000..640ad85 --- /dev/null +++ b/docs/source/lang/cpp/charcast.rst @@ -0,0 +1,32 @@ +.. highlight:: cpp + +.. _lang-charcast: + +``char()`` (cast) +================= + +Converts a value to the :ref:`char <lang-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 <lang-char>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/comments.rst b/docs/source/lang/cpp/comments.rst new file mode 100644 index 0000000..1428dc3 --- /dev/null +++ b/docs/source/lang/cpp/comments.rst @@ -0,0 +1,64 @@ +.. 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/comparison.rst b/docs/source/lang/cpp/comparison.rst new file mode 100644 index 0000000..9cd0a9f --- /dev/null +++ b/docs/source/lang/cpp/comparison.rst @@ -0,0 +1,86 @@ +.. highlight:: cpp + +.. _lang-comparison: + +Comparison Operators (``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``) +=================================================================== + +The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and +``>=`` are used to compare two numbers. They are :ref:`true +<lang-constants-true>` when the comparison is true, and :ref:`false +<lang-constants-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 +<lang-boolean>`, are useful inside the conditionals of :ref:`if +<lang-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 <lang-assignment>`), so x now + contains 10. Then the 'if' conditional evaluates 10, which evaluates + to :ref:`true <lang-constants-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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/compoundarithmetic.rst b/docs/source/lang/cpp/compoundarithmetic.rst new file mode 100644 index 0000000..d70a43c --- /dev/null +++ b/docs/source/lang/cpp/compoundarithmetic.rst @@ -0,0 +1,43 @@ +.. 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 <lang-arithmetic>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/compoundbitwise.rst b/docs/source/lang/cpp/compoundbitwise.rst new file mode 100644 index 0000000..4efe5df --- /dev/null +++ b/docs/source/lang/cpp/compoundbitwise.rst @@ -0,0 +1,229 @@ +.. 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 <lang-bitwisemath>` 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``, ``char``, ``byte``, ``long long``, etc.). You can use either +an integer variable or any :ref:`integer value +<lang-constants-integers>` (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 + <lang-constants-integers-bin>`\ . 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 + <lang-constants-integers-hex>` or :ref:`octal + <lang-constants-integers-oct>` 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``, ``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 +<lang-compoundbitwise-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 <lang-compoundbitwise-binconst>` 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``, ``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:`&= +<lang-compoundbitwise-and>` and :ref:`\|= <lang-compoundbitwise-or>`; +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 <lang-compoundbitwise-binconst>` 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 <lang-boolean>` (``&&``, ``||``) +- :ref:`Bitwise operators <lang-bitwisemath>` (``&``, ``|``, ``^``, ``~``) + +.. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/const.rst b/docs/source/lang/cpp/const.rst new file mode 100644 index 0000000..ad0c580 --- /dev/null +++ b/docs/source/lang/cpp/const.rst @@ -0,0 +1,50 @@ +.. 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 <lang-scope>` that govern other +variables. This, and the pitfalls of using :ref:`#define +<lang-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 <lang-array>`\ , you will need +to use ``const``. In general, ``const`` is preferred over ``#define`` +for defining constants. + +See Also +-------- + +- :ref:`#define <lang-define>` +- :ref:`volatile <lang-volatile>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/continue.rst b/docs/source/lang/cpp/continue.rst new file mode 100644 index 0000000..2a694f6 --- /dev/null +++ b/docs/source/lang/cpp/continue.rst @@ -0,0 +1,30 @@ +.. highlight:: cpp + +.. _lang-continue: + +``continue`` +============ + +The ``continue`` keyword skips the rest of the current iteration of a +:ref:`while <lang-while>`\ , :ref:`for <lang-for>`\ , or +:ref:`do/while <lang-dowhile>` 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/curly-braces.rst b/docs/source/lang/cpp/curly-braces.rst new file mode 100644 index 0000000..df2fe2a --- /dev/null +++ b/docs/source/lang/cpp/curly-braces.rst @@ -0,0 +1,106 @@ +.. 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 <lang-while>`\ , :ref:`for +<lang-for>`\ , and :ref:`do/while <lang-dowhile>` 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 <lang-if>` +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 +<lang-switchcase>` reference page for more information):: + + switch (var) { + case 1: + doThing1(); + break; + case 2: + doThing2(); + break; + } + +.. rubric:: Footnotes + +.. [#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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/define.rst b/docs/source/lang/cpp/define.rst new file mode 100644 index 0000000..b22085f --- /dev/null +++ b/docs/source/lang/cpp/define.rst @@ -0,0 +1,54 @@ +.. 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 +<lang-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 MAPLE_LED_PIN 13 + // The compiler will replace any mention of MAPLE_LED_PIN with + // the value 13 at compile time. + +See Also +-------- +- :ref:`const <lang-const>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/double.rst b/docs/source/lang/cpp/double.rst new file mode 100644 index 0000000..59422eb --- /dev/null +++ b/docs/source/lang/cpp/double.rst @@ -0,0 +1,46 @@ +.. _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 <lang-variables-rollover>` 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 <http://en.wikipedia.org/wiki/Floating_point>`_\ . + +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 <lang-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 <lang-float>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/doublecast.rst b/docs/source/lang/cpp/doublecast.rst new file mode 100644 index 0000000..d3f32ce --- /dev/null +++ b/docs/source/lang/cpp/doublecast.rst @@ -0,0 +1,27 @@ +.. highlight:: cpp + +.. _lang-doublecast: + +``double()`` (cast) +=================== + +Converts a value to the :ref:`double <lang-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 long``), you will get strange results. + +See the :ref:`double <lang-double>` reference for details about the +precision and limitations of ``double`` values on the Maple. + +See Also +-------- + +- :ref:`double <lang-double>` +- :ref:`float <lang-float>` +- :ref:`float() <lang-floatcast>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/dowhile.rst b/docs/source/lang/cpp/dowhile.rst new file mode 100644 index 0000000..d229122 --- /dev/null +++ b/docs/source/lang/cpp/dowhile.rst @@ -0,0 +1,26 @@ +.. highlight:: cpp + +.. _lang-dowhile: + +``do``/``while`` +================ + +A ``do`` loop works in the same manner as a :ref:`while +<lang-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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/enum.rst b/docs/source/lang/cpp/enum.rst new file mode 100644 index 0000000..b6409eb --- /dev/null +++ b/docs/source/lang/cpp/enum.rst @@ -0,0 +1,52 @@ +.. 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 <lang-int>`:: + + // create a weather variable named theWeather, with value COMFY: + weather theWeather = COMFY; + +Enumeration types are useful within :ref:`switch statements +<lang-switchcase>`. 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 +<lang-switchcase-default>`, since we know that ``currentWeather`` must +be either ``HOT``, ``COMFY``, or ``COLD``. + +See Also +-------- + +- :ref:`lang-switchcase` diff --git a/docs/source/lang/cpp/float.rst b/docs/source/lang/cpp/float.rst new file mode 100644 index 0000000..5195fac --- /dev/null +++ b/docs/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 <lang-variables-rollover>` 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 +<lang-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 +<lang-floatcast>`:: + + 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 <lang-double>` +- :ref:`Variables <lang-variables>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/floatcast.rst b/docs/source/lang/cpp/floatcast.rst new file mode 100644 index 0000000..af92543 --- /dev/null +++ b/docs/source/lang/cpp/floatcast.rst @@ -0,0 +1,28 @@ +.. highlight:: cpp + +.. _lang-floatcast: + +``float()`` (cast) +================== + +Converts a value to the :ref:`float <lang-float>` data type. Here is +an example (see the :ref:`constants reference <lang-constants-fp>` 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 <lang-float>` reference for details about the +precision and limitations of ``float`` values on the Maple. + +See Also +-------- + +- :ref:`float <lang-float>` +- :ref:`double <lang-double>` +- :ref:`double() <lang-doublecast>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/for.rst b/docs/source/lang/cpp/for.rst new file mode 100644 index 0000000..78ea562 --- /dev/null +++ b/docs/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 +<lang-array>` to operate on collections of data or multiple +:ref:`pins <gpio>`. 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 <lang-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() <lang-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() +<lang-pwmwrite>` and :ref:`delay() <lang-delay>` happen next. At this +point, the post-loop expression ``i++`` is evaluated, which +:ref:`increments <lang-increment>` ``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() <lang-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 <lang-double>`. 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 +<http://en.wikipedia.org/wiki/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 <lang-while>` loops +- :ref:`do <lang-dowhile>` 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/goto.rst b/docs/source/lang/cpp/goto.rst new file mode 100644 index 0000000..2c0b3b0 --- /dev/null +++ b/docs/source/lang/cpp/goto.rst @@ -0,0 +1,129 @@ +.. 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 <goto-when-to-use>` + 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 <lang-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 <lang-variables>` 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 <ide-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 <lang-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 +<http://en.wikipedia.org/wiki/Goto#Criticism_and_decline>`_. However, +when used with care, ``goto`` can simplify certain programs. One +important use case for ``goto`` is breaking out of deeply nested +:ref:`for <lang-for>` loops or :ref:`if <lang-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 +<lang-analogread>` 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 <lang-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 <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.4846&rep=rep1&type=pdf>`_ (PDF) + +- Knuth, Donald. `Structured Programming with go to Statements <http://pplab.snu.ac.kr/courses/adv_pl05/papers/p261-knuth.pdf>`_ (PDF) + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/if.rst b/docs/source/lang/cpp/if.rst new file mode 100644 index 0000000..f248b05 --- /dev/null +++ b/docs/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 <lang-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 +<lang-comments>` 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 <lang-boolean>` or +:ref:`comparison <lang-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(pin, HIGH); + + if (x > 120) + digitalWrite(pin, HIGH); + + if (x > 120) { + digitalWrite(pin, HIGH); + } + +However, the following two examples are different:: + + // example 1: two lines of code in the if body + if (x > 120) { + 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(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 +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 <lang-if>` statement, by allowing multiple tests to +be grouped together. For example, an :ref:`analog input +<lang-analogread>` 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 <lang-switchcase>` statement. + + +See Also +-------- + +- :ref:`boolean operators <lang-boolean>` +- :ref:`comparison operators <lang-comparison>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/include.rst b/docs/source/lang/cpp/include.rst new file mode 100644 index 0000000..163509d --- /dev/null +++ b/docs/source/lang/cpp/include.rst @@ -0,0 +1,70 @@ +.. 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 +<http://arduino.cc/en/Tutorial/LiquidCrystal>`_) includes a library +that is used to control :ref:`LCD displays +<libraries-liquid-crystal>`:: + + // include the library code: + #include <LiquidCrystal.h> + + // 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 <lang-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 +<http://sourceware.org/newlib/>`_. Its main sources of documentation +are its `main reference <http://sourceware.org/newlib/libc.html>`_ +page and its `math functions +<http://sourceware.org/newlib/libm.html>`_ reference page. Here's an +example that imports the math.h library in order to take the `cube +root <http://en.wikipedia.org/wiki/Cube_root>`_ of a number:: + + #include <math.h> + + 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/increment.rst b/docs/source/lang/cpp/increment.rst new file mode 100644 index 0000000..c423d1a --- /dev/null +++ b/docs/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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/int.rst b/docs/source/lang/cpp/int.rst new file mode 100644 index 0000000..fa63946 --- /dev/null +++ b/docs/source/lang/cpp/int.rst @@ -0,0 +1,68 @@ +.. 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 +<http://en.wikipedia.org/wiki/Two%27s_complement#Explanation>`_\ . +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 <lang-bitshift-signbit-gotcha>` in +dealing with the :ref:`bitshift right operator (>>) +<lang-bitshift>`, however. + +.. _lang-long: + +The ``long`` type is a synonym for ``int``. + +Here is an example of declaring an ``int`` variable named ``pin``, +then giving it value 13:: + + int pin = 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 <lang-variables-rollover>` 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 <lang-unsignedint>` +- :ref:`char <lang-char>` +- :ref:`unsigned char <lang-unsignedchar>` +- :ref:`long long <lang-longlong>` +- :ref:`unsigned long long <lang-unsignedlonglong>` +- :ref:`Integer Constants <lang-constants-integers>` +- :ref:`Variables <lang-variables>` + +.. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/intcast.rst b/docs/source/lang/cpp/intcast.rst new file mode 100644 index 0000000..da838c7 --- /dev/null +++ b/docs/source/lang/cpp/intcast.rst @@ -0,0 +1,26 @@ +.. highlight:: cpp + +.. _lang-intcast: + +``int()`` (cast) +================ + +Converts a value to the :ref:`int <lang-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 <lang-int>` reference for details about the +precision and limitations of ``int`` variables on the Maple. + +See Also +-------- + +- :ref:`int <lang-int>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/keywords.rst b/docs/source/lang/cpp/keywords.rst new file mode 100644 index 0000000..f21cd0d --- /dev/null +++ b/docs/source/lang/cpp/keywords.rst @@ -0,0 +1,204 @@ +.. _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:`&& <lang-boolean-and>`. +- ``not`` is a synonym for :ref:`\! <lang-boolean-not>`. +- ``not_eq`` is a synonym for :ref:`\!= <lang-comparison>`. +- ``or`` is a synonym for :ref:`|| <lang-boolean-or>`. + +Bitwise Operator Synonyms +------------------------- + +- ``and_eq`` is a synonym for :ref:`&= <lang-compoundbitwise-and>`. +- ``bitand`` is a synonym for (bitwise) :ref:`& <lang-bitwisemath-and>`. +- ``bitor`` is a synonym for :ref:`\| <lang-bitwisemath-or>`. +- ``compl`` is a synonym for :ref:`~ <lang-bitwisemath-not>`. +- ``or_eq`` is a synonym for :ref:`|= <lang-compoundbitwise-or>`. +- ``xor`` is a synonym for :ref:`^ <lang-bitwisemath-xor>`. +- ``xor_eq`` is a synonym for :ref:`^= <lang-compoundbitwise-xor>`. + +Constants +--------- + +- ``true`` and ``false`` are the :ref:`boolean constants + <lang-booleanvariables>`. + +Control Flow +------------ + +- ``break`` can exit out of a :ref:`switch statement + <lang-switchcase>` or a :ref:`for <lang-for>`, :ref:`do + <lang-dowhile>`, or :ref:`while <lang-while>` loop. + +- ``case`` defines alternatives in a :ref:`switch statement <lang-switchcase>`. + +- ``continue`` will move control flow to the next iteration of the + enclosing :ref:`for <lang-for>`, :ref:`do <lang-dowhile>`, or + :ref:`while <lang-while>` loop. + +- ``default`` defines the default alternative in a :ref:`switch + statement <lang-switchcase>`. + +- ``do`` introduces a :ref:`do <lang-dowhile>` loop. + +- ``else`` is used in :ref:`if statements <lang-if>`. + +- ``for`` introduces a :ref:`for <lang-for>` loop. + +- ``goto`` :ref:`jumps <lang-goto>` to a label. + +- ``if`` introduces an :ref:`if statement <lang-if>`. + +- ``return`` :ref:`transfers flow to a function's caller <lang-return>`. + +- ``switch`` introduces a :ref:`switch statement <lang-switchcase>`. + +- ``while`` introduces a :ref:`while <lang-while>` loop. + +Types +----- + +The following keywords are used for built-in types. + +- :ref:`bool <lang-booleanvariables>` +- :ref:`char <lang-char>` +- :ref:`double <lang-double>` +- :ref:`float <lang-float>` +- :ref:`int <lang-int>` +- :ref:`long <lang-long>` +- :ref:`short <lang-built-in-types-integral>` +- :ref:`void <lang-void>` (not really a type, but used in the absence + of one) + +The following keywords are used to introduce new types. + +- :ref:`enum <lang-enum>` + +Qualifiers +---------- + +- :ref:`static <lang-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:`volatile <lang-volatile>` is useful when declaring variables + that may be modified by external interrupts. + +- :ref:`const <lang-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 <arm-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 <arm-gcc>` include ``-fno-exceptions``. + +- ``try`` is used in exception handling. Note that the default + flags we pass to :ref:`GCC <arm-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/docs/source/lang/cpp/longcast.rst b/docs/source/lang/cpp/longcast.rst new file mode 100644 index 0000000..493ad67 --- /dev/null +++ b/docs/source/lang/cpp/longcast.rst @@ -0,0 +1,27 @@ +.. highlight:: cpp + +.. _lang-longcast: + +``long()`` (cast) +================= + +Converts a value to the :ref:`long <lang-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 <lang-long>` reference for details about the +precision and limitations of ``long`` variables on the Maple. + +See Also +-------- + +- :ref:`long <lang-long>` +- :ref:`long long <lang-longlong>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/longlong.rst b/docs/source/lang/cpp/longlong.rst new file mode 100644 index 0000000..d942cb4 --- /dev/null +++ b/docs/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 <lang-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 <lang-variables-rollover>` 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 <lang-constants-integers-u-l>` 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 +<lang-int-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 <lang-arithmetic>` +operations on ``long long``\ s will take slightly longer than on +``int``\ s. + +See Also +-------- + +- :ref:`char <lang-char>` +- :ref:`unsigned char <lang-unsignedchar>` +- :ref:`int <lang-int>` +- :ref:`unsigned int <lang-unsignedint>` +- :ref:`unsigned long long <lang-unsignedlonglong>` +- :ref:`Integer Constants <lang-constants-integers>` +- :ref:`Variables <lang-variables>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/modulo.rst b/docs/source/lang/cpp/modulo.rst new file mode 100644 index 0000000..013d07e --- /dev/null +++ b/docs/source/lang/cpp/modulo.rst @@ -0,0 +1,70 @@ +.. highlight:: cpp + +.. _lang-modulo: + +Modulo Operator (``%``) +======================= + +Calculates the `remainder <http://en.wikipedia.org/wiki/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() +<http://sourceware.org/newlib/libm.html#fmod>`_. + +See Also +-------- + +- :ref:`Arithmetic <lang-arithmetic>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/pointer.rst b/docs/source/lang/cpp/pointer.rst new file mode 100644 index 0000000..ff4ec32 --- /dev/null +++ b/docs/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:`& +<lang-bitwisemath-and>` and the arithmetic operator :ref:`* +<lang-arithmetic>`. + +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 +<http://www.cplusplus.com/doc/tutorial/pointers/>`_ is available. +Also see the `Wikipedia article on pointers +<http://en.wikipedia.org/wiki/Pointer_%28computing%29>`_, especially +the section on `pointers in C +<http://en.wikipedia.org/wiki/Pointer_%28computing%29#C_pointers>`_. + +See Also +-------- + +- http://xkcd.com/138/ + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/return.rst b/docs/source/lang/cpp/return.rst new file mode 100644 index 0000000..d9aecbe --- /dev/null +++ b/docs/source/lang/cpp/return.rst @@ -0,0 +1,60 @@ +.. 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 ``double``, etc.; see :ref:`this note +<lang-arithmetic-typeconversion>` 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 <lang-comments>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/scope.rst b/docs/source/lang/cpp/scope.rst new file mode 100644 index 0000000..a270428 --- /dev/null +++ b/docs/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 <ide>`, any variable declared outside +of a function (like :ref:`setup() <lang-setup>` and :ref:`loop() +<lang-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 <lang-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 <lang-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 <ide-serial-monitor>` after you +:ref:`verify <ide-verify>` and :ref:`upload <ide-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 <http://en.wikibooks.org/wiki/C%2B%2B_Programming/Programming_Languages/C%2B%2B/Code/Statements/Scope>`_. +- Wikipedia article on `scope <http://en.wikipedia.org/wiki/Scope_%28programming%29>`_ + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/semicolon.rst b/docs/source/lang/cpp/semicolon.rst new file mode 100644 index 0000000..05e6218 --- /dev/null +++ b/docs/source/lang/cpp/semicolon.rst @@ -0,0 +1,22 @@ +.. 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/sizeof.rst b/docs/source/lang/cpp/sizeof.rst new file mode 100644 index 0000000..ec2dea6 --- /dev/null +++ b/docs/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 <lang-for>` +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:: /arduino-cc-attribution.txt + diff --git a/docs/source/lang/cpp/sqrt.rst b/docs/source/lang/cpp/sqrt.rst new file mode 100644 index 0000000..fbabf82 --- /dev/null +++ b/docs/source/lang/cpp/sqrt.rst @@ -0,0 +1,24 @@ +.. _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 <lang-pow>` +- :ref:`sq <lang-sq>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/static.rst b/docs/source/lang/cpp/static.rst new file mode 100644 index 0000000..8c52ba0 --- /dev/null +++ b/docs/source/lang/cpp/static.rst @@ -0,0 +1,56 @@ +.. 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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/string.rst b/docs/source/lang/cpp/string.rst new file mode 100644 index 0000000..3497484 --- /dev/null +++ b/docs/source/lang/cpp/string.rst @@ -0,0 +1,120 @@ +.. highlight:: cpp + +.. _lang-string: + +Strings +======= + +Text strings on the Maple can be represented with null-terminated +arrays of type :ref:`char <lang-char>`. + +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 +<http://en.wikipedia.org/wiki/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 <lang-array>` +- :ref:`__attribute__ <arm-gcc-attribute-flash>` +- :ref:`Variables <lang-variables>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/switchcase.rst b/docs/source/lang/cpp/switchcase.rst new file mode 100644 index 0000000..e31ccf3 --- /dev/null +++ b/docs/source/lang/cpp/switchcase.rst @@ -0,0 +1,118 @@ +.. highlight:: cpp + +.. _lang-switchcase: + +``switch``\ /\ ``case`` +======================= + +Like :ref:`if <lang-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 <lang-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 <lang-if>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/unsignedchar.rst b/docs/source/lang/cpp/unsignedchar.rst new file mode 100644 index 0000000..45fedeb --- /dev/null +++ b/docs/source/lang/cpp/unsignedchar.rst @@ -0,0 +1,32 @@ +.. highlight:: cpp + +.. _lang-unsignedchar: + +``unsigned char`` +================= + +An unsigned version of the :ref:`char <lang-char>` data type. An +``unsigned char`` occupies 1 byte of memory; it stores an integer from +0 to 255. + +Like an :ref:`unsigned int <lang-unsignedint>`, an ``unsigned char`` +won't store negative numbers; it is also subject to the same +:ref:`overflow issues <lang-int-overflow>` as any integral data type. + +Example +------- + + :: + + unsigned char c = 240; + +See Also +-------- + +- :ref:`byte <lang-byte>` +- :ref:`int <lang-int>` +- :ref:`array <lang-array>` +- :ref:`SerialUSB.println() <lang-serialusb-println>` +- :ref:`Serial.println() <lang-serial-println>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/unsignedint.rst b/docs/source/lang/cpp/unsignedint.rst new file mode 100644 index 0000000..f8ea473 --- /dev/null +++ b/docs/source/lang/cpp/unsignedint.rst @@ -0,0 +1,59 @@ +.. highlight:: cpp + +.. _lang-unsignedint: + +``unsigned int`` +================ + +An ``unsigned int`` (unsigned integer) is the same as an :ref:`int +<lang-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 +<http://en.wikipedia.org/wiki/Two%27s_complement#Explanation>`_. The +bits in an an ``unsigned int`` are interpreted according to the usual +rules for converting `binary to decimal +<http://en.wikipedia.org/wiki/Binary_numeral_system#Counting_in_binary>`_. + +An ``unsigned int`` is subject to the same :ref:`overflow issues +<lang-int-overflow>` 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" + +.. _lang-unsignedlong: + +The ``unsigned long`` type is a synonym for ``unsigned int``. + +Here is an example of declaring an ``unsigned int`` variable named +``pin``, then giving it value 13:: + + unsigned int pin = 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 <lang-int>` +- :ref:`char <lang-char>` +- :ref:`unsigned char <lang-unsignedchar>` +- :ref:`long long <lang-longlong>` +- :ref:`unsigned long long <lang-unsignedlonglong>` +- :ref:`Integer Constants <lang-constants-integers>` +- :ref:`Variables <lang-variables>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/unsignedlonglong.rst b/docs/source/lang/cpp/unsignedlonglong.rst new file mode 100644 index 0000000..a1143f0 --- /dev/null +++ b/docs/source/lang/cpp/unsignedlonglong.rst @@ -0,0 +1,43 @@ +.. highlight:: cpp + +.. _lang-unsignedlonglong: + +``unsigned long long`` +====================== + +An unsigned version of the :ref:`long long <lang-longlong>` 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 <lang-unsignedint>`, an ``unsigned long +long`` won't store negative numbers; it is also subject to the same +:ref:`overflow issues <lang-int-overflow>` 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 <lang-constants-integers-u-l>` 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 <lang-longlong>` +- :ref:`int <lang-int>` +- :ref:`unsigned <lang-unsignedint>` +- :ref:`char <lang-char>` +- :ref:`unsigned char <lang-unsignedchar>` +- :ref:`Integer Constants <lang-constants-integers>` +- :ref:`Variables <lang-variables>` + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst new file mode 100644 index 0000000..9ffdd1d --- /dev/null +++ b/docs/source/lang/cpp/variables.rst @@ -0,0 +1,169 @@ +.. 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 <lang-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 <lang-built-in-types>` page +for more information. + +Here are a few examples of declaring variables of different types:: + + int lightSensVal; + char currentLetter; + unsigned long long speedOfLight = 186000ULL; + 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 <lang-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 <lang-scope>` 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 <lang-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 <lang-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 <lang-assignment>`, 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-built-in-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 + <http://en.wikipedia.org/wiki/Two%27s_complement>`_ on computers. + +.. include:: /arduino-cc-attribution.txt + diff --git a/docs/source/lang/cpp/void.rst b/docs/source/lang/cpp/void.rst new file mode 100644 index 0000000..7af0acd --- /dev/null +++ b/docs/source/lang/cpp/void.rst @@ -0,0 +1,31 @@ +.. highlight:: cpp + +.. _lang-void: + +``void`` +======== + +.. 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 +------- + +:: + + // actions are performed in the functions "setup" and "loop" + // but no information is reported to the larger program + + void setup() { + // ... + } + + void loop() { + // ... + } + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/while.rst b/docs/source/lang/cpp/while.rst new file mode 100644 index 0000000..e66e0aa --- /dev/null +++ b/docs/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 <lang-constants-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:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/unimplemented/notone.rst b/docs/source/lang/unimplemented/notone.rst new file mode 100644 index 0000000..8af878b --- /dev/null +++ b/docs/source/lang/unimplemented/notone.rst @@ -0,0 +1,37 @@ +.. _lang-notone: + +noTone() +======== + +Description +----------- + +Stops the generation of a square wave triggered by +`tone <http://arduino.cc/en/Reference/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 <http://arduino.cc/en/Reference/Tone>`_ () + +.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/unimplemented/pulsein.rst b/docs/source/lang/unimplemented/pulsein.rst new file mode 100644 index 0000000..2b52428 --- /dev/null +++ b/docs/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 <http://arduino.cc/en/Reference/Constants>`_ or +`LOW <http://arduino.cc/en/Reference/Constants>`_. (*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/docs/source/lang/unimplemented/stringclass.rst b/docs/source/lang/unimplemented/stringclass.rst new file mode 100644 index 0000000..b893e83 --- /dev/null +++ b/docs/source/lang/unimplemented/stringclass.rst @@ -0,0 +1,6 @@ +.. _lang-stringclass: + +String Class +============ + +.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/unimplemented/stringobject.rst b/docs/source/lang/unimplemented/stringobject.rst new file mode 100644 index 0000000..e47ed7e --- /dev/null +++ b/docs/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 <http://arduino.cc/en/Reference/StringConstructor>`_\ () +- `charAt <http://arduino.cc/en/Reference/StringCharAt>`_\ () +- `compareTo <http://arduino.cc/en/Reference/StringCompareTo>`_\ () +- `concat <http://arduino.cc/en/Reference/StringConcat>`_\ () +- `endsWith <http://arduino.cc/en/Reference/StringEndsWith>`_\ () +- `equals <http://arduino.cc/en/Reference/StringEquals>`_\ () +- `equalsIgnoreCase <http://arduino.cc/en/Reference/StringEqualsIgnoreCase>`_\ () +- `getBytes <http://arduino.cc/en/Reference/StringGetBytes>`_\ () +- `indexOf <http://arduino.cc/en/Reference/StringIndexOf>`_\ () +- `lastIndexOf <http://arduino.cc/en/Reference/StringLastIndexOf>`_\ () +- `length <http://arduino.cc/en/Reference/StringLength>`_\ () +- `replace <http://arduino.cc/en/Reference/StringReplace>`_\ () +- `setCharAt <http://arduino.cc/en/Reference/StringSetCharAt>`_\ () +- `startsWith <http://arduino.cc/en/Reference/StringStartsWith>`_\ () +- `substring <http://arduino.cc/en/Reference/StringSubstring>`_\ () +- `toCharArray <http://arduino.cc/en/Reference/StringToCharArray>`_\ () +- `toLowerCase <http://arduino.cc/en/Reference/StringToLowerCase>`_\ () +- `toUpperCase <http://arduino.cc/en/Reference/StringToUpperCase>`_\ () +- `trim <http://arduino.cc/en/Reference/StringTrim>`_\ () + + + +Operators +--------- + + +- `[] (element access) <http://arduino.cc/en/Reference/StringBrackets>`_ +- `+ (concatenation) <http://arduino.cc/en/Reference/StringPlus>`_ +- `== (comparison) <http://arduino.cc/en/Reference/StringComparison>`_ + + + +Examples +-------- + + +- `StringConstructors <http://arduino.cc/en/Tutorial/StringConstructors>`_ +- `StringAdditionOperator <http://arduino.cc/en/Tutorial/StringAdditionOperator>`_ +- `StringIndexOf <http://arduino.cc/en/Tutorial/StringIndexOf>`_ +- `StringAppendOperator <http://arduino.cc/en/Tutorial/StringAppendOperator>`_ +- `StringLengthTrim <http://arduino.cc/en/Tutorial/StringLengthTrim>`_ +- `StringCaseChanges <http://arduino.cc/en/Tutorial/StringCaseChanges>`_ +- `StringReplace <http://arduino.cc/en/Tutorial/StringReplace>`_ +- `StringCharacters <http://arduino.cc/en/Tutorial/StringCharacters>`_ +- `StringStartsWithEndsWith <http://arduino.cc/en/Tutorial/StringStartsWithEndsWith>`_ +- `StringComparisonOperators <http://arduino.cc/en/Tutorial/StringComparisonOperators>`_ +- `StringSubstring <http://arduino.cc/en/Tutorial/StringSubstring>`_ + + + +See Also +-------- + + +- `Character array strings <http://arduino.cc/en/Reference/String>`_ +- `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_ + + + + +.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/unimplemented/tone.rst b/docs/source/lang/unimplemented/tone.rst new file mode 100644 index 0000000..13d581e --- /dev/null +++ b/docs/source/lang/unimplemented/tone.rst @@ -0,0 +1,58 @@ +.. _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 <http://arduino.cc/en/Reference/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 <http://arduino.cc/en/Reference/NoTone>`_\ () +- `analogWrite <http://arduino.cc/en/Reference/AnalogWrite>`_\ () +- `Tutorial:Tone <http://arduino.cc/en/Tutorial/Tone>`_ +- `Tutorial:Pitch follower <http://arduino.cc/en/Tutorial/Tone2>`_ +- `Tutorial:Simple Keyboard <http://arduino.cc/en/Tutorial/Tone3>`_ +- `Tutorial: multiple tones <http://arduino.cc/en/Tutorial/Tone4>`_ +- `Tutorial: PWM <http://arduino.cc/en/Tutorial/PWM>`_ + +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/language-index.rst b/docs/source/language-index.rst new file mode 100644 index 0000000..5e4c609 --- /dev/null +++ b/docs/source/language-index.rst @@ -0,0 +1,50 @@ +.. _language-index: + +======================= +Complete Language Index +======================= + +This is the index of Maple's :ref:`language reference +<language-lang-docs>` documentation. The "Maple API" column provides +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. + +.. 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), see :ref:`this FAQ <faq-atoi>`. + + - If you're looking for pointers to low-level details, see the + :ref:`Language Recommended Reading + <language-recommended-reading>` and :ref:`libmaple` pages. + +.. _index-language-index-cpp: +.. _index-language-index-api: + ++----------------------------------+------------------------------------+ +| Maple API | C++ for Maple | +| | | ++==================================+====================================+ +| | | +| .. toctree:: | .. toctree:: | +| :maxdepth: 1 | :maxdepth: 1 | +| :glob: | :glob: | +| | | +| lang/api/* | lang/cpp/* | +| | | ++----------------------------------+------------------------------------+ + +.. 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 diff --git a/docs/source/language.rst b/docs/source/language.rst new file mode 100644 index 0000000..a24bb5f --- /dev/null +++ b/docs/source/language.rst @@ -0,0 +1,431 @@ +.. highlight:: c++ + +.. _language: + +==================== + Language Reference +==================== + +The Maple can be programmed in the `Wiring +<http://www.wiring.org.co/reference/>`_ language, which is the same +language used to program the `Arduino <http://arduino.cc/>`_ boards. +C or C++ programmers who are new to Wiring may wish to skip to the +:ref:`arduino_c_for_c_hackers`. + +.. contents:: Contents + :local: + +.. admonition:: Looking for something else? Try these + + - See the :ref:`libraries` for extra built-in libraries. + + - If you prefer C or C++ over Wiring, see :ref:`libmaple` and the + :ref:`unix-toolchain`. + + - If you're looking for something from the C standard library (like + ``atoi()``, for instance), see :ref:`this FAQ <faq-atoi>`. + + - An :ref:`stm32` and other :ref:`language-recommended-reading` are + also available. + +.. _language-lang-docs: + +Maple Language Reference +------------------------ + +This table is a summary of the most important language features. See +the :ref:`language-index` for a complete listing. + ++--------------------------------------------+----------------------------------------------+---------------------------------------------------+ +| Structure | Variables | Functions | +| | | | ++============================================+==============================================+===================================================+ +|* :ref:`setup() <lang-setup>` |**Constants** |**Digital I/O** | +| | | | +|* :ref:`loop() <lang-loop>` |* :ref:`HIGH <lang-constants-high>` | |* :ref:`pinMode() <lang-pinmode>` | +| | :ref:`LOW <lang-constants-low>` | | +| | |* :ref:`digitalWrite() <lang-digitalwrite>` | +|**Control Structures** |* :ref:`INPUT <lang-constants-input>` | | | +| | :ref:`OUTPUT <lang-constants-output>` |* :ref:`digitalRead() <lang-digitalread>` | +|* :ref:`if/else <lang-if>` | | | +| |* :ref:`true <lang-constants-true>` | |* :ref:`togglePin() <lang-togglepin>` | +|* :ref:`for <lang-for>` | :ref:`false <lang-constants-false>` | | +| | |* :ref:`toggleLED() <lang-toggleled>` | +|* :ref:`switch/case <lang-switchcase>` |* :ref:`Constants | | +| | <lang-constants>` (:ref:`integers |* :ref:`isButtonPressed() <lang-isbuttonpressed>` | +|* :ref:`while <lang-while>` | <lang-constants-integers>`, :ref:`floating | | +| | point <lang-constants-fp>`) |* :ref:`waitForButtonPress() | +|* :ref:`do...while <lang-dowhile>` | | <lang-waitforbuttonpress>` | +| |* :ref:`Board-specific values | | +|* :ref:`break <lang-break>` | <lang-board-values>` |**Analog I/O** | +| | | | +|* :ref:`continue <lang-continue>` |**Data Types** |* :ref:`analogRead() <lang-analogread>` | +| | | | +|* :ref:`return <lang-return>` | The size of each data type, in bytes, is |* :ref:`pwmWrite() <lang-pwmwrite>` | +| | given in parentheses where appropriate. | (:ref:`analogWrite() <lang-analogwrite>` is | +|* :ref:`goto <lang-goto>` | | also available, though its use is discouraged) | +| | *Note*: The ``word`` type is (deliberately) | | +| | :ref:`not supported <language-no-word>`. | | +|**Further syntax** | |**Advanced I/O** | +| |* :ref:`void <lang-void>` | | +|* :ref:`; (semicolon) <lang-semicolon>` | |* tone(): TODO | +| |* :ref:`boolean <lang-boolean>` (1 byte) | | +|* :ref:`{} (curly braces) | |* noTone(): TODO | +| <lang-curly-braces>` |* :ref:`char <lang-char>` (1 byte) | | +| | |* :ref:`shiftOut() <lang-shiftout>` | +|* :ref:`// (single-line comment) |* :ref:`unsigned char | | +| <lang-comments-singleline>` | <lang-unsignedchar>` (1 byte) |* pulseIn(): TODO | +| | | | +|* :ref:`/\* \*/ (multi-line comment) |* :ref:`byte <lang-byte>` (1 byte) | | +| <lang-comments-multiline>` | |**Time** | +| |* :ref:`int <lang-int>` (4 bytes) | | +|* :ref:`#define <lang-define>` | |* :ref:`millis() <lang-millis>` | +| |* :ref:`unsigned int <lang-unsignedint>` | | +|* :ref:`#include <lang-include>` | (4 bytes) |* :ref:`micros() <lang-micros>` | +| | | | +| |* ``long`` (4 bytes), synonym for :ref:`int |* :ref:`delay() <lang-delay>` | +|**Arithmetic Operators** | <lang-int>` | | +| | |* :ref:`delayMicroseconds() | +|* :ref:`= <lang-assignment>` |* ``unsigned long`` (4 bytes), synonym for | <lang-delaymicroseconds>` | +| (assignment) | :ref:`unsigned int <lang-unsignedint>` | | +| | | | +|* :ref:`+ <lang-arithmetic>` (addition) |* :ref:`long long <lang-longlong>` (8 bytes) |**Math** | +| | | | +|* :ref:`- <lang-arithmetic>` |* :ref:`unsigned long |* :ref:`min() <lang-min>` | +| (subtraction) | long <lang-unsignedlonglong>` (8 bytes) | | +| | |* :ref:`max() <lang-max>` | +|* :ref:`* <lang-arithmetic>` |* :ref:`float <lang-float>` (4 bytes) | | +| (multiplication) | |* :ref:`abs() <lang-abs>` | +| |* :ref:`double <lang-double>` (8 bytes) | | +|* :ref:`/ <lang-arithmetic>` (division) | |* :ref:`constrain() <lang-constrain>` | +| |* :ref:`strings <lang-string>` | | +|* :ref:`% <lang-modulo>` (modulo) | |* :ref:`map() <lang-map>` | +| |* :ref:`arrays <lang-array>` | | +| | |* :ref:`pow() <lang-pow>` | +|**Comparison Operators** |* :ref:`enum <lang-enum>` | | +| | |* :ref:`sqrt() <lang-sqrt>` | +|* :ref:`== <lang-comparison>` (equal to) |* :ref:`numeric types <lang-built-in-types>` | | +| | | | +|* :ref:`\!= <lang-comparison>` |**Conversion** |**Trigonometry** | +| (not equal to) | | | +| |* :ref:`char() <lang-charcast>` |* :ref:`sin() <lang-sin>` | +|* :ref:`< <lang-comparison>` (less than) | | | +| |* :ref:`byte() <lang-bytecast>` |* :ref:`cos() <lang-cos>` | +|* :ref:`> <lang-comparison>` | | | +| (greater than) |* :ref:`int() <lang-intcast>` |* :ref:`tan() <lang-tan>` | +| | | | +|* :ref:`<= <lang-comparison>` |* :ref:`long() <lang-longcast>` | | +| (less than or equal to) | |**Random Numbers** | +| |* :ref:`float() <lang-floatcast>` | | +|* :ref:`>= <lang-comparison>` | |* :ref:`randomSeed() <lang-randomseed>` | +| (greater than or equal to) |* :ref:`double() <lang-doublecast>` | | +| | |* :ref:`random() <lang-random>` | +| | | | +|**Boolean Operators** |**Variable Scope & Qualifiers** | | +| | |**Bits and Bytes** | +|* :ref:`&& <lang-boolean-and>` (and) |* :ref:`variables <lang-variables>`, | | +| | :ref:`scope <lang-variables-scope>` |* :ref:`lowByte() <lang-lowbyte>` | +|* :ref:`|| <lang-boolean-or>` (or) | | | +| |* :ref:`static <lang-static>` |* :ref:`highByte() <lang-highbyte>` is | +|* :ref:`\! <lang-boolean-not>` (not) | | provided, though its use is discouraged. | +| |* :ref:`volatile <lang-volatile>` | | +| | |* :ref:`bitRead() <lang-bitread>` | +|**Pointer Operators** |* :ref:`const <lang-const>` | | +| | |* :ref:`bitWrite() <lang-bitwrite>` | +|* :ref:`* dereference operator | | | +| <lang-pointer>` |**Utilities** |* :ref:`bitSet() <lang-bitset>` | +| | | | +|* :ref:`& reference operator |* :ref:`sizeof() <lang-sizeof>` |* :ref:`bitClear() <lang-bitclear>` | +| <lang-pointer>` | | | +| |* :ref:`ASSERT() <lang-assert>` |* :ref:`bit() <lang-bit>` | +| | | | +|**Bitwise Operators** | | | +| | |**External Interrupts** | +|* :ref:`& <lang-bitwisemath-and>` | | | +| (bitwise and) | |* :ref:`Reference Page <external-interrupts>` | +| | | | +|* :ref:`| <lang-bitwisemath-or>` | |* :ref:`attachInterrupt() | +| (bitwise or) | | <lang-attachinterrupt>` | +| | | | +|* :ref:`^ <lang-bitwisemath-xor>` | |* :ref:`detachInterrupt() | +| (bitwise xor) | | <lang-detachinterrupt>` | +| | | | +|* :ref:`~ <lang-bitwisemath-not>` | | | +| (bitwise not) | |**Interrupts** | +| | | | +|* :ref:`\<\< <lang-bitshift>` | |* :ref:`interrupts() <lang-interrupts>` | +| (shift left) | | | +| | |* :ref:`noInterrupts() <lang-nointerrupts>` | +|* :ref:`>> <lang-bitshift>` | | | +| (shift right) | | | +| | |**Communication** | +| | | | +|**Compound Operators** | |* :ref:`SerialUSB <lang-serialusb>` | +| | | | +|* :ref:`++ <lang-increment>` | |* :ref:`Serial <lang-serial>` | +| (increment) | | | +| | | | +|* :ref:`- - <lang-increment>` | | | +| (decrement) | | | +| | | | +|* :ref:`+= <lang-compoundarithmetic>` | | | +| (compound add) | | | +| | | | +|* :ref:`-= | | | +| <lang-compoundarithmetic>` (compound | | | +| subtract) | | | +| | | | +|* :ref:`*= | | | +| <lang-compoundarithmetic>` (compound | | | +| multiply) | | | +| | | | +|* :ref:`/= | | | +| <lang-compoundarithmetic>` (compound | | | +| divide) | | | +| | | | +|* :ref:`&= | | | +| <lang-compoundbitwise>` (compound | | | +| bitwise and) | | | +| | | | +|* :ref:`|= | | | +| <lang-compoundbitwise>` (compound | | | +| bitwise or) | | | +| | | | +|**Keywords** | | | +| | | | +|* :ref:`C++ Keywords <lang-keywords>` | | | +| | | | +| | | | ++--------------------------------------------+----------------------------------------------+---------------------------------------------------+ + +.. _language-missing-features: + +Missing Arduino Features +------------------------ + +.. _langage-missing-analogreference: + +**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; + +Unimplemented Arduino Features +------------------------------ + +The following Wiring/Arduino features are currently unimplemented on +the Maple. + +- `tone() <http://www.arduino.cc/en/Reference/Tone>`_ +- `noTone() <http://www.arduino.cc/en/Reference/NoTone>`_ +- `pulseIn() <http://www.arduino.cc/en/Reference/PulseIn>`_ +- `String <http://arduino.cc/en/Reference/StringObject>`_ + +.. _our reference page: http://leaflabs.com/docs/external-interrupts/ + +.. _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:`Language Index +<language-index>`. It provides some introductory coverage of +programming ideas and C++. + +.. _arduino_c_for_c_hackers: + +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. + +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 +<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 the details, 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 +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 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``, 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, 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 +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 +<http://www.retrologic.com/jargon/B/Bad-and-Wrong.html>`_. 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 +<https://github.com/leaflabs/libmaple/blob/master/wirish/WProgram.h>`_ +(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 +``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(); + + // Call user loop() forever. + 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() { + togglePin(the_pin); + } + +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() { + togglePin(the_pin); + } + + 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() { + togglePin(the_pin); + } + + int choose_a_pin(void); + + int choose_a_pin() { + return random(5, 15); + } + + int main() { + init(); + setup(); + while (true) loop(); + } + +.. _language-recommended-reading: + +Recommended Reading +------------------- + +* :ref:`Your board's documentation <index-boards>` page, which + includes references to the relevant ST materials (reference manual, + datashseet, etc.) for your board. +* `ARM Cortex-M3 Technical Reference Manual, Revision r1p1 <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0337e/DDI0337E_cortex_m3_r1p1_trm.pdf>`_ + (PDF). This ARM manual specifies the Cortex-M3 architecture, + including instruction timings. +* :ref:`libmaple` +* `newlib's Documentation <http://sourceware.org/newlib/>`_ + (see :ref:`arm-gcc-libc`) diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst new file mode 100644 index 0000000..458241e --- /dev/null +++ b/docs/source/libmaple.rst @@ -0,0 +1,48 @@ +.. highlight:: sh + +.. _libmaple: + +``libmaple`` +============ + +LeafLabs' libmaple is the open source library we have developed for +programming the `STM32 <http://www.st.com/stonline>`_ line of +microcontrollers. Libmaple's `source is on GitHub +<https://github.com/leaflabs/libmaple>`_; :ref:`patches are welcome +<libmaple-contributing>`. + +.. _libmaple-vs-wirish: + +Libmaple is split into two pieces: + +- A low-level layer, written in C, called *libmaple proper*, located + in the `libmaple/ + <https://github.com/leaflabs/libmaple/tree/master/libmaple>`_ + subdirectory of the source repository. + +- A high-level layer, written in C++, called *wirish*, in the `wirish/ + <https://github.com/leaflabs/libmaple/tree/master/wirish>`_ + subdirectory. + +Wirish is :ref:`largely compatible <arduino-compatibility>` with the +AVR libraries written for the `Arduino <http://arduino.cc>`_ and +`Wiring <http://wiring.org.co/>`_ development boards. The Wirish +:ref:`language` page is a good summary of what Wirish provides; a +:ref:`complete Wirish API index <language-index>` is also +available. :ref:`Wirish libraries <libraries>` are documented +separately. + +libmaple is bundled with the :ref:`Maple IDE <ide>`. However, we +develop it separately, and :ref:`release it standalone +<unix-toolchain>` for users who might chafe at the "sketch" +programming model of the IDE. The following pages document libmaple +proper. As such, they're intended for advanced users who know how to +write C. + +.. toctree:: + :maxdepth: 1 + + libmaple/overview + libmaple/apis + libmaple/contributing + libmaple/coding-standard diff --git a/docs/source/libmaple/api/adc.rst b/docs/source/libmaple/api/adc.rst new file mode 100644 index 0000000..2f06926 --- /dev/null +++ b/docs/source/libmaple/api/adc.rst @@ -0,0 +1,231 @@ +.. highlight:: c +.. _libmaple-adc: + +``<libmaple/adc.h>`` +==================== + +:ref:`Analog to Digital Conversion <adc>` (ADC) support. + +A common API for basic ADC functionality is available, but the +characteristics of the ADC peripherals vary slightly across +targets. To manage this, each target defines a small set of datatypes +expressing its capabilities (namely :ref:`adc_extsel_event +<adc-adc_extsel_event>`, :ref:`adc_smp_rate <adc-adc_smp_rate>`, and +:ref:`adc_prescaler <adc-adc_prescaler>`). + +.. contents:: Contents + :local: + :depth: 2 + +Devices +------- + +The individual ADC peripherals have the following device struct. + +.. doxygenstruct:: adc_dev + +The available ADC peripherals vary by target. The complete list is +``ADC1``, ``ADC2``, and ``ADC3``. + +.. doxygenvariable:: ADC1 +.. doxygenvariable:: ADC2 +.. doxygenvariable:: ADC3 + +Functions +--------- + +Activation and Deactivation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``adc_enable_single_swstart()`` is simple, portable function, which +enables an ADC and sets it up for its basic usage: performing single +conversions using :ref:`adc_read() <adc-adc_read>`. + +.. _adc-adc_enable_single_swstart: +.. doxygenfunction:: adc_enable_single_swstart + +The precise software sequence used varies by target, so this is a good +function to use if your program needs to support multiple MCUs. By +default, Wirish calls ``adc_enable_single_swstart()`` on all available +ADCs at ``init()`` time, so Wirish users don't have to call this +function. + +There are several other lower-level routines used for activating and +deactivating ADCs: + +.. _adc-adc_init: +.. doxygenfunction:: adc_init +.. _adc-adc_enable: +.. doxygenfunction:: adc_enable +.. _adc-adc_disable: +.. doxygenfunction:: adc_disable +.. _adc-adc_disable_all: +.. doxygenfunction:: adc_disable_all + +ADC Conversion +~~~~~~~~~~~~~~ + +``adc_read()`` is a simple function which starts conversion on a +single ADC channel, blocks until it has completed, and returns the +converted result. Don't use the ADC device for any other purpose while +it's running. + +.. _adc-adc_read: +.. doxygenfunction:: adc_read + +To use ``adc_read()``, the device must be configured appropriately. +You can do this with :ref:`adc_enable_single_swstart() +<adc-adc_enable_single_swstart>`. + +Note that for an ADC device to perform conversion on a GPIO input +(which is the usual case; the notable exception being taking +temperature reading), the pin must be configured for analog +conversion. Do this with :ref:`adc_config_gpio() +<adc-adc_config_gpio>`. + +Other routines helpful for ADC conversion: + +.. _adc-adc_set_reg_seqlen: +.. doxygenfunction:: adc_set_reg_seqlen +.. _adc-adc_set_extsel: +.. doxygenfunction:: adc_set_extsel + +.. _adc-adc_extsel_event: + +The last of these, :ref:`adc_set_extsel() <adc-adc_set_extsel>`, takes +a target-dependent ``adc_extsel_event`` argument. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::adc_extsel_event + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::adc_extsel_event + +ADC Clock Prescaler +~~~~~~~~~~~~~~~~~~~ + +``adc_set_prescaler()`` is available for setting the prescaler which +determines the common ADC clock rate. (Wirish sets a sensible default +for this, so Wirish users ordinarily don't need to call this +function.) + +.. warning:: Increasing the ADC clock rate does speed conversion time, + but the ADC peripherals have a maximum clock rate which must not be + exceeded. Make sure to configure your system and ADC clocks to + respect your device's maximum rate. + +.. _adc_adc_set_prescaler: +.. doxygenfunction:: adc_set_prescaler + +.. _adc-adc_prescaler: + +ADC prescaler values are target-dependent. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::adc_prescaler + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::adc_prescaler + +.. _adc-adc_set_sample_rate: + +ADC Sample Time +~~~~~~~~~~~~~~~ + +You can control the sampling time (in ADC cycles) for an entire ADC +device using ``adc_set_sample_rate()`` [#fchansamp]_. This function +**only controls the sample rate**; the total conversion time is equal +to the sample time plus an additional number of ADC cycles. Consult +the reference manual for your chip for more details. + +.. warning:: Decreasing ADC sample time speeds conversion, but it also + decreases the maximum allowable impedance of the voltage source you + are measuring. If your voltage source has a high impedance + (e.g. you're measuring Vcc through a potentiometer), and your + sample time is too low, you will get inaccurate results. Consult + the datasheet for your target for more details. + +.. note:: Wirish sets a sensible default sample rate to allow for + high-impedance inputs at ``init()`` time, but Wirish users who know + what they're doing may want to call this function to speed up ADC + conversion. + +.. doxygenfunction:: adc_set_sample_rate + +.. _adc-adc_smp_rate: + +The ``adc_smp_rate`` argument to :ref:`adc_set_sample_rate() +<adc-adc_set_sample_rate>` is target-dependent. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::adc_smp_rate + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::adc_smp_rate + +Miscellaneous +~~~~~~~~~~~~~ + +.. FIXME [0.0.13] why don't adc_config_gpio()'s docs show up? + +.. _adc-adc_foreach: +.. doxygenfunction:: adc_foreach + +.. _adc-adc_config_gpio: +.. doxygenfunction:: adc_config_gpio + +STM32F1 only +~~~~~~~~~~~~ + +The following routines are available only on STM32F1 targets. + +.. _adc-adc_set_exttrig: +.. doxygenfunction:: adc_set_exttrig + +``adc_calibrate()`` performs calibration necessary on STM32F1 before +using an ADC. Note that on STM32F1 targets, +:ref:`adc_enable_single_swstart() <adc-adc_enable_single_swstart>` +calls ``adc_calibrate()``, so there's no need to do it separately. + +.. _adc-adc_calibrate: +.. doxygenfunction:: adc_calibrate + +Register Maps +------------- + +Individual ADC peripherals have the following register map. The base +pointers are ``ADC1_BASE``, ``ADC2_BASE``, and ``ADC3_BASE``. + +.. _adc-adc_reg_map: +.. doxygenstruct:: adc_reg_map + +On **STM32F2 targets**, there is an additional common set of registers +shared by all ADC peripherals. Its base pointer is +``ADC_COMMON_BASE``. + +.. _adc-adc_common_reg_map: +.. doxygenstruct:: stm32f2::adc_common_reg_map + +Register Bit Definitions +------------------------ + +.. TODO [0.0.13] + +TODO + +.. rubric:: Footnotes + +.. [#fchansamp] Per-channel sample time configuration is possible, + but currently unsupported. diff --git a/docs/source/libmaple/api/bitband.rst b/docs/source/libmaple/api/bitband.rst new file mode 100644 index 0000000..768f678 --- /dev/null +++ b/docs/source/libmaple/api/bitband.rst @@ -0,0 +1,15 @@ +.. highlight:: c +.. _libmaple-bitband: + +``<libmaple/bitband.h>`` +======================== + +Bit-banding support. + +Functions +--------- + +.. doxygenfunction:: bb_sram_get_bit +.. doxygenfunction:: bb_sram_set_bit +.. doxygenfunction:: bb_peri_get_bit +.. doxygenfunction:: bb_peri_set_bit diff --git a/docs/source/libmaple/api/bkp.rst b/docs/source/libmaple/api/bkp.rst new file mode 100644 index 0000000..4f0115b --- /dev/null +++ b/docs/source/libmaple/api/bkp.rst @@ -0,0 +1,79 @@ +.. highlight:: c +.. _libmaple-bkp: + +``bkp.h`` +========= + +Backup register (BKP) suport. + +.. contents:: Contents + :local: + +Types +----- + +.. doxygenstruct:: bkp_dev +.. doxygenstruct:: bkp_reg_map + +Devices +------- + +.. doxygenvariable:: BKP + +Convenience Functions +--------------------- + +.. 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/docs/source/libmaple/api/dac.rst b/docs/source/libmaple/api/dac.rst new file mode 100644 index 0000000..55c8faf --- /dev/null +++ b/docs/source/libmaple/api/dac.rst @@ -0,0 +1,123 @@ +.. highlight:: c +.. _libmaple-dac: + +``dac.h`` +========= + +Digital to Analog Conversion (DAC) support. + +.. contents:: Contents + :local: + +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/docs/source/libmaple/api/delay.rst b/docs/source/libmaple/api/delay.rst new file mode 100644 index 0000000..d11496b --- /dev/null +++ b/docs/source/libmaple/api/delay.rst @@ -0,0 +1,11 @@ +.. highlight:: c +.. _libmaple-delay: + +``<libmaple/delay.h>`` +====================== + +Provides a simple busy-loop delay function. Note that this function +does not account for time spent in interrupts, so actual delay times +may vary depending on your application. + +.. doxygenfunction:: delay_us diff --git a/docs/source/libmaple/api/dma.rst b/docs/source/libmaple/api/dma.rst new file mode 100644 index 0000000..a9893e2 --- /dev/null +++ b/docs/source/libmaple/api/dma.rst @@ -0,0 +1,215 @@ +.. highlight:: c +.. _libmaple-dma: + +``dma.h`` +========= + +Direct Memory Access (DMA) support. + +.. contents:: Contents + :local: + +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 +--------- + +.. 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/docs/source/libmaple/api/exti.rst b/docs/source/libmaple/api/exti.rst new file mode 100644 index 0000000..1038fbf --- /dev/null +++ b/docs/source/libmaple/api/exti.rst @@ -0,0 +1,37 @@ +.. highlight:: c +.. _libmaple-exti: + +``exti.h`` +========== + +:ref:`External interrupt <external-interrupts>` support. + +.. contents:: Contents + :local: + +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/docs/source/libmaple/api/flash.rst b/docs/source/libmaple/api/flash.rst new file mode 100644 index 0000000..52ff4d2 --- /dev/null +++ b/docs/source/libmaple/api/flash.rst @@ -0,0 +1,249 @@ +.. highlight:: c +.. _libmaple-flash: + +``<libmaple/flash.h>`` +====================== + +Flash memory support. + +The built-in Flash on different STM32 MCUs varies in terms of its +eraseable page/sector size and read/write protections. There isn't +currently much support for dealing with this. This header is mostly +useful for its functions that control Flash features which affect +system performance, like wait states and prefetch buffers. + +.. contents:: Contents + :local: + +Devices +------- + +None at this time. + +Functions +--------- + +The following functions can be used to portably manipulate Flash memory. + +.. doxygenfunction:: flash_set_latency +.. doxygenfunction:: flash_enable_features +.. doxygenfunction:: flash_enable_prefetch + +Register Maps +------------- + +Register maps vary by target. The base pointer is always ``FLASH_BASE``. + +Base Pointer +~~~~~~~~~~~~ + +.. doxygendefine:: FLASH_BASE + +STM32F1 targets +~~~~~~~~~~~~~~~ + +.. doxygenstruct:: stm32f1::flash_reg_map + +STM32F2 targets +~~~~~~~~~~~~~~~ + +.. doxygenstruct:: stm32f2::flash_reg_map + +Register Bit Definitions +------------------------ + +These are given as source code. Available register bit definitions +vary by target. + +STM32F1 Targets +~~~~~~~~~~~~~~~ + +:: + + /* Access control register */ + + #define FLASH_ACR_PRFTBS_BIT 5 + #define FLASH_ACR_PRFTBE_BIT 4 + #define FLASH_ACR_HLFCYA_BIT 3 + + #define FLASH_ACR_PRFTBS (1U << FLASH_ACR_PRFTBS_BIT) + #define FLASH_ACR_PRFTBE (1U << FLASH_ACR_PRFTBE_BIT) + #define FLASH_ACR_HLFCYA (1U << FLASH_ACR_HLFCYA_BIT) + #define FLASH_ACR_LATENCY 0x7 + + /* Status register */ + + #define FLASH_SR_EOP_BIT 5 + #define FLASH_SR_WRPRTERR_BIT 4 + #define FLASH_SR_PGERR_BIT 2 + #define FLASH_SR_BSY_BIT 0 + + #define FLASH_SR_EOP (1U << FLASH_SR_EOP_BIT) + #define FLASH_SR_WRPRTERR (1U << FLASH_SR_WRPRTERR_BIT) + #define FLASH_SR_PGERR (1U << FLASH_SR_PGERR_BIT) + #define FLASH_SR_BSY (1U << FLASH_SR_BSY_BIT) + + /* Control register */ + + #define FLASH_CR_EOPIE_BIT 12 + #define FLASH_CR_ERRIE_BIT 10 + #define FLASH_CR_OPTWRE_BIT 9 + #define FLASH_CR_LOCK_BIT 7 + #define FLASH_CR_STRT_BIT 6 + #define FLASH_CR_OPTER_BIT 5 + #define FLASH_CR_OPTPG_BIT 4 + #define FLASH_CR_MER_BIT 2 + #define FLASH_CR_PER_BIT 1 + #define FLASH_CR_PG_BIT 0 + + #define FLASH_CR_EOPIE (1U << FLASH_CR_EOPIE_BIT) + #define FLASH_CR_ERRIE (1U << FLASH_CR_ERRIE_BIT) + #define FLASH_CR_OPTWRE (1U << FLASH_CR_OPTWRE_BIT) + #define FLASH_CR_LOCK (1U << FLASH_CR_LOCK_BIT) + #define FLASH_CR_STRT (1U << FLASH_CR_STRT_BIT) + #define FLASH_CR_OPTER (1U << FLASH_CR_OPTER_BIT) + #define FLASH_CR_OPTPG (1U << FLASH_CR_OPTPG_BIT) + #define FLASH_CR_MER (1U << FLASH_CR_MER_BIT) + #define FLASH_CR_PER (1U << FLASH_CR_PER_BIT) + #define FLASH_CR_PG (1U << FLASH_CR_PG_BIT) + + /* Option byte register */ + + #define FLASH_OBR_nRST_STDBY_BIT 4 + #define FLASH_OBR_nRST_STOP_BIT 3 + #define FLASH_OBR_WDG_SW_BIT 2 + #define FLASH_OBR_RDPRT_BIT 1 + #define FLASH_OBR_OPTERR_BIT 0 + + #define FLASH_OBR_DATA1 (0xFF << 18) + #define FLASH_OBR_DATA0 (0xFF << 10) + #define FLASH_OBR_USER 0x3FF + #define FLASH_OBR_nRST_STDBY (1U << FLASH_OBR_nRST_STDBY_BIT) + #define FLASH_OBR_nRST_STOP (1U << FLASH_OBR_nRST_STOP_BIT) + #define FLASH_OBR_WDG_SW (1U << FLASH_OBR_WDG_SW_BIT) + #define FLASH_OBR_RDPRT (1U << FLASH_OBR_RDPRT_BIT) + #define FLASH_OBR_OPTERR (1U << FLASH_OBR_OPTERR_BIT) + +STM32F2 Targets +~~~~~~~~~~~~~~~ + +:: + + /* Access control register */ + + #define FLASH_ACR_DCRST_BIT 12 + #define FLASH_ACR_ICRST_BIT 11 + #define FLASH_ACR_DCEN_BIT 10 + #define FLASH_ACR_ICEN_BIT 9 + #define FLASH_ACR_PRFTEN_BIT 8 + + #define FLASH_ACR_DCRST (1U << FLASH_ACR_DCRST_BIT) + #define FLASH_ACR_ICRST (1U << FLASH_ACR_ICRST_BIT) + #define FLASH_ACR_DCEN (1U << FLASH_ACR_DCEN_BIT) + #define FLASH_ACR_ICEN (1U << FLASH_ACR_ICEN_BIT) + #define FLASH_ACR_PRFTEN (1U << FLASH_ACR_PRFTEN_BIT) + #define FLASH_ACR_LATENCY 0x7 + #define FLASH_ACR_LATENCY_0WS 0x0 + #define FLASH_ACR_LATENCY_1WS 0x1 + #define FLASH_ACR_LATENCY_2WS 0x2 + #define FLASH_ACR_LATENCY_3WS 0x3 + #define FLASH_ACR_LATENCY_4WS 0x4 + #define FLASH_ACR_LATENCY_5WS 0x5 + #define FLASH_ACR_LATENCY_6WS 0x6 + #define FLASH_ACR_LATENCY_7WS 0x7 + + /* Key register */ + + #define FLASH_KEYR_KEY1 0x45670123 + #define FLASH_KEYR_KEY2 0xCDEF89AB + + /* Option key register */ + + #define FLASH_OPTKEYR_OPTKEY1 0x08192A3B + #define FLASH_OPTKEYR_OPTKEY2 0x4C5D6E7F + + /* Status register */ + + #define FLASH_SR_BSY_BIT 16 + #define FLASH_SR_PGSERR_BIT 7 + #define FLASH_SR_PGPERR_BIT 6 + #define FLASH_SR_PGAERR_BIT 5 + #define FLASH_SR_WRPERR_BIT 4 + #define FLASH_SR_OPERR_BIT 1 + #define FLASH_SR_EOP_BIT 0 + + #define FLASH_SR_BSY (1U << FLASH_SR_BSY_BIT) + #define FLASH_SR_PGSERR (1U << FLASH_SR_PGSERR_BIT) + #define FLASH_SR_PGPERR (1U << FLASH_SR_PGPERR_BIT) + #define FLASH_SR_PGAERR (1U << FLASH_SR_PGAERR_BIT) + #define FLASH_SR_WRPERR (1U << FLASH_SR_WRPERR_BIT) + #define FLASH_SR_OPERR (1U << FLASH_SR_OPERR_BIT) + #define FLASH_SR_EOP (1U << FLASH_SR_EOP_BIT) + + /* Control register */ + + #define FLASH_CR_LOCK_BIT 31 + #define FLASH_CR_ERRIE_BIT 25 + #define FLASH_CR_EOPIE_BIT 24 + #define FLASH_CR_STRT_BIT 16 + #define FLASH_CR_MER_BIT 2 + #define FLASH_CR_SER_BIT 1 + #define FLASH_CR_PG_BIT 0 + + #define FLASH_CR_LOCK (1U << FLASH_CR_LOCK_BIT) + #define FLASH_CR_ERRIE (1U << FLASH_CR_ERRIE_BIT) + #define FLASH_CR_EOPIE (1U << FLASH_CR_EOPIE_BIT) + #define FLASH_CR_STRT (1U << FLASH_CR_STRT_BIT) + + #define FLASH_CR_PSIZE (0x3 << 8) + #define FLASH_CR_PSIZE_MUL8 (0x0 << 8) + #define FLASH_CR_PSIZE_MUL16 (0x1 << 8) + #define FLASH_CR_PSIZE_MUL32 (0x2 << 8) + #define FLASH_CR_PSIZE_MUL64 (0x3 << 8) + + #define FLASH_CR_SNB (0xF << 3) + #define FLASH_CR_SNB_0 (0x0 << 3) + #define FLASH_CR_SNB_1 (0x1 << 3) + #define FLASH_CR_SNB_2 (0x2 << 3) + #define FLASH_CR_SNB_3 (0x3 << 3) + #define FLASH_CR_SNB_4 (0x4 << 3) + #define FLASH_CR_SNB_5 (0x5 << 3) + #define FLASH_CR_SNB_6 (0x6 << 3) + #define FLASH_CR_SNB_7 (0x7 << 3) + #define FLASH_CR_SNB_8 (0x8 << 3) + #define FLASH_CR_SNB_9 (0x9 << 3) + #define FLASH_CR_SNB_10 (0xA << 3) + #define FLASH_CR_SNB_11 (0xB << 3) + + #define FLASH_CR_MER (1U << FLASH_CR_MER_BIT) + #define FLASH_CR_SER (1U << FLASH_CR_SER_BIT) + #define FLASH_CR_PG (1U << FLASH_CR_PG_BIT) + + /* Option control register */ + + #define FLASH_OPTCR_NRST_STDBY_BIT 7 + #define FLASH_OPTCR_NRST_STOP_BIT 6 + #define FLASH_OPTCR_WDG_SW_BIT 5 + #define FLASH_OPTCR_OPTSTRT_BIT 1 + #define FLASH_OPTCR_OPTLOCK_BIT 0 + + #define FLASH_OPTCR_NWRP (0x3FF << 16) + + /* Excluded: The many level 1 values */ + #define FLASH_OPTCR_RDP (0xFF << 8) + #define FLASH_OPTCR_RDP_LEVEL0 (0xAA << 8) + #define FLASH_OPTCR_RDP_LEVEL2 (0xCC << 8) + + #define FLASH_OPTCR_USER (0x7 << 5) + #define FLASH_OPTCR_nRST_STDBY (1U << FLASH_OPTCR_nRST_STDBY_BIT) + #define FLASH_OPTCR_nRST_STOP (1U << FLASH_OPTCR_nRST_STOP_BIT) + #define FLASH_OPTCR_WDG_SW (1U << FLASH_OPTCR_WDG_SW_BIT) + + #define FLASH_OPTCR_BOR_LEV (0x3 << 2) + #define FLASH_OPTCR_BOR_LEVEL3 (0x0 << 2) + #define FLASH_OPTCR_BOR_LEVEL2 (0x1 << 2) + #define FLASH_OPTCR_BOR_LEVEL1 (0x2 << 2) + #define FLASH_OPTCR_BOR_OFF (0x3 << 2) + + #define FLASH_OPTCR_OPTSTRT (1U << FLASH_OPTCR_OPTSTRT_BIT) + #define FLASH_OPTCR_OPTLOCK (1U << FLASH_OPTCR_OPTLOCK_BIT) diff --git a/docs/source/libmaple/api/fsmc.rst b/docs/source/libmaple/api/fsmc.rst new file mode 100644 index 0000000..e2bf87a --- /dev/null +++ b/docs/source/libmaple/api/fsmc.rst @@ -0,0 +1,235 @@ +.. highlight:: c +.. _libmaple-fsmc: + +``<libmaple/fsmc.h>`` +===================== + +Flexible Static Memory Controller (FSMC) support. The FSMC peripheral +is only available on some targets. Including this header on a target +without an FSMC will cause a compilation error. Check your target's +documentation to determine if it's available. You can also use +:ref:`STM32_HAVE_FSMC <libmaple-stm32-STM32_HAVE_FSMC>` from +``<libmaple/stm32.h>`` to determine whether your target has an FSMC at +build time. + +All functionality documented here is portable. + +.. contents:: Contents + :local: + +Usage Note +---------- + +FSMC support is fairly limited at this time. Current Leaflabs boards +only use the FSMC to interface with external SRAM chips, so that's +what there's the most support for (:ref:`patches welcome! +<libmaple-contributing>`). Even for use with SRAM, you will still need +to program some registers directly. + +To use the FSMC with an SRAM chip, first call +:ref:`fsmc_sram_init_gpios() <libmaple-fsmc-fsmc_sram_init_gpios>` to +configure its data, address, and control lines. Then, turn on the +FSMC clock (by calling :ref:`rcc_clk_enable(RCC_FSMC) +<libmaple-rcc-rcc_clk_enable>`). You can then configure the relevant +:ref:`fsmc_nor_psram_reg_map <libmaple-fsmc-fsmc_nor_psram_reg_map>` +``BCR`` register yourself for the SRAM chip you are using. + +You can additionally use :ref:`fsmc_nor_psram_set_datast() +<libmaple-fsmc-fsmc_nor_psram_set_datast>` and +:ref:`fsmc_nor_psram_set_datast() <libmaple-fsmc-fsmc_nor_psram_set_datast>` +to control read/write timing. + +Devices +------- + +None at this time. + +Functions +--------- + +.. _libmaple-fsmc-fsmc_sram_init_gpios: +.. doxygenfunction:: fsmc_sram_init_gpios +.. _libmaple-fsmc-fsmc_nor_psram_set_datast: +.. doxygenfunction:: fsmc_nor_psram_set_datast +.. _libmaple-fsmc-fsmc_nor_psram_set_addset: +.. doxygenfunction:: fsmc_nor_psram_set_addset + +Register Maps +------------- + +The general purpose register map type is ``fsmc_reg_map``; its base +pointer is ``FSMC_BASE``. The ``fsmc_nor_psram_reg_map`` type is for +use configuring the registers for an individual NOR/PSRAM region +(``FSMC_BCRx``, ``FSMC_BTRx``, and ``FSMC_BWTRx``); the relevant base +pointers are ``FSMC_NOR_PSRAM_REGION1`` through +``FSMC_NOR_PSRAM_REGION4``. + +.. doxygendefine:: FSMC_BASE + +.. doxygendefine:: FSMC_NOR_PSRAM1_BASE +.. doxygendefine:: FSMC_NOR_PSRAM2_BASE +.. doxygendefine:: FSMC_NOR_PSRAM3_BASE +.. doxygendefine:: FSMC_NOR_PSRAM4_BASE + +.. doxygenstruct:: fsmc_reg_map +.. _libmaple-fsmc-fsmc_nor_psram_reg_map: +.. doxygenstruct:: fsmc_nor_psram_reg_map + +Memory Bank Boundary Addresses +------------------------------ + +Reading and writing data on an external memory chip using FSMC is done +by reading and writing from addresses in special memory-mapped +sections of the address space called *memory banks*. + +This is convenient, since it implies that the usual load and store +instructions used for I/O with the internal SRAM are also used to +perform bus transactions with the external memory chip. (Which means +you can use ``memcpy()`` etc. on external memory.) + +Pointers to the memory banks' base addresses are given by the +following macros. + +.. 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 Bit Definitions +------------------------ + +These are given as source code. + +:: + + /* NOR/PSRAM chip-select control registers */ + + #define FSMC_BCR_CBURSTRW_BIT 19 + #define FSMC_BCR_ASYNCWAIT_BIT 15 + #define FSMC_BCR_EXTMOD_BIT 14 + #define FSMC_BCR_WAITEN_BIT 13 + #define FSMC_BCR_WREN_BIT 12 + #define FSMC_BCR_WAITCFG_BIT 11 + #define FSMC_BCR_WRAPMOD_BIT 10 + #define FSMC_BCR_WAITPOL_BIT 9 + #define FSMC_BCR_BURSTEN_BIT 8 + #define FSMC_BCR_FACCEN_BIT 6 + #define FSMC_BCR_MUXEN_BIT 1 + #define FSMC_BCR_MBKEN_BIT 0 + + #define FSMC_BCR_CBURSTRW (1U << FSMC_BCR_CBURSTRW_BIT) + #define FSMC_BCR_ASYNCWAIT (1U << FSMC_BCR_ASYNCWAIT_BIT) + #define FSMC_BCR_EXTMOD (1U << FSMC_BCR_EXTMOD_BIT) + #define FSMC_BCR_WAITEN (1U << FSMC_BCR_WAITEN_BIT) + #define FSMC_BCR_WREN (1U << FSMC_BCR_WREN_BIT) + #define FSMC_BCR_WAITCFG (1U << FSMC_BCR_WAITCFG_BIT) + #define FSMC_BCR_WRAPMOD (1U << FSMC_BCR_WRAPMOD_BIT) + #define FSMC_BCR_WAITPOL (1U << FSMC_BCR_WAITPOL_BIT) + #define FSMC_BCR_BURSTEN (1U << FSMC_BCR_BURSTEN_BIT) + #define FSMC_BCR_FACCEN (1U << FSMC_BCR_FACCEN_BIT) + #define FSMC_BCR_MWID (0x3 << 4) + #define FSMC_BCR_MWID_8BITS (0x0 << 4) + #define FSMC_BCR_MWID_16BITS (0x1 << 4) + #define FSMC_BCR_MTYP (0x3 << 2) + #define FSMC_BCR_MTYP_SRAM (0x0 << 2) + #define FSMC_BCR_MTYP_PSRAM (0x1 << 2) + #define FSMC_BCR_MTYP_NOR_FLASH (0x2 << 2) + #define FSMC_BCR_MUXEN (1U << FSMC_BCR_MUXEN_BIT) + #define FSMC_BCR_MBKEN (1U << FSMC_BCR_MBKEN_BIT) + + /* SRAM/NOR-Flash chip-select timing registers */ + + #define FSMC_BTR_ACCMOD (0x3 << 28) + #define FSMC_BTR_ACCMOD_A (0x0 << 28) + #define FSMC_BTR_ACCMOD_B (0x1 << 28) + #define FSMC_BTR_ACCMOD_C (0x2 << 28) + #define FSMC_BTR_ACCMOD_D (0x3 << 28) + #define FSMC_BTR_DATLAT (0xF << 24) + #define FSMC_BTR_CLKDIV (0xF << 20) + #define FSMC_BTR_BUSTURN (0xF << 16) + #define FSMC_BTR_DATAST (0xFF << 8) + #define FSMC_BTR_ADDHLD (0xF << 4) + #define FSMC_BTR_ADDSET 0xF + + /* SRAM/NOR-Flash write timing registers */ + + #define FSMC_BWTR_ACCMOD (0x3 << 28) + #define FSMC_BWTR_ACCMOD_A (0x0 << 28) + #define FSMC_BWTR_ACCMOD_B (0x1 << 28) + #define FSMC_BWTR_ACCMOD_C (0x2 << 28) + #define FSMC_BWTR_ACCMOD_D (0x3 << 28) + #define FSMC_BWTR_DATLAT (0xF << 24) + #define FSMC_BWTR_CLKDIV (0xF << 20) + #define FSMC_BWTR_DATAST (0xFF << 8) + #define FSMC_BWTR_ADDHLD (0xF << 4) + #define FSMC_BWTR_ADDSET 0xF + + /* NAND Flash/PC Card controller registers */ + + #define FSMC_PCR_ECCEN_BIT 6 + #define FSMC_PCR_PTYP_BIT 3 + #define FSMC_PCR_PBKEN_BIT 2 + #define FSMC_PCR_PWAITEN_BIT 1 + + #define FSMC_PCR_ECCPS (0x7 << 17) + #define FSMC_PCR_ECCPS_256B (0x0 << 17) + #define FSMC_PCR_ECCPS_512B (0x1 << 17) + #define FSMC_PCR_ECCPS_1024B (0x2 << 17) + #define FSMC_PCR_ECCPS_2048B (0x3 << 17) + #define FSMC_PCR_ECCPS_4096B (0x4 << 17) + #define FSMC_PCR_ECCPS_8192B (0x5 << 17) + #define FSMC_PCR_TAR (0xF << 13) + #define FSMC_PCR_TCLR (0xF << 9) + #define FSMC_PCR_ECCEN (1U << FSMC_PCR_ECCEN_BIT) + #define FSMC_PCR_PWID (0x3 << 4) + #define FSMC_PCR_PWID_8BITS (0x0 << 4) + #define FSMC_PCR_PWID_16BITS (0x1 << 4) + #define FSMC_PCR_PTYP (1U << FSMC_PCR_PTYP_BIT) + #define FSMC_PCR_PTYP_PC_CF_PCMCIA (0x0 << FSMC_PCR_PTYP_BIT) + #define FSMC_PCR_PTYP_NAND (0x1 << FSMC_PCR_PTYP_BIT) + #define FSMC_PCR_PBKEN (1U << FSMC_PCR_PBKEN_BIT) + #define FSMC_PCR_PWAITEN (1U << FSMC_PCR_PWAITEN_BIT) + + /* FIFO status and interrupt registers */ + + #define FSMC_SR_FEMPT_BIT 6 + #define FSMC_SR_IFEN_BIT 5 + #define FSMC_SR_ILEN_BIT 4 + #define FSMC_SR_IREN_BIT 3 + #define FSMC_SR_IFS_BIT 2 + #define FSMC_SR_ILS_BIT 1 + #define FSMC_SR_IRS_BIT 0 + + #define FSMC_SR_FEMPT (1U << FSMC_SR_FEMPT_BIT) + #define FSMC_SR_IFEN (1U << FSMC_SR_IFEN_BIT) + #define FSMC_SR_ILEN (1U << FSMC_SR_ILEN_BIT) + #define FSMC_SR_IREN (1U << FSMC_SR_IREN_BIT) + #define FSMC_SR_IFS (1U << FSMC_SR_IFS_BIT) + #define FSMC_SR_ILS (1U << FSMC_SR_ILS_BIT) + #define FSMC_SR_IRS (1U << FSMC_SR_IRS_BIT) + + /* Common memory space timing registers */ + + #define FSMC_PMEM_MEMHIZ (0xFF << 24) + #define FSMC_PMEM_MEMHOLD (0xFF << 16) + #define FSMC_PMEM_MEMWAIT (0xFF << 8) + #define FSMC_PMEM_MEMSET 0xFF + + /* Attribute memory space timing registers */ + + #define FSMC_PATT_ATTHIZ (0xFF << 24) + #define FSMC_PATT_ATTHOLD (0xFF << 16) + #define FSMC_PATT_ATTWAIT (0xFF << 8) + #define FSMC_PATT_ATTSET 0xFF + + /* I/O space timing register 4 */ + + #define FSMC_PIO_IOHIZ (0xFF << 24) + #define FSMC_PIO_IOHOLD (0xFF << 16) + #define FSMC_PIO_IOWAIT (0xFF << 8) + #define FSMC_PIO_IOSET 0xF diff --git a/docs/source/libmaple/api/gpio.rst b/docs/source/libmaple/api/gpio.rst new file mode 100644 index 0000000..faf0ad2 --- /dev/null +++ b/docs/source/libmaple/api/gpio.rst @@ -0,0 +1,243 @@ +.. highlight:: c +.. _libmaple-gpio: + +``gpio.h`` +========== + +General Purpose Input/Output (GPIO) port and Alternate Function +Input/Output (AFIO) support. + +.. contents:: Contents + :local: + +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 + +.. _gpio-h-afio-remap: +.. 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/docs/source/libmaple/api/i2c.rst b/docs/source/libmaple/api/i2c.rst new file mode 100644 index 0000000..ff380cc --- /dev/null +++ b/docs/source/libmaple/api/i2c.rst @@ -0,0 +1,124 @@ +.. highlight:: c +.. _libmaple-i2c: + +``i2c.h`` +========= + +Inter-Integrated Circuit (|i2c|) peripheral support. + +.. contents:: Contents + :local: + +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/docs/source/libmaple/api/iwdg.rst b/docs/source/libmaple/api/iwdg.rst new file mode 100644 index 0000000..65f9f7b --- /dev/null +++ b/docs/source/libmaple/api/iwdg.rst @@ -0,0 +1,80 @@ +.. highlight:: c +.. _libmaple-iwdg: + +``<libmaple/iwdg.h>`` +===================== + +Independent Watchdog (IWDG) support. The IWDG peripheral is common +across supported targets, so everything documented here is portable. + +.. contents:: Contents + :local: + +Usage Note +---------- + +To use the independent watchdog, first call :ref:`iwdg_init() +<libmaple-iwdg-iwdg_init>` with the appropriate prescaler and IWDG +counter reload values for your application. Afterwards, you must +periodically call :ref:`iwdg_feed() <libmaple-iwdg-iwdg_feed>` before +the IWDG counter reaches zero 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. + +Devices +------- + +None at this time. + +Functions +--------- + +.. _libmaple-iwdg-iwdg_init: +.. doxygenfunction:: iwdg_init +.. _libmaple-iwdg-iwdg_feed: +.. doxygenfunction:: iwdg_feed + +Types +----- + +.. doxygenenum:: iwdg_prescaler + + +Register Maps +------------- + +.. doxygendefine:: IWDG_BASE + +.. doxygenstruct:: iwdg_reg_map + +Register Bit Definitions +------------------------ + +These are given as source code. + +:: + + /* Key register */ + + #define IWDG_KR_UNLOCK 0x5555 + #define IWDG_KR_FEED 0xAAAA + #define IWDG_KR_START 0xCCCC + + /* Prescaler register */ + + #define IWDG_PR_DIV_4 0x0 + #define IWDG_PR_DIV_8 0x1 + #define IWDG_PR_DIV_16 0x2 + #define IWDG_PR_DIV_32 0x3 + #define IWDG_PR_DIV_64 0x4 + #define IWDG_PR_DIV_128 0x5 + #define IWDG_PR_DIV_256 0x6 + + /* Status register */ + + #define IWDG_SR_RVU_BIT 1 + #define IWDG_SR_PVU_BIT 0 + + #define IWDG_SR_RVU (1U << IWDG_SR_RVU_BIT) + #define IWDG_SR_PVU (1U << IWDG_SR_PVU_BIT) diff --git a/docs/source/libmaple/api/libmaple.rst b/docs/source/libmaple/api/libmaple.rst new file mode 100644 index 0000000..7deb659 --- /dev/null +++ b/docs/source/libmaple/api/libmaple.rst @@ -0,0 +1,11 @@ +.. highlight:: c +.. _libmaple-libmaple: + +``<libmaple/libmaple.h>`` +========================= + +Base include file for libmaple. + +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/docs/source/libmaple/api/libmaple_types.rst b/docs/source/libmaple/api/libmaple_types.rst new file mode 100644 index 0000000..5ca446e --- /dev/null +++ b/docs/source/libmaple/api/libmaple_types.rst @@ -0,0 +1,85 @@ +.. highlight:: c +.. _libmaple-libmaple_types: + +``<libmaple/libmaple_types.h>`` +=============================== + +Defines the base types and type-related macros used throughout the +rest of libmaple. + +.. contents:: Contents + :local: + +Integral Types +-------------- + +.. doxygentypedef:: uint8 +.. doxygentypedef:: uint16 +.. doxygentypedef:: uint32 +.. doxygentypedef:: uint64 +.. doxygentypedef:: int8 +.. doxygentypedef:: int16 +.. doxygentypedef:: int32 +.. doxygentypedef:: int64 + +Attributes and Type Qualifiers +------------------------------ + +In the case of macros for GCC's ``__attribute__``\ s, we have our own +macros mostly to save typing, but also in hopes that they might be +expressible using different compiler extensions, or to give them +different interpretations when running e.g. Doxygen on libmaple. + +.. c:macro:: __always_inline + + Macro for ``inline __attribute__((always_inline))``. This can be + used to defeat GCC's ``-Os`` when you Really Mean Inline. + +.. c:macro:: __attr_flash + + Macro for a GCC ``__attribute__`` which (when using libmaple's + linker scripts) will cause the variable being marked to be stored + in Flash, rather than SRAM. It's useful for read-only variables + like look-up tables. + +.. c:macro:: __deprecated + + Macro for ``__attribute__((deprecated))``. Its use causes GCC to + emit deprecation warnings when the deprecated functionality is + used. It's not used for everything that gets deprecated, so don't + rely on it to catch all uses of deprecated APIs. + +.. c:macro:: __packed + + Macro for ``__attribute__((packed))``. + +.. c:macro:: __io + + Macro for ``volatile`` which denotes 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 + <libmaple-overview-regmaps>` struct. + +.. c:macro:: __weak + + Macro for ``__attribute__((weak))``. + +.. c:macro:: __unused + + Macro for ``__attribute__((unused))``. This can be used + (sparingly!) to silence unused function warnings when GCC is + mistaken. + +Miscellaneous +------------- + +.. doxygentypedef:: voidFuncPtr + +.. c:macro:: offsetof(type, member) + + If left undefined, this is defined to ``__builtin_ofsetof(type, + member)``. + +.. c:macro:: NULL + + If left undefined, this is defined to ``0``. diff --git a/docs/source/libmaple/api/nvic.rst b/docs/source/libmaple/api/nvic.rst new file mode 100644 index 0000000..505e36e --- /dev/null +++ b/docs/source/libmaple/api/nvic.rst @@ -0,0 +1,67 @@ +.. highlight:: c +.. _libmaple-nvic: + +``<libmaple/nvic.h>`` +===================== + +Nested Vector Interrupt Controller (NVIC) support. + +The same API is used on all targets, but the available interrupts are +target-dependent. To manage this, each target series defines an +:ref:`nvic_irq_num <libmaple-nvic-nvic_irq_num>` enumerator for each +available interrupt. + +.. contents:: Contents + :local: + +Devices +------- + +None at this time. + +.. _libmaple-nvic-nvic_irq_num: + +``nvic_irq_num`` +---------------- + +This target-dependent enum is used to identify an interrupt vector +number. Interrupts which are common across series have the same token +(though not necessarily the same value) for their ``nvic_irq_num``\ s. +The available values on each supported target series are as follows. + +STM32F1 Targets +~~~~~~~~~~~~~~~ + +.. doxygenenum:: stm32f1::nvic_irq_num + +STM32F2 Targets +~~~~~~~~~~~~~~~ + +.. doxygenenum:: stm32f2::nvic_irq_num + +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 +.. doxygenfunction:: nvic_sys_reset + +Register Maps +------------- + +Since the NVIC is part of the ARM core, its registers and base pointer +are common across all targes. + +.. doxygendefine:: NVIC_BASE +.. doxygenstruct:: nvic_reg_map + +Register Bit Definitions +------------------------ + +None at this time. diff --git a/docs/source/libmaple/api/pwr.rst b/docs/source/libmaple/api/pwr.rst new file mode 100644 index 0000000..6a2cf22 --- /dev/null +++ b/docs/source/libmaple/api/pwr.rst @@ -0,0 +1,51 @@ +.. highlight:: c +.. _libmaple-pwr: + +``pwr.h`` +========= + +Power control (PWR) support. + +.. contents:: Contents + :local: + +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/docs/source/libmaple/api/rcc-reg-bits.txt b/docs/source/libmaple/api/rcc-reg-bits.txt new file mode 100644 index 0000000..6b1133d --- /dev/null +++ b/docs/source/libmaple/api/rcc-reg-bits.txt @@ -0,0 +1,1017 @@ +STM32F1 Targets +~~~~~~~~~~~~~~~ + +Clock control register +++++++++++++++++++++++ + +:: + + #define RCC_CR_PLLRDY_BIT 25 + #define RCC_CR_PLLON_BIT 24 + #define RCC_CR_CSSON_BIT 19 + #define RCC_CR_HSEBYP_BIT 18 + #define RCC_CR_HSERDY_BIT 17 + #define RCC_CR_HSEON_BIT 16 + #define RCC_CR_HSIRDY_BIT 1 + #define RCC_CR_HSION_BIT 0 + + #define RCC_CR_PLLRDY (1U << RCC_CR_PLLRDY_BIT) + #define RCC_CR_PLLON (1U << RCC_CR_PLLON_BIT) + #define RCC_CR_CSSON (1U << RCC_CR_CSSON_BIT) + #define RCC_CR_HSEBYP (1U << RCC_CR_HSEBYP_BIT) + #define RCC_CR_HSERDY (1U << RCC_CR_HSERDY_BIT) + #define RCC_CR_HSEON (1U << RCC_CR_HSEON_BIT) + #define RCC_CR_HSICAL (0xFF << 8) + #define RCC_CR_HSITRIM (0x1F << 3) + #define RCC_CR_HSIRDY (1U << RCC_CR_HSIRDY_BIT) + #define RCC_CR_HSION (1U << RCC_CR_HSION_BIT) + +Clock configuration register +++++++++++++++++++++++++++++ + +:: + + #define RCC_CFGR_USBPRE_BIT 22 + #define RCC_CFGR_PLLXTPRE_BIT 17 + #define RCC_CFGR_PLLSRC_BIT 16 + + #define RCC_CFGR_MCO (0x3 << 24) + #define RCC_CFGR_USBPRE (1U << RCC_CFGR_USBPRE_BIT) + #define RCC_CFGR_PLLMUL (0xF << 18) + #define RCC_CFGR_PLLXTPRE (1U << RCC_CFGR_PLLXTPRE_BIT) + #define RCC_CFGR_PLLSRC (1U << RCC_CFGR_PLLSRC_BIT) + #define RCC_CFGR_ADCPRE (0x3 << 14) + #define RCC_CFGR_PPRE2 (0x7 << 11) + #define RCC_CFGR_PPRE1 (0x7 << 8) + #define RCC_CFGR_HPRE (0xF << 4) + #define RCC_CFGR_SWS (0x3 << 2) + #define RCC_CFGR_SWS_PLL (0x2 << 2) + #define RCC_CFGR_SWS_HSE (0x1 << 2) + #define RCC_CFGR_SW 0x3 + #define RCC_CFGR_SW_PLL 0x2 + #define RCC_CFGR_SW_HSE 0x1 + +Clock interrupt register +++++++++++++++++++++++++ + +:: + + #define RCC_CIR_CSSC_BIT 23 + #define RCC_CIR_PLLRDYC_BIT 20 + #define RCC_CIR_HSERDYC_BIT 19 + #define RCC_CIR_HSIRDYC_BIT 18 + #define RCC_CIR_LSERDYC_BIT 17 + #define RCC_CIR_LSIRDYC_BIT 16 + #define RCC_CIR_PLLRDYIE_BIT 12 + #define RCC_CIR_HSERDYIE_BIT 11 + #define RCC_CIR_HSIRDYIE_BIT 10 + #define RCC_CIR_LSERDYIE_BIT 9 + #define RCC_CIR_LSIRDYIE_BIT 8 + #define RCC_CIR_CSSF_BIT 7 + #define RCC_CIR_PLLRDYF_BIT 4 + #define RCC_CIR_HSERDYF_BIT 3 + #define RCC_CIR_HSIRDYF_BIT 2 + #define RCC_CIR_LSERDYF_BIT 1 + #define RCC_CIR_LSIRDYF_BIT 0 + + #define RCC_CIR_CSSC (1U << RCC_CIR_CSSC_BIT) + #define RCC_CIR_PLLRDYC (1U << RCC_CIR_PLLRDYC_BIT) + #define RCC_CIR_HSERDYC (1U << RCC_CIR_HSERDYC_BIT) + #define RCC_CIR_HSIRDYC (1U << RCC_CIR_HSIRDYC_BIT) + #define RCC_CIR_LSERDYC (1U << RCC_CIR_LSERDYC_BIT) + #define RCC_CIR_LSIRDYC (1U << RCC_CIR_LSIRDYC_BIT) + #define RCC_CIR_PLLRDYIE (1U << RCC_CIR_PLLRDYIE_BIT) + #define RCC_CIR_HSERDYIE (1U << RCC_CIR_HSERDYIE_BIT) + #define RCC_CIR_HSIRDYIE (1U << RCC_CIR_HSIRDYIE_BIT) + #define RCC_CIR_LSERDYIE (1U << RCC_CIR_LSERDYIE_BIT) + #define RCC_CIR_LSIRDYIE (1U << RCC_CIR_LSIRDYIE_BIT) + #define RCC_CIR_CSSF (1U << RCC_CIR_CSSF_BIT) + #define RCC_CIR_PLLRDYF (1U << RCC_CIR_PLLRDYF_BIT) + #define RCC_CIR_HSERDYF (1U << RCC_CIR_HSERDYF_BIT) + #define RCC_CIR_HSIRDYF (1U << RCC_CIR_HSIRDYF_BIT) + #define RCC_CIR_LSERDYF (1U << RCC_CIR_LSERDYF_BIT) + #define RCC_CIR_LSIRDYF (1U << RCC_CIR_LSIRDYF_BIT) + +Peripheral reset registers +++++++++++++++++++++++++++ + +:: + + #define RCC_APB2RSTR_TIM11RST_BIT 21 + #define RCC_APB2RSTR_TIM10RST_BIT 20 + #define RCC_APB2RSTR_TIM9RST_BIT 19 + #define RCC_APB2RSTR_ADC3RST_BIT 15 + #define RCC_APB2RSTR_USART1RST_BIT 14 + #define RCC_APB2RSTR_TIM8RST_BIT 13 + #define RCC_APB2RSTR_SPI1RST_BIT 12 + #define RCC_APB2RSTR_TIM1RST_BIT 11 + #define RCC_APB2RSTR_ADC2RST_BIT 10 + #define RCC_APB2RSTR_ADC1RST_BIT 9 + #define RCC_APB2RSTR_IOPGRST_BIT 8 + #define RCC_APB2RSTR_IOPFRST_BIT 7 + #define RCC_APB2RSTR_IOPERST_BIT 6 + #define RCC_APB2RSTR_IOPDRST_BIT 5 + #define RCC_APB2RSTR_IOPCRST_BIT 4 + #define RCC_APB2RSTR_IOPBRST_BIT 3 + #define RCC_APB2RSTR_IOPARST_BIT 2 + #define RCC_APB2RSTR_AFIORST_BIT 0 + + #define RCC_APB2RSTR_TIM11RST (1U << RCC_APB2RSTR_TIM11RST_BIT) + #define RCC_APB2RSTR_TIM10RST (1U << RCC_APB2RSTR_TIM10RST_BIT) + #define RCC_APB2RSTR_TIM9RST (1U << RCC_APB2RSTR_TIM9RST_BIT) + #define RCC_APB2RSTR_ADC3RST (1U << RCC_APB2RSTR_ADC3RST_BIT) + #define RCC_APB2RSTR_USART1RST (1U << RCC_APB2RSTR_USART1RST_BIT) + #define RCC_APB2RSTR_TIM8RST (1U << RCC_APB2RSTR_TIM8RST_BIT) + #define RCC_APB2RSTR_SPI1RST (1U << RCC_APB2RSTR_SPI1RST_BIT) + #define RCC_APB2RSTR_TIM1RST (1U << RCC_APB2RSTR_TIM1RST_BIT) + #define RCC_APB2RSTR_ADC2RST (1U << RCC_APB2RSTR_ADC2RST_BIT) + #define RCC_APB2RSTR_ADC1RST (1U << RCC_APB2RSTR_ADC1RST_BIT) + #define RCC_APB2RSTR_IOPGRST (1U << RCC_APB2RSTR_IOPGRST_BIT) + #define RCC_APB2RSTR_IOPFRST (1U << RCC_APB2RSTR_IOPFRST_BIT) + #define RCC_APB2RSTR_IOPERST (1U << RCC_APB2RSTR_IOPERST_BIT) + #define RCC_APB2RSTR_IOPDRST (1U << RCC_APB2RSTR_IOPDRST_BIT) + #define RCC_APB2RSTR_IOPCRST (1U << RCC_APB2RSTR_IOPCRST_BIT) + #define RCC_APB2RSTR_IOPBRST (1U << RCC_APB2RSTR_IOPBRST_BIT) + #define RCC_APB2RSTR_IOPARST (1U << RCC_APB2RSTR_IOPARST_BIT) + #define RCC_APB2RSTR_AFIORST (1U << RCC_APB2RSTR_AFIORST_BIT) + + #define RCC_APB1RSTR_DACRST_BIT 29 + #define RCC_APB1RSTR_PWRRST_BIT 28 + #define RCC_APB1RSTR_BKPRST_BIT 27 + #define RCC_APB1RSTR_CANRST_BIT 25 + #define RCC_APB1RSTR_USBRST_BIT 23 + #define RCC_APB1RSTR_I2C2RST_BIT 22 + #define RCC_APB1RSTR_I2C1RST_BIT 21 + #define RCC_APB1RSTR_UART5RST_BIT 20 + #define RCC_APB1RSTR_UART4RST_BIT 19 + #define RCC_APB1RSTR_USART3RST_BIT 18 + #define RCC_APB1RSTR_USART2RST_BIT 17 + #define RCC_APB1RSTR_SPI3RST_BIT 15 + #define RCC_APB1RSTR_SPI2RST_BIT 14 + #define RCC_APB1RSTR_WWDRST_BIT 11 + #define RCC_APB1RSTR_TIM14RST_BIT 8 + #define RCC_APB1RSTR_TIM13RST_BIT 7 + #define RCC_APB1RSTR_TIM12RST_BIT 6 + #define RCC_APB1RSTR_TIM7RST_BIT 5 + #define RCC_APB1RSTR_TIM6RST_BIT 4 + #define RCC_APB1RSTR_TIM5RST_BIT 3 + #define RCC_APB1RSTR_TIM4RST_BIT 2 + #define RCC_APB1RSTR_TIM3RST_BIT 1 + #define RCC_APB1RSTR_TIM2RST_BIT 0 + + #define RCC_APB1RSTR_DACRST (1U << RCC_APB1RSTR_DACRST_BIT) + #define RCC_APB1RSTR_PWRRST (1U << RCC_APB1RSTR_PWRRST_BIT) + #define RCC_APB1RSTR_BKPRST (1U << RCC_APB1RSTR_BKPRST_BIT) + #define RCC_APB1RSTR_CANRST (1U << RCC_APB1RSTR_CANRST_BIT) + #define RCC_APB1RSTR_USBRST (1U << RCC_APB1RSTR_USBRST_BIT) + #define RCC_APB1RSTR_I2C2RST (1U << RCC_APB1RSTR_I2C2RST_BIT) + #define RCC_APB1RSTR_I2C1RST (1U << RCC_APB1RSTR_I2C1RST_BIT) + #define RCC_APB1RSTR_UART5RST (1U << RCC_APB1RSTR_UART5RST_BIT) + #define RCC_APB1RSTR_UART4RST (1U << RCC_APB1RSTR_UART4RST_BIT) + #define RCC_APB1RSTR_USART3RST (1U << RCC_APB1RSTR_USART3RST_BIT) + #define RCC_APB1RSTR_USART2RST (1U << RCC_APB1RSTR_USART2RST_BIT) + #define RCC_APB1RSTR_SPI3RST (1U << RCC_APB1RSTR_SPI3RST_BIT) + #define RCC_APB1RSTR_SPI2RST (1U << RCC_APB1RSTR_SPI2RST_BIT) + #define RCC_APB1RSTR_WWDRST (1U << RCC_APB1RSTR_WWDRST_BIT) + #define RCC_APB1RSTR_TIM14RST (1U << RCC_APB1RSTR_TIM14RST_BIT) + #define RCC_APB1RSTR_TIM13RST (1U << RCC_APB1RSTR_TIM13RST_BIT) + #define RCC_APB1RSTR_TIM12RST (1U << RCC_APB1RSTR_TIM12RST_BIT) + #define RCC_APB1RSTR_TIM7RST (1U << RCC_APB1RSTR_TIM7RST_BIT) + #define RCC_APB1RSTR_TIM6RST (1U << RCC_APB1RSTR_TIM6RST_BIT) + #define RCC_APB1RSTR_TIM5RST (1U << RCC_APB1RSTR_TIM5RST_BIT) + #define RCC_APB1RSTR_TIM4RST (1U << RCC_APB1RSTR_TIM4RST_BIT) + #define RCC_APB1RSTR_TIM3RST (1U << RCC_APB1RSTR_TIM3RST_BIT) + #define RCC_APB1RSTR_TIM2RST (1U << RCC_APB1RSTR_TIM2RST_BIT) + +Peripheral clock enable registers ++++++++++++++++++++++++++++++++++ + +:: + + #define RCC_AHBENR_SDIOEN_BIT 10 + #define RCC_AHBENR_FSMCEN_BIT 8 + #define RCC_AHBENR_CRCEN_BIT 7 + #define RCC_AHBENR_FLITFEN_BIT 4 + #define RCC_AHBENR_SRAMEN_BIT 2 + #define RCC_AHBENR_DMA2EN_BIT 1 + #define RCC_AHBENR_DMA1EN_BIT 0 + + #define RCC_AHBENR_SDIOEN (1U << RCC_AHBENR_SDIOEN_BIT) + #define RCC_AHBENR_FSMCEN (1U << RCC_AHBENR_FSMCEN_BIT) + #define RCC_AHBENR_CRCEN (1U << RCC_AHBENR_CRCEN_BIT) + #define RCC_AHBENR_FLITFEN (1U << RCC_AHBENR_FLITFEN_BIT) + #define RCC_AHBENR_SRAMEN (1U << RCC_AHBENR_SRAMEN_BIT) + #define RCC_AHBENR_DMA2EN (1U << RCC_AHBENR_DMA2EN_BIT) + #define RCC_AHBENR_DMA1EN (1U << RCC_AHBENR_DMA1EN_BIT) + + #define RCC_APB2ENR_TIM11EN_BIT 21 + #define RCC_APB2ENR_TIM10EN_BIT 20 + #define RCC_APB2ENR_TIM9EN_BIT 19 + #define RCC_APB2ENR_ADC3EN_BIT 15 + #define RCC_APB2ENR_USART1EN_BIT 14 + #define RCC_APB2ENR_TIM8EN_BIT 13 + #define RCC_APB2ENR_SPI1EN_BIT 12 + #define RCC_APB2ENR_TIM1EN_BIT 11 + #define RCC_APB2ENR_ADC2EN_BIT 10 + #define RCC_APB2ENR_ADC1EN_BIT 9 + #define RCC_APB2ENR_IOPGEN_BIT 8 + #define RCC_APB2ENR_IOPFEN_BIT 7 + #define RCC_APB2ENR_IOPEEN_BIT 6 + #define RCC_APB2ENR_IOPDEN_BIT 5 + #define RCC_APB2ENR_IOPCEN_BIT 4 + #define RCC_APB2ENR_IOPBEN_BIT 3 + #define RCC_APB2ENR_IOPAEN_BIT 2 + #define RCC_APB2ENR_AFIOEN_BIT 0 + + #define RCC_APB2ENR_TIM11EN (1U << RCC_APB2ENR_TIM11EN_BIT) + #define RCC_APB2ENR_TIM10EN (1U << RCC_APB2ENR_TIM10EN_BIT) + #define RCC_APB2ENR_TIM9EN (1U << RCC_APB2ENR_TIM9EN_BIT) + #define RCC_APB2ENR_ADC3EN (1U << RCC_APB2ENR_ADC3EN_BIT) + #define RCC_APB2ENR_USART1EN (1U << RCC_APB2ENR_USART1EN_BIT) + #define RCC_APB2ENR_TIM8EN (1U << RCC_APB2ENR_TIM8EN_BIT) + #define RCC_APB2ENR_SPI1EN (1U << RCC_APB2ENR_SPI1EN_BIT) + #define RCC_APB2ENR_TIM1EN (1U << RCC_APB2ENR_TIM1EN_BIT) + #define RCC_APB2ENR_ADC2EN (1U << RCC_APB2ENR_ADC2EN_BIT) + #define RCC_APB2ENR_ADC1EN (1U << RCC_APB2ENR_ADC1EN_BIT) + #define RCC_APB2ENR_IOPGEN (1U << RCC_APB2ENR_IOPGEN_BIT) + #define RCC_APB2ENR_IOPFEN (1U << RCC_APB2ENR_IOPFEN_BIT) + #define RCC_APB2ENR_IOPEEN (1U << RCC_APB2ENR_IOPEEN_BIT) + #define RCC_APB2ENR_IOPDEN (1U << RCC_APB2ENR_IOPDEN_BIT) + #define RCC_APB2ENR_IOPCEN (1U << RCC_APB2ENR_IOPCEN_BIT) + #define RCC_APB2ENR_IOPBEN (1U << RCC_APB2ENR_IOPBEN_BIT) + #define RCC_APB2ENR_IOPAEN (1U << RCC_APB2ENR_IOPAEN_BIT) + #define RCC_APB2ENR_AFIOEN (1U << RCC_APB2ENR_AFIOEN_BIT) + + #define RCC_APB1ENR_DACEN_BIT 29 + #define RCC_APB1ENR_PWREN_BIT 28 + #define RCC_APB1ENR_BKPEN_BIT 27 + #define RCC_APB1ENR_CANEN_BIT 25 + #define RCC_APB1ENR_USBEN_BIT 23 + #define RCC_APB1ENR_I2C2EN_BIT 22 + #define RCC_APB1ENR_I2C1EN_BIT 21 + #define RCC_APB1ENR_UART5EN_BIT 20 + #define RCC_APB1ENR_UART4EN_BIT 19 + #define RCC_APB1ENR_USART3EN_BIT 18 + #define RCC_APB1ENR_USART2EN_BIT 17 + #define RCC_APB1ENR_SPI3EN_BIT 15 + #define RCC_APB1ENR_SPI2EN_BIT 14 + #define RCC_APB1ENR_WWDEN_BIT 11 + #define RCC_APB1ENR_TIM14EN_BIT 8 + #define RCC_APB1ENR_TIM13EN_BIT 7 + #define RCC_APB1ENR_TIM12EN_BIT 6 + #define RCC_APB1ENR_TIM7EN_BIT 5 + #define RCC_APB1ENR_TIM6EN_BIT 4 + #define RCC_APB1ENR_TIM5EN_BIT 3 + #define RCC_APB1ENR_TIM4EN_BIT 2 + #define RCC_APB1ENR_TIM3EN_BIT 1 + #define RCC_APB1ENR_TIM2EN_BIT 0 + + #define RCC_APB1ENR_DACEN (1U << RCC_APB1ENR_DACEN_BIT) + #define RCC_APB1ENR_PWREN (1U << RCC_APB1ENR_PWREN_BIT) + #define RCC_APB1ENR_BKPEN (1U << RCC_APB1ENR_BKPEN_BIT) + #define RCC_APB1ENR_CANEN (1U << RCC_APB1ENR_CANEN_BIT) + #define RCC_APB1ENR_USBEN (1U << RCC_APB1ENR_USBEN_BIT) + #define RCC_APB1ENR_I2C2EN (1U << RCC_APB1ENR_I2C2EN_BIT) + #define RCC_APB1ENR_I2C1EN (1U << RCC_APB1ENR_I2C1EN_BIT) + #define RCC_APB1ENR_UART5EN (1U << RCC_APB1ENR_UART5EN_BIT) + #define RCC_APB1ENR_UART4EN (1U << RCC_APB1ENR_UART4EN_BIT) + #define RCC_APB1ENR_USART3EN (1U << RCC_APB1ENR_USART3EN_BIT) + #define RCC_APB1ENR_USART2EN (1U << RCC_APB1ENR_USART2EN_BIT) + #define RCC_APB1ENR_SPI3EN (1U << RCC_APB1ENR_SPI3EN_BIT) + #define RCC_APB1ENR_SPI2EN (1U << RCC_APB1ENR_SPI2EN_BIT) + #define RCC_APB1ENR_WWDEN (1U << RCC_APB1ENR_WWDEN_BIT) + #define RCC_APB1ENR_TIM14EN (1U << RCC_APB1ENR_TIM14EN_BIT) + #define RCC_APB1ENR_TIM13EN (1U << RCC_APB1ENR_TIM13EN_BIT) + #define RCC_APB1ENR_TIM12EN (1U << RCC_APB1ENR_TIM12EN_BIT) + #define RCC_APB1ENR_TIM7EN (1U << RCC_APB1ENR_TIM7EN_BIT) + #define RCC_APB1ENR_TIM6EN (1U << RCC_APB1ENR_TIM6EN_BIT) + #define RCC_APB1ENR_TIM5EN (1U << RCC_APB1ENR_TIM5EN_BIT) + #define RCC_APB1ENR_TIM4EN (1U << RCC_APB1ENR_TIM4EN_BIT) + #define RCC_APB1ENR_TIM3EN (1U << RCC_APB1ENR_TIM3EN_BIT) + #define RCC_APB1ENR_TIM2EN (1U << RCC_APB1ENR_TIM2EN_BIT) + +Backup domain control register +++++++++++++++++++++++++++++++ + +:: + + #define RCC_BDCR_BDRST_BIT 16 + #define RCC_BDCR_RTCEN_BIT 15 + #define RCC_BDCR_LSEBYP_BIT 2 + #define RCC_BDCR_LSERDY_BIT 1 + #define RCC_BDCR_LSEON_BIT 0 + + #define RCC_BDCR_BDRST (1U << RCC_BDCR_BDRST_BIT) + #define RCC_BDCR_RTCEN (1U << RCC_BDCR_RTC_BIT) + #define RCC_BDCR_RTCSEL (0x3 << 8) + #define RCC_BDCR_RTCSEL_NONE (0x0 << 8) + #define RCC_BDCR_RTCSEL_LSE (0x1 << 8) + #define RCC_BDCR_RTCSEL_HSE (0x3 << 8) + #define RCC_BDCR_LSEBYP (1U << RCC_BDCR_LSEBYP_BIT) + #define RCC_BDCR_LSERDY (1U << RCC_BDCR_LSERDY_BIT) + #define RCC_BDCR_LSEON (1U << RCC_BDCR_LSEON_BIT) + +Control/status register ++++++++++++++++++++++++ + +:: + + #define RCC_CSR_LPWRRSTF_BIT 31 + #define RCC_CSR_WWDGRSTF_BIT 30 + #define RCC_CSR_IWDGRSTF_BIT 29 + #define RCC_CSR_SFTRSTF_BIT 28 + #define RCC_CSR_PORRSTF_BIT 27 + #define RCC_CSR_PINRSTF_BIT 26 + #define RCC_CSR_RMVF_BIT 24 + #define RCC_CSR_LSIRDY_BIT 1 + #define RCC_CSR_LSION_BIT 0 + + #define RCC_CSR_LPWRRSTF (1U << RCC_CSR_LPWRRSTF_BIT) + #define RCC_CSR_WWDGRSTF (1U << RCC_CSR_WWDGRSTF_BIT) + #define RCC_CSR_IWDGRSTF (1U << RCC_CSR_IWDGRSTF_BIT) + #define RCC_CSR_SFTRSTF (1U << RCC_CSR_SFTRSTF_BIT) + #define RCC_CSR_PORRSTF (1U << RCC_CSR_PORRSTF_BIT) + #define RCC_CSR_PINRSTF (1U << RCC_CSR_PINRSTF_BIT) + #define RCC_CSR_RMVF (1U << RCC_CSR_RMVF_BIT) + #define RCC_CSR_LSIRDY (1U << RCC_CSR_LSIRDY_BIT) + #define RCC_CSR_LSION (1U << RCC_CSR_LSION_BIT) + +STM32F2 Targets +~~~~~~~~~~~~~~~ + +Clock control register +++++++++++++++++++++++ + +:: + + #define RCC_CR_PLLI2SRDY_BIT 27 + #define RCC_CR_PLLI2SON_BIT 26 + #define RCC_CR_PLLRDY_BIT 25 + #define RCC_CR_PLLON_BIT 24 + #define RCC_CR_CSSON_BIT 19 + #define RCC_CR_HSEBYP_BIT 18 + #define RCC_CR_HSERDY_BIT 17 + #define RCC_CR_HSEON_BIT 16 + #define RCC_CR_HSIRDY_BIT 1 + #define RCC_CR_HSION_BIT 0 + + #define RCC_CR_PLLI2SRDY (1U << RCC_CR_PLLI2SRDY_BIT) + #define RCC_CR_PLLI2SON (1U << RCC_CR_PLLI2SON_BIT) + #define RCC_CR_PLLRDY (1U << RCC_CR_PLLRDY_BIT) + #define RCC_CR_PLLON (1U << RCC_CR_PLLON_BIT) + #define RCC_CR_CSSON (1U << RCC_CR_CSSON_BIT) + #define RCC_CR_HSEBYP (1U << RCC_CR_HSEBYP_BIT) + #define RCC_CR_HSERDY (1U << RCC_CR_HSERDY_BIT) + #define RCC_CR_HSEON (1U << RCC_CR_HSEON_BIT) + #define RCC_CR_HSICAL (0xFF << 8) + #define RCC_CR_HSITRIM (0x1F << 3) + #define RCC_CR_HSIRDY (1U << RCC_CR_HSIRDY_BIT) + #define RCC_CR_HSION (1U << RCC_CR_HSION_BIT) + +PLL configuration register +++++++++++++++++++++++++++ + +:: + + #define RCC_PLLCFGR_PLLSRC_BIT 22 + + #define RCC_PLLCFGR_PLLQ (0xF << 24) + #define RCC_PLLCFGR_PLLSRC (1U << RCC_PLLCFGR_PLLSRC_BIT) + #define RCC_PLLCFGR_PLLSRC_HSI (0x0 << RCC_PLLCFGR_PLLSRC_BIT) + #define RCC_PLLCFGR_PLLSRC_HSE (0x1 << RCC_PLLCFGR_PLLSRC_BIT) + #define RCC_PLLCFGR_PLLP (0x3 << 16) + #define RCC_PLLCFGR_PLLN (0x1FF << 6) + #define RCC_PLLCFGR_PLLM 0x1F + +Clock configuration register +++++++++++++++++++++++++++++ + +:: + + #define RCC_CFGR_I2SSRC_BIT 23 + + #define RCC_CFGR_MCO2 (0x3 << 30) + #define RCC_CFGR_MCO2_SYSCLK (0x0 << 30) + #define RCC_CFGR_MCO2_PLLI2S (0x1 << 30) + #define RCC_CFGR_MCO2_HSE (0x2 << 30) + #define RCC_CFGR_MCO2_PLL (0x3 << 30) + + #define RCC_CFGR_MCO2PRE (0x7 << 27) + #define RCC_CFGR_MCO2PRE_DIV_1 (0x0 << 27) + #define RCC_CFGR_MCO2PRE_DIV_2 (0x4 << 27) + #define RCC_CFGR_MCO2PRE_DIV_3 (0x5 << 27) + #define RCC_CFGR_MCO2PRE_DIV_4 (0x6 << 27) + #define RCC_CFGR_MCO2PRE_DIV_5 (0x7 << 27) + + #define RCC_CFGR_MCO1PRE (0x7 << 24) + #define RCC_CFGR_MCO1PRE_DIV_1 (0x0 << 24) + #define RCC_CFGR_MCO1PRE_DIV_2 (0x4 << 24) + #define RCC_CFGR_MCO1PRE_DIV_3 (0x5 << 24) + #define RCC_CFGR_MCO1PRE_DIV_4 (0x6 << 24) + #define RCC_CFGR_MCO1PRE_DIV_5 (0x7 << 24) + + #define RCC_CFGR_I2SSRC (1U << RCC_CFGR_I2SSRC_BIT) + #define RCC_CFGR_I2SSRC_PLLI2S (0 << RCC_CFGR_I2SSRC_BIT) + #define RCC_CFGR_I2SSRC_I2S_CKIN (1 << RCC_CFGR_I2SSRC_BIT) + + #define RCC_CFGR_MCO1 (0x3 << 21) + #define RCC_CFGR_MCO1_HSI (0x0 << 21) + #define RCC_CFGR_MCO1_LSE (0x1 << 21) + #define RCC_CFGR_MCO1_HSE (0x2 << 21) + #define RCC_CFGR_MCO1_PLL (0x3 << 21) + + #define RCC_CFGR_RTCPRE (0x1F << 16) + + /* Skipped: all the 0b0xx values meaning "not divided" */ + #define RCC_CFGR_PPRE2 (0x7 << 13) + #define RCC_CFGR_PPRE2_AHB_DIV_2 (0x4 << 13) + #define RCC_CFGR_PPRE2_AHB_DIV_4 (0x5 << 13) + #define RCC_CFGR_PPRE2_AHB_DIV_8 (0x6 << 13) + #define RCC_CFGR_PPRE2_AHB_DIV_16 (0x7 << 13) + + /* Skipped: all the 0b0xx values meaning "not divided" */ + #define RCC_CFGR_PPRE1 (0x7 << 10) + #define RCC_CFGR_PPRE1_AHB_DIV_2 (0x4 << 10) + #define RCC_CFGR_PPRE1_AHB_DIV_4 (0x5 << 10) + #define RCC_CFGR_PPRE1_AHB_DIV_8 (0x6 << 10) + #define RCC_CFGR_PPRE1_AHB_DIV_16 (0x7 << 10) + + /* Skipped: all the 0b0xxx values meaning "not divided" */ + #define RCC_CFGR_HPRE (0xF << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_2 (0x8 << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_4 (0x9 << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_8 (0xA << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_16 (0xB << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_64 (0xC << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_128 (0xD << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_256 (0xE << 4) + #define RCC_CFGR_HPRE_SYSCLK_DIV_512 (0xF << 4) + + #define RCC_CFGR_SWS (0x3 << 2) + #define RCC_CFGR_SWS_HSI (0x0 << 2) + #define RCC_CFGR_SWS_HSE (0x1 << 2) + #define RCC_CFGR_SWS_PLL (0x2 << 2) + + #define RCC_CFGR_SW 0x3 + #define RCC_CFGR_SW_HSI 0x0 + #define RCC_CFGR_SW_HSE 0x1 + #define RCC_CFGR_SW_PLL 0x2 + +Clock interrupt register +++++++++++++++++++++++++ + +:: + + #define RCC_CIR_CSSC_BIT 23 + + #define RCC_CIR_PLLI2SRDYC_BIT 21 + #define RCC_CIR_PLLRDYC_BIT 20 + #define RCC_CIR_HSERDYC_BIT 19 + #define RCC_CIR_HSIRDYC_BIT 18 + #define RCC_CIR_LSERDYC_BIT 17 + #define RCC_CIR_LSIRDYC_BIT 16 + + #define RCC_CIR_PLLI2SRDYIE_BIT 13 + #define RCC_CIR_PLLRDYIE_BIT 12 + #define RCC_CIR_HSERDYIE_BIT 11 + #define RCC_CIR_HSIRDYIE_BIT 10 + #define RCC_CIR_LSERDYIE_BIT 9 + #define RCC_CIR_LSIRDYIE_BIT 8 + + #define RCC_CIR_CSSF_BIT 7 + + #define RCC_CIR_PLLI2SRDYF_BIT 5 + #define RCC_CIR_PLLRDYF_BIT 4 + #define RCC_CIR_HSERDYF_BIT 3 + #define RCC_CIR_HSIRDYF_BIT 2 + #define RCC_CIR_LSERDYF_BIT 1 + #define RCC_CIR_LSIRDYF_BIT 0 + + #define RCC_CIR_CSSC (1U << RCC_CIR_CSSC_BIT) + + #define RCC_CIR_PLLI2SRDYC (1U << RCC_CIR_PLLI2SRDYC_BIT) + #define RCC_CIR_PLLRDYC (1U << RCC_CIR_PLLRDYC_BIT) + #define RCC_CIR_HSERDYC (1U << RCC_CIR_HSERDYC_BIT) + #define RCC_CIR_HSIRDYC (1U << RCC_CIR_HSIRDYC_BIT) + #define RCC_CIR_LSERDYC (1U << RCC_CIR_LSERDYC_BIT) + #define RCC_CIR_LSIRDYC (1U << RCC_CIR_LSIRDYC_BIT) + + #define RCC_CIR_PLLI2SRDYIE (1U << RCC_CIR_PLLI2SRDYIE_BIT) + #define RCC_CIR_PLLRDYIE (1U << RCC_CIR_PLLRDYIE_BIT) + #define RCC_CIR_HSERDYIE (1U << RCC_CIR_HSERDYIE_BIT) + #define RCC_CIR_HSIRDYIE (1U << RCC_CIR_HSIRDYIE_BIT) + #define RCC_CIR_LSERDYIE (1U << RCC_CIR_LSERDYIE_BIT) + #define RCC_CIR_LSIRDYIE (1U << RCC_CIR_LSIRDYIE_BIT) + + #define RCC_CIR_CSSF (1U << RCC_CIR_CSSF_BIT) + + #define RCC_CIR_PLLI2SRDYF (1U << RCC_CIR_PLLI2SRDYF_BIT) + #define RCC_CIR_PLLRDYF (1U << RCC_CIR_PLLRDYF_BIT) + #define RCC_CIR_HSERDYF (1U << RCC_CIR_HSERDYF_BIT) + #define RCC_CIR_HSIRDYF (1U << RCC_CIR_HSIRDYF_BIT) + #define RCC_CIR_LSERDYF (1U << RCC_CIR_LSERDYF_BIT) + #define RCC_CIR_LSIRDYF (1U << RCC_CIR_LSIRDYF_BIT) + +Peripheral reset registers +++++++++++++++++++++++++++ + +:: + + /* AHB1 */ + + #define RCC_AHB1RSTR_OTGHSRST_BIT 29 + #define RCC_AHB1RSTR_ETHMACRST_BIT 25 + #define RCC_AHB1RSTR_DMA2RST_BIT 22 + #define RCC_AHB1RSTR_DMA1RST_BIT 21 + #define RCC_AHB1RSTR_CRCRST_BIT 12 + #define RCC_AHB1RSTR_GPIOIRST_BIT 8 + #define RCC_AHB1RSTR_GPIOHRST_BIT 7 + #define RCC_AHB1RSTR_GPIOGRST_BIT 6 + #define RCC_AHB1RSTR_GPIOFRST_BIT 5 + #define RCC_AHB1RSTR_GPIOERST_BIT 4 + #define RCC_AHB1RSTR_GPIODRST_BIT 3 + #define RCC_AHB1RSTR_GPIOCRST_BIT 2 + #define RCC_AHB1RSTR_GPIOBRST_BIT 1 + #define RCC_AHB1RSTR_GPIOARST_BIT 0 + + #define RCC_AHB1RSTR_OTGHSRST (1U << RCC_AHB1RSTR_OTGHSRST_BIT) + #define RCC_AHB1RSTR_ETHMACRST (1U << RCC_AHB1RSTR_ETHMACRST_BIT) + #define RCC_AHB1RSTR_DMA2RST (1U << RCC_AHB1RSTR_DMA2RST_BIT) + #define RCC_AHB1RSTR_DMA1RST (1U << RCC_AHB1RSTR_DMA1RST_BIT) + #define RCC_AHB1RSTR_CRCRST (1U << RCC_AHB1RSTR_CRCRST_BIT) + #define RCC_AHB1RSTR_GPIOIRST (1U << RCC_AHB1RSTR_GPIOIRST_BIT) + #define RCC_AHB1RSTR_GPIOHRST (1U << RCC_AHB1RSTR_GPIOHRST_BIT) + #define RCC_AHB1RSTR_GPIOGRST (1U << RCC_AHB1RSTR_GPIOGRST_BIT) + #define RCC_AHB1RSTR_GPIOFRST (1U << RCC_AHB1RSTR_GPIOFRST_BIT) + #define RCC_AHB1RSTR_GPIOERST (1U << RCC_AHB1RSTR_GPIOERST_BIT) + #define RCC_AHB1RSTR_GPIODRST (1U << RCC_AHB1RSTR_GPIODRST_BIT) + #define RCC_AHB1RSTR_GPIOCRST (1U << RCC_AHB1RSTR_GPIOCRST_BIT) + #define RCC_AHB1RSTR_GPIOBRST (1U << RCC_AHB1RSTR_GPIOBRST_BIT) + #define RCC_AHB1RSTR_GPIOARST (1U << RCC_AHB1RSTR_GPIOARST_BIT) + + /* AHB2 */ + + #define RCC_AHB2RSTR_OTGFSRST_BIT 7 + #define RCC_AHB2RSTR_RNGRST_BIT 6 + #define RCC_AHB2RSTR_HASHRST_BIT 5 + #define RCC_AHB2RSTR_CRYPRST_BIT 4 + #define RCC_AHB2RSTR_DCMIRST_BIT 0 + + #define RCC_AHB2RSTR_OTGFSRST (1U << RCC_AHB2RSTR_OTGFSRST_BIT) + #define RCC_AHB2RSTR_RNGRST (1U << RCC_AHB2RSTR_RNGRST_BIT) + #define RCC_AHB2RSTR_HASHRST (1U << RCC_AHB2RSTR_HASHRST_BIT) + #define RCC_AHB2RSTR_CRYPRST (1U << RCC_AHB2RSTR_CRYPRST_BIT) + #define RCC_AHB2RSTR_DCMIRST (1U << RCC_AHB2RSTR_DCMIRST_BIT) + + /* AHB3 */ + + #define RCC_AHB3RSTR_FSMCRST_BIT 0 + + #define RCC_AHB3RSTR_FSMCRST (1U << RCC_AHB3RSTR_FSMCRST_BIT) + + /* APB1 */ + + #define RCC_APB1RSTR_DACRST_BIT 29 + #define RCC_APB1RSTR_PWRRST_BIT 28 + #define RCC_APB1RSTR_CAN2RST_BIT 26 + #define RCC_APB1RSTR_CAN1RST_BIT 25 + #define RCC_APB1RSTR_I2C3RST_BIT 23 + #define RCC_APB1RSTR_I2C2RST_BIT 22 + #define RCC_APB1RSTR_I2C1RST_BIT 21 + #define RCC_APB1RSTR_UART5RST_BIT 20 + #define RCC_APB1RSTR_UART4RST_BIT 19 + #define RCC_APB1RSTR_UART3RST_BIT 18 + #define RCC_APB1RSTR_UART2RST_BIT 17 + #define RCC_APB1RSTR_SPI3RST_BIT 15 + #define RCC_APB1RSTR_SPI2RST_BIT 14 + #define RCC_APB1RSTR_WWDGRST_BIT 11 + #define RCC_APB1RSTR_TIM14RST_BIT 8 + #define RCC_APB1RSTR_TIM13RST_BIT 7 + #define RCC_APB1RSTR_TIM12RST_BIT 6 + #define RCC_APB1RSTR_TIM7RST_BIT 5 + #define RCC_APB1RSTR_TIM6RST_BIT 4 + #define RCC_APB1RSTR_TIM5RST_BIT 3 + #define RCC_APB1RSTR_TIM4RST_BIT 2 + #define RCC_APB1RSTR_TIM3RST_BIT 1 + #define RCC_APB1RSTR_TIM2RST_BIT 0 + + #define RCC_APB1RSTR_DACRST (1U << RCC_APB1RSTR_DACRST_BIT) + #define RCC_APB1RSTR_PWRRST (1U << RCC_APB1RSTR_PWRRST_BIT) + #define RCC_APB1RSTR_CAN2RST (1U << RCC_APB1RSTR_CAN2RST_BIT) + #define RCC_APB1RSTR_CAN1RST (1U << RCC_APB1RSTR_CAN1RST_BIT) + #define RCC_APB1RSTR_I2C3RST (1U << RCC_APB1RSTR_I2C3RST_BIT) + #define RCC_APB1RSTR_I2C2RST (1U << RCC_APB1RSTR_I2C2RST_BIT) + #define RCC_APB1RSTR_I2C1RST (1U << RCC_APB1RSTR_I2C1RST_BIT) + #define RCC_APB1RSTR_UART5RST (1U << RCC_APB1RSTR_UART5RST_BIT) + #define RCC_APB1RSTR_UART4RST (1U << RCC_APB1RSTR_UART4RST_BIT) + #define RCC_APB1RSTR_UART3RST (1U << RCC_APB1RSTR_UART3RST_BIT) + #define RCC_APB1RSTR_UART2RST (1U << RCC_APB1RSTR_UART2RST_BIT) + #define RCC_APB1RSTR_SPI3RST (1U << RCC_APB1RSTR_SPI3RST_BIT) + #define RCC_APB1RSTR_SPI2RST (1U << RCC_APB1RSTR_SPI2RST_BIT) + #define RCC_APB1RSTR_WWDGRST (1U << RCC_APB1RSTR_WWDGRST_BIT) + #define RCC_APB1RSTR_TIM14RST (1U << RCC_APB1RSTR_TIM14RST_BIT) + #define RCC_APB1RSTR_TIM13RST (1U << RCC_APB1RSTR_TIM13RST_BIT) + #define RCC_APB1RSTR_TIM12RST (1U << RCC_APB1RSTR_TIM12RST_BIT) + #define RCC_APB1RSTR_TIM7RST (1U << RCC_APB1RSTR_TIM7RST_BIT) + #define RCC_APB1RSTR_TIM6RST (1U << RCC_APB1RSTR_TIM6RST_BIT) + #define RCC_APB1RSTR_TIM5RST (1U << RCC_APB1RSTR_TIM5RST_BIT) + #define RCC_APB1RSTR_TIM4RST (1U << RCC_APB1RSTR_TIM4RST_BIT) + #define RCC_APB1RSTR_TIM3RST (1U << RCC_APB1RSTR_TIM3RST_BIT) + #define RCC_APB1RSTR_TIM2RST (1U << RCC_APB1RSTR_TIM2RST_BIT) + + /* APB2 */ + + #define RCC_APB2RSTR_TIM11RST_BIT 18 + #define RCC_APB2RSTR_TIM10RST_BIT 17 + #define RCC_APB2RSTR_TIM9RST_BIT 16 + #define RCC_APB2RSTR_SYSCFGRST_BIT 14 + #define RCC_APB2RSTR_SPI1RST_BIT 12 + #define RCC_APB2RSTR_SDIORST_BIT 11 + #define RCC_APB2RSTR_ADCRST_BIT 8 + #define RCC_APB2RSTR_USART6RST_BIT 5 + #define RCC_APB2RSTR_USART1RST_BIT 4 + #define RCC_APB2RSTR_TIM8RST_BIT 1 + #define RCC_APB2RSTR_TIM1RST_BIT 0 + + #define RCC_APB2RSTR_TIM11RST (1U << RCC_APB2RSTR_TIM11RST_BIT) + #define RCC_APB2RSTR_TIM10RST (1U << RCC_APB2RSTR_TIM10RST_BIT) + #define RCC_APB2RSTR_TIM9RST (1U << RCC_APB2RSTR_TIM9RST_BIT) + #define RCC_APB2RSTR_SYSCFGRST (1U << RCC_APB2RSTR_SYSCFGRST_BIT) + #define RCC_APB2RSTR_SPI1RST (1U << RCC_APB2RSTR_SPI1RST_BIT) + #define RCC_APB2RSTR_SDIORST (1U << RCC_APB2RSTR_SDIORST_BIT) + #define RCC_APB2RSTR_ADCRST (1U << RCC_APB2RSTR_ADCRST_BIT) + #define RCC_APB2RSTR_USART6RST (1U << RCC_APB2RSTR_USART6RST_BIT) + #define RCC_APB2RSTR_USART1RST (1U << RCC_APB2RSTR_USART1RST_BIT) + #define RCC_APB2RSTR_TIM8RST (1U << RCC_APB2RSTR_TIM8RST_BIT) + #define RCC_APB2RSTR_TIM1RST (1U << RCC_APB2RSTR_TIM1RST_BIT) + +Peripheral clock enable registers ++++++++++++++++++++++++++++++++++ + +:: + + /* AHB1 */ + + #define RCC_AHB1ENR_OTGHSULPIEN_BIT 30 + #define RCC_AHB1ENR_OTGHSEN_BIT 29 + #define RCC_AHB1ENR_ETHMACPTPEN_BIT 28 + #define RCC_AHB1ENR_ETHMACRXEN_BIT 27 + #define RCC_AHB1ENR_ETHMACTXEN_BIT 26 + #define RCC_AHB1ENR_ETHMACEN_BIT 25 + #define RCC_AHB1ENR_DMA2EN_BIT 22 + #define RCC_AHB1ENR_DMA1EN_BIT 21 + #define RCC_AHB1ENR_BKPSRAMEN_BIT 18 + #define RCC_AHB1ENR_CRCEN_BIT 12 + #define RCC_AHB1ENR_GPIOIEN_BIT 8 + #define RCC_AHB1ENR_GPIOHEN_BIT 7 + #define RCC_AHB1ENR_GPIOGEN_BIT 6 + #define RCC_AHB1ENR_GPIOFEN_BIT 5 + #define RCC_AHB1ENR_GPIOEEN_BIT 4 + #define RCC_AHB1ENR_GPIODEN_BIT 3 + #define RCC_AHB1ENR_GPIOCEN_BIT 2 + #define RCC_AHB1ENR_GPIOBEN_BIT 1 + #define RCC_AHB1ENR_GPIOAEN_BIT 0 + + #define RCC_AHB1ENR_OTGHSULPIEN (1U << RCC_AHB1ENR_OTGHSULPIEN_BIT) + #define RCC_AHB1ENR_OTGHSEN (1U << RCC_AHB1ENR_OTGHSEN_BIT) + #define RCC_AHB1ENR_ETHMACPTPEN (1U << RCC_AHB1ENR_ETHMACPTPEN_BIT) + #define RCC_AHB1ENR_ETHMACRXEN (1U << RCC_AHB1ENR_ETHMACRXEN_BIT) + #define RCC_AHB1ENR_ETHMACTXEN (1U << RCC_AHB1ENR_ETHMACTXEN_BIT) + #define RCC_AHB1ENR_ETHMACEN (1U << RCC_AHB1ENR_ETHMACEN_BIT) + #define RCC_AHB1ENR_DMA2EN (1U << RCC_AHB1ENR_DMA2EN_BIT) + #define RCC_AHB1ENR_DMA1EN (1U << RCC_AHB1ENR_DMA1EN_BIT) + #define RCC_AHB1ENR_BKPSRAMEN (1U << RCC_AHB1ENR_BKPSRAMEN_BIT) + #define RCC_AHB1ENR_CRCEN (1U << RCC_AHB1ENR_CRCEN_BIT) + #define RCC_AHB1ENR_GPIOIEN (1U << RCC_AHB1ENR_GPIOIEN_BIT) + #define RCC_AHB1ENR_GPIOHEN (1U << RCC_AHB1ENR_GPIOHEN_BIT) + #define RCC_AHB1ENR_GPIOGEN (1U << RCC_AHB1ENR_GPIOGEN_BIT) + #define RCC_AHB1ENR_GPIOFEN (1U << RCC_AHB1ENR_GPIOFEN_BIT) + #define RCC_AHB1ENR_GPIOEEN (1U << RCC_AHB1ENR_GPIOEEN_BIT) + #define RCC_AHB1ENR_GPIODEN (1U << RCC_AHB1ENR_GPIODEN_BIT) + #define RCC_AHB1ENR_GPIOCEN (1U << RCC_AHB1ENR_GPIOCEN_BIT) + #define RCC_AHB1ENR_GPIOBEN (1U << RCC_AHB1ENR_GPIOBEN_BIT) + #define RCC_AHB1ENR_GPIOAEN (1U << RCC_AHB1ENR_GPIOAEN_BIT) + + /* AHB2 */ + + #define RCC_AHB2ENR_OTGFSEN_BIT 7 + #define RCC_AHB2ENR_RNGEN_BIT 6 + #define RCC_AHB2ENR_HASHEN_BIT 5 + #define RCC_AHB2ENR_CRYPEN_BIT 4 + #define RCC_AHB2ENR_DCMIEN_BIT 0 + + #define RCC_AHB2ENR_OTGFSEN (1U << RCC_AHB2ENR_OTGFSEN_BIT) + #define RCC_AHB2ENR_RNGEN (1U << RCC_AHB2ENR_RNGEN_BIT) + #define RCC_AHB2ENR_HASHEN (1U << RCC_AHB2ENR_HASHEN_BIT) + #define RCC_AHB2ENR_CRYPEN (1U << RCC_AHB2ENR_CRYPEN_BIT) + #define RCC_AHB2ENR_DCMIEN (1U << RCC_AHB2ENR_DCMIEN_BIT) + + /* AHB3 */ + + #define RCC_AHB3ENR_FSMCEN_BIT 0 + + #define RCC_AHB3ENR_FSMCEN (1U << RCC_AHB3ENR_FSMCEN_BIT) + + /* APB1 */ + + #define RCC_APB1ENR_DACEN_BIT 29 + #define RCC_APB1ENR_PWREN_BIT 28 + #define RCC_APB1ENR_CAN2EN_BIT 26 + #define RCC_APB1ENR_CAN1EN_BIT 25 + #define RCC_APB1ENR_I2C3EN_BIT 23 + #define RCC_APB1ENR_I2C2EN_BIT 22 + #define RCC_APB1ENR_I2C1EN_BIT 21 + #define RCC_APB1ENR_UART5EN_BIT 20 + #define RCC_APB1ENR_UART4EN_BIT 19 + #define RCC_APB1ENR_USART3EN_BIT 18 + #define RCC_APB1ENR_USART2EN_BIT 17 + #define RCC_APB1ENR_SPI3EN_BIT 15 + #define RCC_APB1ENR_SPI2EN_BIT 14 + #define RCC_APB1ENR_WWDGEN_BIT 11 + #define RCC_APB1ENR_TIM14EN_BIT 8 + #define RCC_APB1ENR_TIM13EN_BIT 7 + #define RCC_APB1ENR_TIM12EN_BIT 6 + #define RCC_APB1ENR_TIM7EN_BIT 5 + #define RCC_APB1ENR_TIM6EN_BIT 4 + #define RCC_APB1ENR_TIM5EN_BIT 3 + #define RCC_APB1ENR_TIM4EN_BIT 2 + #define RCC_APB1ENR_TIM3EN_BIT 1 + #define RCC_APB1ENR_TIM2EN_BIT 0 + + #define RCC_APB1ENR_DACEN (1U << RCC_APB1ENR_DACEN_BIT) + #define RCC_APB1ENR_PWREN (1U << RCC_APB1ENR_PWREN_BIT) + #define RCC_APB1ENR_CAN2EN (1U << RCC_APB1ENR_CAN2EN_BIT) + #define RCC_APB1ENR_CAN1EN (1U << RCC_APB1ENR_CAN1EN_BIT) + #define RCC_APB1ENR_I2C3EN (1U << RCC_APB1ENR_I2C3EN_BIT) + #define RCC_APB1ENR_I2C2EN (1U << RCC_APB1ENR_I2C2EN_BIT) + #define RCC_APB1ENR_I2C1EN (1U << RCC_APB1ENR_I2C1EN_BIT) + #define RCC_APB1ENR_UART5EN (1U << RCC_APB1ENR_UART5EN_BIT) + #define RCC_APB1ENR_UART4EN (1U << RCC_APB1ENR_UART4EN_BIT) + #define RCC_APB1ENR_USART3EN (1U << RCC_APB1ENR_USART3EN_BIT) + #define RCC_APB1ENR_USART2EN (1U << RCC_APB1ENR_USART2EN_BIT) + #define RCC_APB1ENR_SPI3EN (1U << RCC_APB1ENR_SPI3EN_BIT) + #define RCC_APB1ENR_SPI2EN (1U << RCC_APB1ENR_SPI2EN_BIT) + #define RCC_APB1ENR_WWDGEN (1U << RCC_APB1ENR_WWDGEN_BIT) + #define RCC_APB1ENR_TIM14EN (1U << RCC_APB1ENR_TIM14EN_BIT) + #define RCC_APB1ENR_TIM13EN (1U << RCC_APB1ENR_TIM13EN_BIT) + #define RCC_APB1ENR_TIM12EN (1U << RCC_APB1ENR_TIM12EN_BIT) + #define RCC_APB1ENR_TIM7EN (1U << RCC_APB1ENR_TIM7EN_BIT) + #define RCC_APB1ENR_TIM6EN (1U << RCC_APB1ENR_TIM6EN_BIT) + #define RCC_APB1ENR_TIM5EN (1U << RCC_APB1ENR_TIM5EN_BIT) + #define RCC_APB1ENR_TIM4EN (1U << RCC_APB1ENR_TIM4EN_BIT) + #define RCC_APB1ENR_TIM3EN (1U << RCC_APB1ENR_TIM3EN_BIT) + #define RCC_APB1ENR_TIM2EN (1U << RCC_APB1ENR_TIM2EN_BIT) + + /* APB2 */ + + #define RCC_APB2ENR_TIM11EN_BIT 18 + #define RCC_APB2ENR_TIM10EN_BIT 17 + #define RCC_APB2ENR_TIM9EN_BIT 16 + #define RCC_APB2ENR_SYSCFGEN_BIT 14 + #define RCC_APB2ENR_SPI1EN_BIT 12 + #define RCC_APB2ENR_SDIOEN_BIT 11 + #define RCC_APB2ENR_ADC3EN_BIT 10 + #define RCC_APB2ENR_ADC2EN_BIT 9 + #define RCC_APB2ENR_ADC1EN_BIT 8 + #define RCC_APB2ENR_USART6EN_BIT 5 + #define RCC_APB2ENR_USART1EN_BIT 4 + #define RCC_APB2ENR_TIM8EN_BIT 1 + #define RCC_APB2ENR_TIM1EN_BIT 0 + + #define RCC_APB2ENR_TIM11EN (1U << RCC_APB2ENR_TIM11EN_BIT) + #define RCC_APB2ENR_TIM10EN (1U << RCC_APB2ENR_TIM10EN_BIT) + #define RCC_APB2ENR_TIM9EN (1U << RCC_APB2ENR_TIM9EN_BIT) + #define RCC_APB2ENR_SYSCFGEN (1U << RCC_APB2ENR_SYSCFGEN_BIT) + #define RCC_APB2ENR_SPI1EN (1U << RCC_APB2ENR_SPI1EN_BIT) + #define RCC_APB2ENR_SDIOEN (1U << RCC_APB2ENR_SDIOEN_BIT) + #define RCC_APB2ENR_ADC3EN (1U << RCC_APB2ENR_ADC3EN_BIT) + #define RCC_APB2ENR_ADC2EN (1U << RCC_APB2ENR_ADC2EN_BIT) + #define RCC_APB2ENR_ADC1EN (1U << RCC_APB2ENR_ADC1EN_BIT) + #define RCC_APB2ENR_USART6EN (1U << RCC_APB2ENR_USART6EN_BIT) + #define RCC_APB2ENR_USART1EN (1U << RCC_APB2ENR_USART1EN_BIT) + #define RCC_APB2ENR_TIM8EN (1U << RCC_APB2ENR_TIM8EN_BIT) + #define RCC_APB2ENR_TIM1EN (1U << RCC_APB2ENR_TIM1EN_BIT) + +Peripheral clock enable in low power mode registers ++++++++++++++++++++++++++++++++++++++++++++++++++++ + +:: + + /* AHB1 */ + + #define RCC_AHB1LPENR_OTGHSULPILPEN_BIT 30 + #define RCC_AHB1LPENR_OTGHSLPEN_BIT 29 + #define RCC_AHB1LPENR_ETHMACPTPLPEN_BIT 28 + #define RCC_AHB1LPENR_ETHMACRXLPEN_BIT 27 + #define RCC_AHB1LPENR_ETHMACTXLPEN_BIT 26 + #define RCC_AHB1LPENR_ETHMACLPEN_BIT 25 + #define RCC_AHB1LPENR_DMA2LPEN_BIT 22 + #define RCC_AHB1LPENR_DMA1LPEN_BIT 21 + #define RCC_AHB1LPENR_BKPSRAMLPEN_BIT 18 + #define RCC_AHB1LPENR_SRAM2LPEN_BIT 17 + #define RCC_AHB1LPENR_SRAM1LPEN_BIT 16 + #define RCC_AHB1LPENR_FLITFLPEN_BIT 15 + #define RCC_AHB1LPENR_CRCLPEN_BIT 12 + #define RCC_AHB1LPENR_GPIOILPEN_BIT 8 + #define RCC_AHB1LPENR_GPIOGLPEN_BIT 6 + #define RCC_AHB1LPENR_GPIOFLPEN_BIT 5 + #define RCC_AHB1LPENR_GPIOELPEN_BIT 4 + #define RCC_AHB1LPENR_GPIODLPEN_BIT 3 + #define RCC_AHB1LPENR_GPIOCLPEN_BIT 2 + #define RCC_AHB1LPENR_GPIOBLPEN_BIT 1 + #define RCC_AHB1LPENR_GPIOALPEN_BIT 0 + + #define RCC_AHB1LPENR_OTGHSULPILPEN (1U << RCC_AHB1LPENR_OTGHSULPILPEN_BIT) + #define RCC_AHB1LPENR_OTGHSLPEN (1U << RCC_AHB1LPENR_OTGHSLPEN_BIT) + #define RCC_AHB1LPENR_ETHMACPTPLPEN (1U << RCC_AHB1LPENR_ETHMACPTPLPEN_BIT) + #define RCC_AHB1LPENR_ETHMACRXLPEN (1U << RCC_AHB1LPENR_ETHMACRXLPEN_BIT) + #define RCC_AHB1LPENR_ETHMACTXLPEN (1U << RCC_AHB1LPENR_ETHMACTXLPEN_BIT) + #define RCC_AHB1LPENR_ETHMACLPEN (1U << RCC_AHB1LPENR_ETHMACLPEN_BIT) + #define RCC_AHB1LPENR_DMA2LPEN (1U << RCC_AHB1LPENR_DMA2LPEN_BIT) + #define RCC_AHB1LPENR_DMA1LPEN (1U << RCC_AHB1LPENR_DMA1LPEN_BIT) + #define RCC_AHB1LPENR_BKPSRAMLPEN (1U << RCC_AHB1LPENR_BKPSRAMLPEN_BIT) + #define RCC_AHB1LPENR_SRAM2LPEN (1U << RCC_AHB1LPENR_SRAM2LPEN_BIT) + #define RCC_AHB1LPENR_SRAM1LPEN (1U << RCC_AHB1LPENR_SRAM1LPEN_BIT) + #define RCC_AHB1LPENR_FLITFLPEN (1U << RCC_AHB1LPENR_FLITFLPEN_BIT) + #define RCC_AHB1LPENR_CRCLPEN (1U << RCC_AHB1LPENR_CRCLPEN_BIT) + #define RCC_AHB1LPENR_GPIOILPEN (1U << RCC_AHB1LPENR_GPIOILPEN_BIT) + #define RCC_AHB1LPENR_GPIOGLPEN (1U << RCC_AHB1LPENR_GPIOGLPEN_BIT) + #define RCC_AHB1LPENR_GPIOFLPEN (1U << RCC_AHB1LPENR_GPIOFLPEN_BIT) + #define RCC_AHB1LPENR_GPIOELPEN (1U << RCC_AHB1LPENR_GPIOELPEN_BIT) + #define RCC_AHB1LPENR_GPIODLPEN (1U << RCC_AHB1LPENR_GPIODLPEN_BIT) + #define RCC_AHB1LPENR_GPIOCLPEN (1U << RCC_AHB1LPENR_GPIOCLPEN_BIT) + #define RCC_AHB1LPENR_GPIOBLPEN (1U << RCC_AHB1LPENR_GPIOBLPEN_BIT) + #define RCC_AHB1LPENR_GPIOALPEN (1U << RCC_AHB1LPENR_GPIOALPEN_BIT) + + /* AHB2 */ + + #define RCC_AHB2LPENR_OTGFSLPEN_BIT 7 + #define RCC_AHB2LPENR_RNGLPEN_BIT 6 + #define RCC_AHB2LPENR_HASHLPEN_BIT 5 + #define RCC_AHB2LPENR_CRYPLPEN_BIT 4 + #define RCC_AHB2LPENR_DCMILPEN_BIT 0 + + #define RCC_AHB2LPENR_OTGFSLPEN (1U << RCC_AHB2LPENR_OTGFSLPEN_BIT) + #define RCC_AHB2LPENR_RNGLPEN (1U << RCC_AHB2LPENR_RNGLPEN_BIT) + #define RCC_AHB2LPENR_HASHLPEN (1U << RCC_AHB2LPENR_HASHLPEN_BIT) + #define RCC_AHB2LPENR_CRYPLPEN (1U << RCC_AHB2LPENR_CRYPLPEN_BIT) + #define RCC_AHB2LPENR_DCMILPEN (1U << RCC_AHB2LPENR_DCMILPEN_BIT) + + /* AHB3 */ + + #define RCC_AHB3LPENR_FSMCLPEN_BIT 0 + + #define RCC_AHB3LPENR_FSMCLPEN (1U << RCC_AHB3LPENR_FSMCLPEN_BIT) + + /* APB1 */ + + #define RCC_APB1LPENR_DACLPEN_BIT 29 + #define RCC_APB1LPENR_PWRLPEN_BIT 28 + #define RCC_APB1LPENR_CAN2LPEN_BIT 26 + #define RCC_APB1LPENR_CAN1LPEN_BIT 25 + #define RCC_APB1LPENR_I2C3LPEN_BIT 23 + #define RCC_APB1LPENR_I2C2LPEN_BIT 22 + #define RCC_APB1LPENR_I2C1LPEN_BIT 21 + #define RCC_APB1LPENR_UART5LPEN_BIT 20 + #define RCC_APB1LPENR_UART4LPEN_BIT 19 + #define RCC_APB1LPENR_USART3LPEN_BIT 18 + #define RCC_APB1LPENR_USART2LPEN_BIT 17 + #define RCC_APB1LPENR_SPI3LPEN_BIT 15 + #define RCC_APB1LPENR_SPI2LPEN_BIT 14 + #define RCC_APB1LPENR_WWDGLPEN_BIT 11 + #define RCC_APB1LPENR_TIM14LPEN_BIT 8 + #define RCC_APB1LPENR_TIM13LPEN_BIT 7 + #define RCC_APB1LPENR_TIM12LPEN_BIT 6 + #define RCC_APB1LPENR_TIM7LPEN_BIT 5 + #define RCC_APB1LPENR_TIM6LPEN_BIT 4 + #define RCC_APB1LPENR_TIM5LPEN_BIT 3 + #define RCC_APB1LPENR_TIM4LPEN_BIT 2 + #define RCC_APB1LPENR_TIM3LPEN_BIT 1 + #define RCC_APB1LPENR_TIM2LPEN_BIT 0 + + #define RCC_APB1LPENR_DACLPEN (1U << RCC_APB1LPENR_DACLPEN_BIT) + #define RCC_APB1LPENR_PWRLPEN (1U << RCC_APB1LPENR_PWRLPEN_BIT) + #define RCC_APB1LPENR_CAN2LPEN (1U << RCC_APB1LPENR_CAN2LPEN_BIT) + #define RCC_APB1LPENR_CAN1LPEN (1U << RCC_APB1LPENR_CAN1LPEN_BIT) + #define RCC_APB1LPENR_I2C3LPEN (1U << RCC_APB1LPENR_I2C3LPEN_BIT) + #define RCC_APB1LPENR_I2C2LPEN (1U << RCC_APB1LPENR_I2C2LPEN_BIT) + #define RCC_APB1LPENR_I2C1LPEN (1U << RCC_APB1LPENR_I2C1LPEN_BIT) + #define RCC_APB1LPENR_UART5LPEN (1U << RCC_APB1LPENR_UART5LPEN_BIT) + #define RCC_APB1LPENR_UART4LPEN (1U << RCC_APB1LPENR_UART4LPEN_BIT) + #define RCC_APB1LPENR_USART3LPEN (1U << RCC_APB1LPENR_USART3LPEN_BIT) + #define RCC_APB1LPENR_USART2LPEN (1U << RCC_APB1LPENR_USART2LPEN_BIT) + #define RCC_APB1LPENR_SPI3LPEN (1U << RCC_APB1LPENR_SPI3LPEN_BIT) + #define RCC_APB1LPENR_SPI2LPEN (1U << RCC_APB1LPENR_SPI2LPEN_BIT) + #define RCC_APB1LPENR_WWDGLPEN (1U << RCC_APB1LPENR_WWDGLPEN_BIT) + #define RCC_APB1LPENR_TIM14LPEN (1U << RCC_APB1LPENR_TIM14LPEN_BIT) + #define RCC_APB1LPENR_TIM13LPEN (1U << RCC_APB1LPENR_TIM13LPEN_BIT) + #define RCC_APB1LPENR_TIM12LPEN (1U << RCC_APB1LPENR_TIM12LPEN_BIT) + #define RCC_APB1LPENR_TIM7LPEN (1U << RCC_APB1LPENR_TIM7LPEN_BIT) + #define RCC_APB1LPENR_TIM6LPEN (1U << RCC_APB1LPENR_TIM6LPEN_BIT) + #define RCC_APB1LPENR_TIM5LPEN (1U << RCC_APB1LPENR_TIM5LPEN_BIT) + #define RCC_APB1LPENR_TIM4LPEN (1U << RCC_APB1LPENR_TIM4LPEN_BIT) + #define RCC_APB1LPENR_TIM3LPEN (1U << RCC_APB1LPENR_TIM3LPEN_BIT) + #define RCC_APB1LPENR_TIM2LPEN (1U << RCC_APB1LPENR_TIM2LPEN_BIT) + + /* APB2 */ + + #define RCC_APB2LPENR_TIM11LPEN_BIT 18 + #define RCC_APB2LPENR_TIM10LPEN_BIT 17 + #define RCC_APB2LPENR_TIM9LPEN_BIT 16 + #define RCC_APB2LPENR_SYSCFGLPEN_BIT 14 + #define RCC_APB2LPENR_SPI1LPEN_BIT 12 + #define RCC_APB2LPENR_SDIOLPEN_BIT 11 + #define RCC_APB2LPENR_ADC3LPEN_BIT 10 + #define RCC_APB2LPENR_ADC2LPEN_BIT 9 + #define RCC_APB2LPENR_ADC1LPEN_BIT 8 + #define RCC_APB2LPENR_USART6LPEN_BIT 5 + #define RCC_APB2LPENR_USART1LPEN_BIT 4 + #define RCC_APB2LPENR_TIM8LPEN_BIT 1 + #define RCC_APB2LPENR_TIM1LPEN_BIT 0 + + #define RCC_APB2LPENR_TIM11LPEN (1U << RCC_APB2LPENR_TIM11LPEN_BIT) + #define RCC_APB2LPENR_TIM10LPEN (1U << RCC_APB2LPENR_TIM10LPEN_BIT) + #define RCC_APB2LPENR_TIM9LPEN (1U << RCC_APB2LPENR_TIM9LPEN_BIT) + #define RCC_APB2LPENR_SYSCFGLPEN (1U << RCC_APB2LPENR_SYSCFGLPEN_BIT) + #define RCC_APB2LPENR_SPI1LPEN (1U << RCC_APB2LPENR_SPI1LPEN_BIT) + #define RCC_APB2LPENR_SDIOLPEN (1U << RCC_APB2LPENR_SDIOLPEN_BIT) + #define RCC_APB2LPENR_ADC3LPEN (1U << RCC_APB2LPENR_ADC3LPEN_BIT) + #define RCC_APB2LPENR_ADC2LPEN (1U << RCC_APB2LPENR_ADC2LPEN_BIT) + #define RCC_APB2LPENR_ADC1LPEN (1U << RCC_APB2LPENR_ADC1LPEN_BIT) + #define RCC_APB2LPENR_USART6LPEN (1U << RCC_APB2LPENR_USART6LPEN_BIT) + #define RCC_APB2LPENR_USART1LPEN (1U << RCC_APB2LPENR_USART1LPEN_BIT) + #define RCC_APB2LPENR_TIM8LPEN (1U << RCC_APB2LPENR_TIM8LPEN_BIT) + #define RCC_APB2LPENR_TIM1LPEN (1U << RCC_APB2LPENR_TIM1LPEN_BIT) + +Backup domain control register +++++++++++++++++++++++++++++++ + +:: + + #define RCC_BDCR_BDRST_BIT 16 + #define RCC_BDCR_RTCEN_BIT 15 + #define RCC_BDCR_LSEBYP_BIT 2 + #define RCC_BDCR_LSERDY_BIT 1 + #define RCC_BDCR_LSEON_BIT 0 + + #define RCC_BDCR_BDRST (1U << RCC_BDCR_BDRST_BIT) + #define RCC_BDCR_RTCEN (1U << RCC_BDCR_RTCEN_BIT) + #define RCC_BDCR_RTCSEL (0x3 << 8) + #define RCC_BDCR_RTCSEL_NOCLOCK (0x0 << 8) + #define RCC_BDCR_RTCSEL_LSE (0x1 << 8) + #define RCC_BDCR_RTCSEL_LSI (0x2 << 8) + #define RCC_BDCR_RTCSEL_HSE_DIV (0x3 << 8) + #define RCC_BDCR_LSEBYP (1U << RCC_BDCR_LSEBYP_BIT) + #define RCC_BDCR_LSERDY (1U << RCC_BDCR_LSERDY_BIT) + #define RCC_BDCR_LSEON (1U << RCC_BDCR_LSEON_BIT) + +Clock control and status register ++++++++++++++++++++++++++++++++++ + +:: + + #define RCC_CSR_LPWRRSTF_BIT 31 + #define RCC_CSR_WWDGRSTF_BIT 30 + #define RCC_CSR_IWDGRSTF_BIT 29 + #define RCC_CSR_SFTRSTF_BIT 28 + #define RCC_CSR_PORRSTF_BIT 27 + #define RCC_CSR_PINRSTF_BIT 26 + #define RCC_CSR_BORRSTF_BIT 25 + #define RCC_CSR_RMVF_BIT 24 + #define RCC_CSR_LSIRDY_BIT 1 + #define RCC_CSR_LSION_BIT 0 + + #define RCC_CSR_LPWRRSTF (1U << RCC_CSR_LPWRRSTF_BIT) + #define RCC_CSR_WWDGRSTF (1U << RCC_CSR_WWDGRSTF_BIT) + #define RCC_CSR_IWDGRSTF (1U << RCC_CSR_IWDGRSTF_BIT) + #define RCC_CSR_SFTRSTF (1U << RCC_CSR_SFTRSTF_BIT) + #define RCC_CSR_PORRSTF (1U << RCC_CSR_PORRSTF_BIT) + #define RCC_CSR_PINRSTF (1U << RCC_CSR_PINRSTF_BIT) + #define RCC_CSR_BORRSTF (1U << RCC_CSR_BORRSTF_BIT) + #define RCC_CSR_RMVF (1U << RCC_CSR_RMVF_BIT) + #define RCC_CSR_LSIRDY (1U << RCC_CSR_LSIRDY_BIT) + #define RCC_CSR_LSION (1U << RCC_CSR_LSION_BIT) + +Spread spectrum clock generation register ++++++++++++++++++++++++++++++++++++++++++ + +:: + + #define RCC_SSCGR_SSCGEN_BIT 31 + #define RCC_SSCGR_SPREADSEL_BIT 30 + + #define RCC_SSCGR_SSCGEN (1U << RCC_SSCGR_SSCGEN_BIT) + #define RCC_SSCGR_SPREADSEL (1U << RCC_SSCGR_SPREADSEL_BIT) + #define RCC_SSCGR_SPREADSEL_CENTER (0x0 << RCC_SSCGR_SPREADSEL_BIT) + #define RCC_SSCGR_SPREADSEL_DOWN (0x1 << RCC_SSCGR_SPREADSEL_BIT) + #define RCC_SSCGR_INCSTEP (0xFFF << 16) + #define RCC_SSCGR_MODPER 0xFFFF + +PLLI2S configuration register ++++++++++++++++++++++++++++++ + +:: + + #define RCC_PLLI2SCFGR_PLLI2SR (0x7 << 28) + #define RCC_PLLI2SCFGR_PLLI2SN (0x1FF << 6) + diff --git a/docs/source/libmaple/api/rcc.rst b/docs/source/libmaple/api/rcc.rst new file mode 100644 index 0000000..ce58ec8 --- /dev/null +++ b/docs/source/libmaple/api/rcc.rst @@ -0,0 +1,360 @@ +.. highlight:: c +.. _libmaple-rcc: + +``<libmaple/rcc.h>`` +==================== + +Reset and Clock Control (RCC) support. + +The RCC is responsible for managing the MCU's various clocks. This +includes the core clock SYSCLK, which determines the CPU clock +frequency, as well as the clock lines that drive peripherals. + +Because of this, the available RCC functionality varies by target. +There are a :ref:`variety of abstractions <libmaple-rcc-core-types>` +in place to make managing this more convenient. + +.. contents:: Contents + :local: + :depth: 2 + +.. _libmaple-rcc-core-types: + +Core Types +---------- + +The core abstractions in place are +:ref:`rcc_clk_id <libmaple-rcc-rcc_clk_id>`, +:ref:`rcc_clk <libmaple-rcc-rcc_clk>`, +:ref:`rcc_sysclk_src <libmaple-rcc-rcc_sysclk_src>`, +:ref:`rcc_clk_domain <libmaple-rcc-rcc_clk_domain>`, and +:ref:`rcc_prescaler <libmaple-rcc-rcc_prescaler>`. + +.. _libmaple-rcc-rcc_clk_id: + +Peripheral Identifiers: ``rcc_clk_id`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``rcc_clk_id`` is an enum used to identify peripherals. The RCC +back-ends use them to look up a peripheral's bus and clock line, but +they are also generally useful as unique identifiers for each +peripheral. You can manage peripherals using their ``rcc_clk_id``\ s +with :ref:`these functions <libmaple-rcc-clk-id-funcs>`. + +Peripherals which are common across targets have the same token +(though not necessarily the same value) for their ``rcc_clk_id`` +across different targets. For example, the ``rcc_clk_id`` for the ADC1 +peripheral is always ``RCC_ADC1`` regardless of the target. +Additionally, as explained in :ref:`libmaple-overview-devices`, each +peripheral device type struct contains the ``rcc_clk_id`` for that +peripheral in a ``clk_id`` field. + +The available ``rcc_clk_id``\ s on each supported target series are as +follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_clk_id + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_clk_id + +.. _libmaple-rcc-rcc_sysclk_src: + +System Clock (SYSCLK) Sources: ``rcc_sysclk_src`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SYSCLK is the core system clock. It determines the CPU clock rate, and +it's the base clock which is used to drive (most of) the peripherals +on the STM32. ``rcc_sysclk_src`` is an enum for the possible SYSCLK +sources. Switch the SYSCLK source with :ref:`rcc_switch_sysclk() +<libmaple-rcc-rcc_switch_sysclk>`. + +.. doxygenenum:: rcc_sysclk_src + +As a special case, you can configure the PLL with a call to +:ref:`rcc_configure_pll() <libmaple-rcc-rcc_configure_pll>`. + +.. _libmaple-rcc-rcc_clk: + +System and Secondary Clock Sources: ``rcc_clk`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``rcc_clk`` type gives available system and secondary clock +sources (e.g. HSI, HSE, LSE). As with :ref:`rcc_clk_id +<libmaple-rcc-rcc_clk_id>`, clock sources which are common across +targets have the same token, but not necessarily the same value, for +their ``rcc_clk`` on each target. A variety of :ref:`clock management +functions <libmaple-rcc-clk-funcs>` are available. + +Note that the inclusion of secondary clock sources, like LSI and LSE, +makes ``rcc_clk`` different from the SYSCLK sources, which are managed +using :ref:`rcc_sysclk_src <libmaple-rcc-rcc_sysclk_src>`. + +The available ``rcc_clk``\ s for each supported target series are as +follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_clk + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_clk + +.. _libmaple-rcc-rcc_clk_domain: + +Clock Domains: ``rcc_clk_domain`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These specify the available clock domains. For example, each AHB and +APB is a clock domain. + +This type mostly exists to enable asking devices what bus they're on, +which, given knowledge of your system's clock configuration, can be +useful when making decisions about prescalers, etc. + +Given an :ref:`rcc_clk_id <libmaple-rcc-rcc_clk_id>`, you can get the +peripheral's clock domain with :ref:`rcc_dev_clk() +<libmaple-rcc-rcc_dev_clk>`. Clock domains that are common across +series have the same token (but not necessarily the same value) for +their corresponding ``rcc_clk_domain``. + +The available ``rcc_clk_domain``\ s for each supported target series +are as follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_clk_domain + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_clk_domain + +.. _libmaple-rcc-rcc_prescaler: + +Prescalers: ``rcc_prescaler`` and Friends +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Available prescalers are managed via the ``rcc_prescaler`` type, the +``rcc_set_prescaler()`` function, and a variety of related prescaler +divider types. See :ref:`libmaple-rcc-prescalers` for more +information and usage notes. + +Functions +--------- + +.. _libmaple-rcc-sysclk-funcs: +.. _libmaple-rcc-rcc_switch_sysclk: + +SYSCLK Management +~~~~~~~~~~~~~~~~~ + +Change the SYSCLK source with ``rcc_switch_sysclk()``. + +.. doxygenfunction:: rcc_switch_sysclk + +.. _libmaple-rcc-rcc_configure_pll: + +PLL Configuration +~~~~~~~~~~~~~~~~~ + +You can configure the PLL with ``rcc_configure_pll()``. This takes an +``rcc_pll_cfg`` struct as its argument. Though the definition of +``rcc_pll_cfg`` is common across series, its contents are entirely +target-dependent. + +.. doxygenstruct:: rcc_pll_cfg +.. _rcc-rcc_configure_pll: +.. doxygenfunction:: rcc_configure_pll + +The fields in an ``rcc_pll_cfg`` on each target are as follows. + +rcc_pll_cfg on STM32F1 Targets +++++++++++++++++++++++++++++++ + +The ``pllsrc`` field is chosen from the following. + +.. doxygenenum:: stm32f1::rcc_pllsrc + +.. FIXME [0.0.13] We've got plans to redo this; make sure you watch +.. libmaple for changes here. + +The ``data`` field must point to a ``struct stm32f1_rcc_pll_data``. +This just contains an ``rcc_pll_multiplier``. + +.. doxygenenum:: stm32f1::rcc_pll_multiplier + +.. doxygenstruct:: stm32f1::stm32f1_rcc_pll_data + +rcc_pll_cfg on STM32F2 Targets +++++++++++++++++++++++++++++++ + +The ``pllsrc`` field is chosen from the following. + +.. doxygenenum:: stm32f2::rcc_pllsrc + +The ``data`` field must point to a ``struct stm32f2_rcc_pll_data``. + +.. doxygenstruct:: stm32f2::stm32f2_rcc_pll_data + +.. _libmaple-rcc-clk-funcs: + +System and Secondary Clock Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These functions are useful for managing clocks via their :ref:`rcc_clk +<libmaple-rcc-rcc_clk>`. + +.. doxygenfunction:: rcc_turn_on_clk +.. doxygenfunction:: rcc_turn_off_clk +.. doxygenfunction:: rcc_is_clk_on +.. doxygenfunction:: rcc_is_clk_ready + +.. _libmaple-rcc-clk-id-funcs: + +Peripheral Management +~~~~~~~~~~~~~~~~~~~~~ + +These functions are useful for managing peripherals via their +:ref:`rcc_clk_id <libmaple-rcc-rcc_clk_id>`. + +.. _libmaple-rcc-rcc_clk_enable: +.. doxygenfunction:: rcc_clk_enable +.. doxygenfunction:: rcc_reset_dev +.. _libmaple-rcc-rcc_dev_clk: +.. doxygenfunction:: rcc_dev_clk + +.. _libmaple-rcc-prescalers: + +Prescaler Management +~~~~~~~~~~~~~~~~~~~~ + +All clock prescalers managed by RCC can be controlled with a single +function, ``rcc_set_prescaler()``. + +.. doxygenfunction:: rcc_set_prescaler + +The arguments to ``rcc_set_prescaler()`` are target-dependent, but +follow a common pattern: + +- The first argument is the prescaler to set, so there's one for each + peripheral clock domain, etc. These have names like + ``RCC_PRESCALER_FOO``, e.g. ``RCC_PRESCALER_APB1``. Choose the + prescaler from the ``rcc_prescaler``\ s on your target (see below). + +- The second argument is the actual clock divider to use; it's chosen + based on the first argument. The dividers for ``RCC_PRESCALER_FOO`` + are given by the type ``rcc_foo_divider``, and have values like + ``RCC_FOO_xxx_DIV_y``. This means that the foo clock will be the + ``xxx`` clock divided by ``y``. + +For example, calling ``rcc_set_prescaler(RCC_PRESCALER_APB1, +RCC_APB1_HCLK_DIV_1)`` would set the APB1 clock to HCLK divided by 1. + +Prescalers which are common across targets have the same token, though +not necessarily the same value, for their ``rcc_prescaler`` (for +example, ``RCC_PRESCALER_APB1`` is available on both STM32F1 and +STM32F2 targets). The available prescalers and dividers on each +supported target series are as follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_prescaler +.. doxygenenum:: stm32f1::rcc_adc_divider +.. doxygenenum:: stm32f1::rcc_apb1_divider +.. doxygenenum:: stm32f1::rcc_apb2_divider +.. doxygenenum:: stm32f1::rcc_ahb_divider + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_prescaler +.. doxygenenum:: stm32f2::rcc_mco2_divider +.. doxygenenum:: stm32f2::rcc_mco1_divider +.. doxygenenum:: stm32f2::rcc_rtc_divider +.. doxygenenum:: stm32f2::rcc_apb2_divider +.. doxygenenum:: stm32f2::rcc_apb1_divider +.. doxygenenum:: stm32f2::rcc_ahb_divider + +Register Maps +------------- + +These vary by target. The base pointer is always ``RCC_BASE``. + +.. doxygendefine:: RCC_BASE + +STM32F1 Targets +~~~~~~~~~~~~~~~ + +.. doxygenstruct:: stm32f1::rcc_reg_map + +STM32F2 Targets +~~~~~~~~~~~~~~~ + +.. doxygenstruct:: stm32f2::rcc_reg_map + +Register Bit Definitions +------------------------ + +These are given as source code. Available register bit definitions +vary by target. + +.. We need this include to avoid crashing Emacs's ReST parser. Yuck. + +.. include:: rcc-reg-bits.txt + +Deprecated Functionality +------------------------ + +.. _rcc-rcc_clk_init: +.. doxygenfunction:: stm32f1::rcc_clk_init + +To replace a call to ``rcc_clk_init()`` in order to set SYSCLK to PLL +driven by an external oscillator, you can use something like this, +which is portable except for the initialization of ``your_pll_cfg``:: + + /* You need to make this point to something valid for your target; see + * the documentation for rcc_configure_pll() for more details. */ + extern rcc_pll_cfg *your_pll_cfg; + + void pll_reconfigure() { + /* Turn on HSI using rcc_turn_on_clk() and wait for it to + * become ready by busy-waiting on rcc_is_clk_ready(). + * + * Switch to HSI to ensure we're not using the PLL while we + * reconfigure it. */ + rcc_turn_on_clk(RCC_CLK_HSI); + while (!rcc_is_clk_ready(RCC_CLK_HSI)) + ; + rcc_switch_sysclk(RCC_CLKSRC_HSI); + + /* Turn off HSE and the PLL, or we can't reconfigure it. */ + rcc_turn_off_clk(RCC_CLK_PLL); + rcc_turn_off_clk(RCC_CLK_HSE); + + /* Reconfigure the PLL. You can also perform any other + * prescaler management here. */ + rcc_configure_pll(your_pll_cfg); + + /* Turn on RCC_CLK_HSE. */ + rcc_turn_on_clk(RCC_CLK_HSE); + while (!rcc_is_clk_ready(RCC_CLK_HSE)) + ; + + /* Turn on RCC_CLK_PLL. */ + rcc_turn_on_clk(RCC_CLK_PLL); + while (!rcc_is_clk_ready(RCC_CLK_PLL)) + ; + + /* Finally, switch to the PLL. */ + rcc_switch_sysclk(RCC_CLKSRC_PLL); + } diff --git a/docs/source/libmaple/api/ring_buffer.rst b/docs/source/libmaple/api/ring_buffer.rst new file mode 100644 index 0000000..ef082dd --- /dev/null +++ b/docs/source/libmaple/api/ring_buffer.rst @@ -0,0 +1,27 @@ +.. highlight:: c +.. _libmaple-ring_buffer: + +``<libmaple/ring_buffer.h>`` +============================ + +Simple circular byte buffer. This implementation is not thread-safe. +In particular, none of these functions is guaranteed to be re-entrant. + +Ring Buffer Type +---------------- + +.. 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/docs/source/libmaple/api/scb.rst b/docs/source/libmaple/api/scb.rst new file mode 100644 index 0000000..96d464f --- /dev/null +++ b/docs/source/libmaple/api/scb.rst @@ -0,0 +1,156 @@ +.. highlight:: c +.. _libmaple-scb: + +``<libmaple/scb.h>`` +==================== + +.. TODO [0.0.13] check for any F2 modifications + +System Control Block (SCB) support. This is currently limited to a +register map and bit definitions. + +.. warning:: + + At time of writing, ST PM0056 (which specifies the system control + block on STM32F1) appears to be buggy (some registers required or + specified as implementation-defined by ARM are not mentioned). + This file is the result of combining material from ARM and ST, and + is subject to change. See the source code for more details. + + If you notice a problem or have any other input on this, please + `contact`_ us! + +.. contents:: Contents + :local: + +Register Maps +------------- + +The SCB has the following register map. Its base pointer is ``SCB_BASE``. + +.. doxygenstruct:: scb_reg_map +.. doxygendefine:: SCB_BASE + +Register Bit Definitions +------------------------ + +These are given as source code. + +:: + + /* No SCB_REG_FIELD_BIT macros as the relevant addresses are not in a + * bit-band region. */ + + /* CPUID base register (SCB_CPUID) */ + + #define SCB_CPUID_IMPLEMENTER (0xFF << 24) + #define SCB_CPUID_VARIANT (0xF << 20) + #define SCB_CPUID_CONSTANT (0xF << 16) + #define SCB_CPUID_PARTNO (0xFFF << 4) + #define SCB_CPUID_REVISION 0xF + + /* Interrupt control state register (SCB_ICSR) */ + + #define SCB_ICSR_NMIPENDSET (1U << 31) + #define SCB_ICSR_PENDSVSET (1U << 28) + #define SCB_ICSR_PENDSVCLR (1U << 27) + #define SCB_ICSR_PENDSTSET (1U << 26) + #define SCB_ICSR_PENDSTCLR (1U << 25) + #define SCB_ICSR_ISRPENDING (1U << 22) + #define SCB_ICSR_VECTPENDING (0x3FF << 12) + #define SCB_ICSR_RETOBASE (1U << 11) + #define SCB_ICSR_VECTACTIVE 0xFF + + /* Vector table offset register (SCB_VTOR) */ + + #define SCB_VTOR_TBLOFF (0x1FFFFF << 9) + + /* Application interrupt and reset control register (SCB_AIRCR) */ + + #define SCB_AIRCR_VECTKEYSTAT (0x5FA << 16) + #define SCB_AIRCR_VECTKEY (0x5FA << 16) + #define SCB_AIRCR_ENDIANNESS (1U << 15) + #define SCB_AIRCR_PRIGROUP (0x3 << 8) + #define SCB_AIRCR_SYSRESETREQ (1U << 2) + #define SCB_AIRCR_VECTCLRACTIVE (1U << 1) + #define SCB_AIRCR_VECTRESET (1U << 0) + + /* System control register (SCB_SCR) */ + + #define SCB_SCR_SEVONPEND (1U << 4) + #define SCB_SCR_SLEEPDEEP (1U << 2) + #define SCB_SCR_SLEEPONEXIT (1U << 1) + + /* Configuration and Control Register (SCB_CCR) */ + + #define SCB_CCR_STKALIGN (1U << 9) + #define SCB_CCR_BFHFNMIGN (1U << 8) + #define SCB_CCR_DIV_0_TRP (1U << 4) + #define SCB_CCR_UNALIGN_TRP (1U << 3) + #define SCB_CCR_USERSETMPEND (1U << 1) + #define SCB_CCR_NONBASETHRDENA (1U << 0) + + /* System handler priority registers (SCB_SHPRx) */ + + #define SCB_SHPR1_PRI6 (0xFF << 16) + #define SCB_SHPR1_PRI5 (0xFF << 8) + #define SCB_SHPR1_PRI4 0xFF + + #define SCB_SHPR2_PRI11 (0xFF << 24) + + #define SCB_SHPR3_PRI15 (0xFF << 24) + #define SCB_SHPR3_PRI14 (0xFF << 16) + + /* System Handler Control and state register (SCB_SHCSR) */ + + #define SCB_SHCSR_USGFAULTENA (1U << 18) + #define SCB_SHCSR_BUSFAULTENA (1U << 17) + #define SCB_SHCSR_MEMFAULTENA (1U << 16) + #define SCB_SHCSR_SVCALLPENDED (1U << 15) + #define SCB_SHCSR_BUSFAULTPENDED (1U << 14) + #define SCB_SHCSR_MEMFAULTPENDED (1U << 13) + #define SCB_SHCSR_USGFAULTPENDED (1U << 12) + #define SCB_SHCSR_SYSTICKACT (1U << 11) + #define SCB_SHCSR_PENDSVACT (1U << 10) + #define SCB_SHCSR_MONITORACT (1U << 8) + #define SCB_SHCSR_SVCALLACT (1U << 7) + #define SCB_SHCSR_USGFAULTACT (1U << 3) + #define SCB_SHCSR_BUSFAULTACT (1U << 1) + #define SCB_SHCSR_MEMFAULTACT (1U << 0) + + /* Configurable fault status register (SCB_CFSR) */ + + #define SCB_CFSR_DIVBYZERO (1U << 25) + #define SCB_CFSR_UNALIGNED (1U << 24) + #define SCB_CFSR_NOCP (1U << 19) + #define SCB_CFSR_INVPC (1U << 18) + #define SCB_CFSR_INVSTATE (1U << 17) + #define SCB_CFSR_UNDEFINSTR (1U << 16) + #define SCB_CFSR_BFARVALID (1U << 15) + #define SCB_CFSR_STKERR (1U << 12) + #define SCB_CFSR_UNSTKERR (1U << 11) + #define SCB_CFSR_IMPRECISERR (1U << 10) + #define SCB_CFSR_PRECISERR (1U << 9) + #define SCB_CFSR_IBUSERR (1U << 8) + #define SCB_CFSR_MMARVALID (1U << 7) + #define SCB_CFSR_MSTKERR (1U << 4) + #define SCB_CFSR_MUNSTKERR (1U << 3) + #define SCB_CFSR_DACCVIOL (1U << 1) + #define SCB_CFSR_IACCVIOL (1U << 0) + + /* Hard Fault Status Register (SCB_HFSR) */ + + #define SCB_HFSR_DEBUG_VT (1U << 31) + #define SCB_CFSR_FORCED (1U << 30) + #define SCB_CFSR_VECTTBL (1U << 1) + + /* Debug Fault Status Register */ + + /* Not specified by PM0056, but required by ARM. The bit definitions + * here are based on the names given in the ARM v7-M ARM. */ + + #define SCB_DFSR_EXTERNAL (1U << 4) + #define SCB_DFSR_VCATCH (1U << 3) + #define SCB_DFSR_DWTTRAP (1U << 2) + #define SCB_DFSR_BKPT (1U << 1) + #define SCB_DFSR_HALTED (1U << 0) diff --git a/docs/source/libmaple/api/spi.rst b/docs/source/libmaple/api/spi.rst new file mode 100644 index 0000000..e72696b --- /dev/null +++ b/docs/source/libmaple/api/spi.rst @@ -0,0 +1,187 @@ +.. highlight:: c +.. _libmaple-spi: + +``spi.h`` +========= + +Serial Peripheral Interface (SPI) support. Currently, there is no I2S +support beyond register bit definitions. + +.. contents:: Contents + :local: + +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/docs/source/libmaple/api/stm32.rst b/docs/source/libmaple/api/stm32.rst new file mode 100644 index 0000000..335bda4 --- /dev/null +++ b/docs/source/libmaple/api/stm32.rst @@ -0,0 +1,121 @@ +.. highlight:: c +.. _libmaple-stm32: + +``<libmaple/stm32.h>`` +====================== + +STM32 chip header. This header supplies various series-specific and +chip-specific macros for the current build target. It's useful both +to abstract away hardware details (e.g. through use of +:ref:`STM32_NR_INTERRUPTS <libmaple-stm32-STM32_NR_INTERRUPTS>`) and +to decide what to do when you want something nonportable (e.g. by +checking :ref:`STM32_MCU_SERIES <libmaple-stm32-STM32_MCU_SERIES>`). + +.. contents:: Contents + :local: + +Determining the Target Series +----------------------------- + +The STM32 series (e.g. STM32F1, STM32F2, etc.) of the current target +can be inspected with ``STM32_MCU_SERIES``. + +.. _libmaple-stm32-STM32_MCU_SERIES: +.. doxygendefine:: STM32_MCU_SERIES + +Allowed values for ``STM32_MCU_SERIES`` are the following. This set is +expected to grow over time. + +.. doxygendefine:: STM32_SERIES_F1 +.. doxygendefine:: STM32_SERIES_F2 +.. doxygendefine:: STM32_SERIES_L1 +.. doxygendefine:: STM32_SERIES_F4 + +Series-Specific Characteristics +------------------------------- + +The macros in this section are only available on some STM32 series. + +STM32F1 +~~~~~~~ + +.. note:: These macros are only available when the current target is + an STM32F1 series MCU (i.e., when :ref:`STM32_MCU_SERIES + <libmaple-stm32-STM32_MCU_SERIES>` is ``STM32_SERIES_F1``). + +The STM32F1 series is further subdivided into :ref:`lines +<stm32-series-f1-lines>`. The line of the current target can be +inspected with ``STM32_F1_LINE``. + +.. doxygendefine:: STM32_F1_LINE + +There are five STM32F1 lines. The corresponding values +``STM32_F1_LINE`` can take are the following, though libmaple doesn't +currently support all of them. + +.. doxygendefine:: STM32_F1_LINE_VALUE +.. doxygendefine:: STM32_F1_LINE_ACCESS +.. doxygendefine:: STM32_F1_LINE_USB_ACCESS +.. doxygendefine:: STM32_F1_LINE_PERFORMANCE +.. doxygendefine:: STM32_F1_LINE_CONNECTIVITY + +MCU Feature Tests +----------------- + +The following defines can be used to determine if the target MCU has +a particular feature. + +.. _libmaple-stm32-STM32_HAVE_FSMC: +.. doxygendefine:: STM32_HAVE_FSMC +.. doxygendefine:: STM32_HAVE_USB + +MCU Characteristics +------------------- + +The following defines give salient characteristics of the target MCU. + +.. doxygendefine:: STM32_NR_GPIO_PORTS +.. _libmaple-stm32-STM32_NR_INTERRUPTS: +.. doxygendefine:: STM32_NR_INTERRUPTS +.. doxygendefine:: STM32_SRAM_END + +Clock Speeds +------------ + +The macros in this section are related to clock rates. As such, they +are really part of the configuration of the MCU, rather than inherent +characteristics of the MCU itself. For instance, it's possible to +change the PCLK1 and PCLK2 clock rates by reconfiguring the :ref:`RCC +<libmaple-rcc>`. libmaple proper never changes any clock rates, but it +does have APIs for doing so (such as :ref:`rcc_configure_pll() +<libmaple-rcc-rcc_configure_pll>`). Because of this, be careful when +using the macros in this section, as they assume that some values are +constant which in fact may be changed. + +The values these macros actually take are typically the maximum values +supported by the MCU. Since these are their actual values in practice +(at least in LeafLabs' current use cases, which have the chips running +as fast as possible), they're still considered useful. + +.. doxygendefine:: STM32_PCLK1 +.. doxygendefine:: STM32_PCLK2 + +The following macro, ``STM32_DELAY_US_MULT``, is a libmaple +implementation detail. It was included in this public API page in a +previous release by mistake, and is not deprecated, but using it in +your own code is a bad idea. + +.. doxygendefine:: STM32_DELAY_US_MULT + +Deprecated Macros +----------------- + +.. warning:: The macros in this section are deprecated, and are + available for backwards compatibility only. Do not use + them in new code. + +.. doxygendefine:: PCLK1 +.. doxygendefine:: PCLK2 +.. doxygendefine:: NR_INTERRUPTS +.. doxygendefine:: NR_GPIO_PORTS +.. doxygendefine:: DELAY_US_MULT diff --git a/docs/source/libmaple/api/systick.rst b/docs/source/libmaple/api/systick.rst new file mode 100644 index 0000000..45b6d63 --- /dev/null +++ b/docs/source/libmaple/api/systick.rst @@ -0,0 +1,62 @@ +.. highlight:: c + +.. _libmaple-systick: + +``systick.h`` +============= + +System timer (SysTick) support. + +.. contents:: Contents + :local: + +Types +----- + +.. doxygenstruct:: systick_reg_map + +Devices +------- + +None. + +Functions +--------- + +.. doxygenfunction:: systick_init +.. _libmaple-systick-enable: +.. doxygenfunction:: systick_enable +.. _libmaple-systick-disable: +.. 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/docs/source/libmaple/api/timer.rst b/docs/source/libmaple/api/timer.rst new file mode 100644 index 0000000..f315cb0 --- /dev/null +++ b/docs/source/libmaple/api/timer.rst @@ -0,0 +1,453 @@ +.. highlight:: c +.. _libmaple-timer: + +``timer.h`` +=========== + +Timer support. + +.. contents:: Contents + :local: + +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/docs/source/libmaple/api/usart.rst b/docs/source/libmaple/api/usart.rst new file mode 100644 index 0000000..68f2c37 --- /dev/null +++ b/docs/source/libmaple/api/usart.rst @@ -0,0 +1,197 @@ +.. highlight:: c +.. _libmaple-usart: + +``usart.h`` +=========== + +Universal Synchronous/Asynchronous Receiver/Transmitter (USART, or +commonly *serial port*) support. + +.. contents:: Contents + :local: + +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_rx +.. 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/docs/source/libmaple/api/util.rst b/docs/source/libmaple/api/util.rst new file mode 100644 index 0000000..54377c0 --- /dev/null +++ b/docs/source/libmaple/api/util.rst @@ -0,0 +1,54 @@ +.. highlight:: c +.. _libmaple-util: + +``<libmaple/util.h>`` +===================== + +.. TODO [0.2.0?] clean this up. + +Miscellaneous utility macros and procedures. + +.. contents:: Contents + :local: + +Bit Manipulation +---------------- + +The following macros are useful for bit manipulation. + +.. doxygendefine:: BIT +.. doxygendefine:: BIT_MASK_SHIFT +.. doxygendefine:: GET_BITS +.. doxygendefine:: IS_POWER_OF_TWO + +Failure Routines +---------------- + +``throb()`` is called by various routines to throb a built-in +LED. **Usually, you shouldn't call it yourself**; use something like +``ASSERT(0)`` (or the libc ``abort()`` function) instead. + +.. 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`. diff --git a/docs/source/libmaple/apis.rst b/docs/source/libmaple/apis.rst new file mode 100644 index 0000000..31f4902 --- /dev/null +++ b/docs/source/libmaple/apis.rst @@ -0,0 +1,14 @@ +.. _libmaple-apis: + +``libmaple`` API Index +====================== + +This is the master index for libmaple proper's APIs. + +**Contents** + +.. toctree:: + :maxdepth: 1 + :glob: + + api/* diff --git a/docs/source/libmaple/coding-standard.rst b/docs/source/libmaple/coding-standard.rst new file mode 100644 index 0000000..9ed56cc --- /dev/null +++ b/docs/source/libmaple/coding-standard.rst @@ -0,0 +1,422 @@ +.. _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. + +Configuration for other editors (vim, etc.) 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 +---------- + +TextMate users may find `this bundle +<https://github.com/glennr/uber-glory-tmbundle>`_ useful for +automatically converting tabs to spaces and removing trailing +whitespace at save time. + +- 4 space indents (set in ``.dir-locals.el``). + +- Unix newlines. + +- 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 <https://github.com/mbolivar/code-fascism>`_. + +- 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 + <http://en.wikipedia.org/wiki/Indent_style#Variant:_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 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 <http://sphinx.pocoo.org/>`_ for it in the + `leaflabs-docs <https://github.com/leaflabs/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 + <https://raw.github.com/leaflabs/leaflabs-docs/master/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 + <http://sphinx.pocoo.org/domains.html#the-c-domain>`_. 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 <libmaple-dac>` 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 (or `wiki <http://wiki.leaflabs.com>`_ + pages). + +- **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 + <http://www.helsinki.fi/~sjpaavol/programs/lineker.el>`_. 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 <http://www.youtube.com/watch?v=jZkdcYlOn5M>`_. + +Explicitly approved GCC extensions: + + * `asm volatile <http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_ + + * `Nested functions <http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html>`_ + +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/docs/source/libmaple/contributing.rst b/docs/source/libmaple/contributing.rst new file mode 100644 index 0000000..25c6c17 --- /dev/null +++ b/docs/source/libmaple/contributing.rst @@ -0,0 +1,176 @@ +.. _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 +<http://forums.leaflabs.com>`_ 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 <libmaple-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 <http://www.opensource.org/licenses/mit-license.php>`_. See +e.g. `bkp.h +<https://github.com/leaflabs/libmaple/blob/master/libmaple/bkp.h#L1>`_ +for an example, and the coding standard for more details. Code +released under the `Lesser GPL +<http://www.gnu.org/copyleft/lesser.html>`_ may be accepted for +Wirish, but will almost certainly be rejected for libmaple proper. We +will not accept patches released under the `GPL +<http://www.gnu.org/licenses/gpl.html>`_. + +**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 +<http://www.hermann-uwe.de/blog/libopenstm32-a-free-software-firmware-library-for-stm32-arm-cortex-m3-microcontrollers>`_. +Also note that :ref:`libraries <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 <https://github.com>`_. 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 + <https://github.com/plans>`_ (free). + +2. Fork libmaple, then clone your fork to the computer you code on. + GitHub provides detailed instructions on `forking and cloning a + repository <http://help.github.com/fork-a-repo/>`_. + +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 + <http://elinux.org/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 <jsmith@example.com>`` + + 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 <http://help.github.com/pull-requests/>`_ 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 +<http://linux.yyz.us/patch-format.html>`_, 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 + <http://elinux.org/Developer_Certificate_Of_Origin>`_ [#fcert]_. + +.. _libmaple-git-resources: + +Git Resources +------------- + +If you'd like to learn more about Git, we recommend the following +resources: + +* `The Git Community Book <http://book.git-scm.com/index.html>`_: A + collaboratively edited book on Git. + +* `Pro Git <http://progit.org/book/>`_: despite its title, this is a + fairly beginner-friendly source of information. + +* `Git - Revision Control Perfected (Linux Journal) + <http://www.linuxjournal.com/content/git-revision-control-perfected>`_: + 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. + +- `GitPhraseBook (openembedded.org) + <http://www.openembedded.org/index.php/GitPhraseBook>`_: A + cookbook-style list of common Git problems and their solutions. + +* `Understanding Git Conceptually + <http://www.eecs.harvard.edu/~cduan/technical/git/>`_: a good, + introductory tutorial on Git's fundamental concepts. + +* `Git for Computer Scientists + <http://eagain.net/articles/git-for-computer-scientists/>`_: 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. diff --git a/docs/source/libmaple/overview.rst b/docs/source/libmaple/overview.rst new file mode 100644 index 0000000..006f1d8 --- /dev/null +++ b/docs/source/libmaple/overview.rst @@ -0,0 +1,516 @@ +.. highlight:: c + +.. _libmaple-overview: + +Overview +======== + +This page is a general overview of :ref:`libmaple proper +<libmaple-vs-wirish>`. It describes libmaple's design, and names +implementation patterns to look for when using it. General +familiarity with the :ref:`STM32 <stm32>` is assumed; beginners should +start with the high-level :ref:`Wirish interface <language>` instead. +Examples are given from libmaple's sources. + +.. contents:: Contents + :local: + +Design Goals +------------ + +The central goal for libmaple proper is to provide a pleasant, +portable, and consistent set of interfaces for dealing with the +various series of STM32 microcontrollers. + +Portability in particular can be a problem when programming for the +STM32. While the various STM32 series are largely pin-compatible with +one another, the peripheral register maps between series often change +drastically, even when the functionality provided by the peripheral +doesn't change very much. This means that code which accesses +registers directly often needs to change when porting a program to a +different series MCU. + +ST's solution to this problem thus far has been to `issue +<http://www.st.com/internet/com/SOFTWARE_RESOURCES/SW_COMPONENT/FIRMWARE/stm32l1_stdperiph_lib.zip>`_ +`separate +<http://www.st.com/internet/com/SOFTWARE_RESOURCES/SW_COMPONENT/FIRMWARE/stm32f10x_stdperiph_lib.zip>`_ +`firmware +<http://www.st.com/internet/com/SOFTWARE_RESOURCES/SW_COMPONENT/FIRMWARE/stm32f2xx_stdperiph_lib.zip>`_ +`libraries +<http://www.st.com/internet/com/SOFTWARE_RESOURCES/SW_COMPONENT/FIRMWARE/stm32f4_dsp_stdperiph_lib.zip>`_; +one for each STM32 series. Along with these, they have released a +`number +<http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/APPLICATION_NOTE/DM00024853.pdf>`_ +of `application +<http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/APPLICATION_NOTE/DM00033267.pdf>`_ +`notes +<http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/APPLICATION_NOTE/DM00032987.pdf>`_ +describing the compatibility issues and how to migrate between series +by switching firmware libraries. Often, the migration advice is +essentially "rewrite your code"; this occurs, for example, with any +code involving GPIO or DMA being migrated between STM32F1 and STM32F2. + +Needless to say, this can be very annoying. (Didn't we solve this +sort of problem years ago?) When you just want your robot to fly, +your `LEDs to blink <http://www.youtube.com/watch?v=J845L45zqfk>`_, or +your `FM synthesizer <https://github.com/Ixox/preen>`_ to, well, +`synthesize <http://xhosxe.free.fr/IxoxFMSynth.mp3>`_, you probably +couldn't care less about dealing with a new set of registers. + +We want to make it easier to write portable STM32 code. To enable +that, libmaple abstracts away many hardware details behind portable +interfaces. We also want to make it easy for you to get your hands +dirty when need or desire arises. To that end, libmaple makes as few +assumptions as possible, and does its best to get out of your way when +you want it to leave. + +.. _libmaple-overview-devices: + +Libmaple's Device Model +----------------------- + +The libmaple device model is simple and stupid. This is a feature. + +*Device types* are the central libmaple abstraction; they exist to +provide portable interfaces to common peripherals, but they still let +you do nonportable things easily if you want to. + +The rules for device types are: + +- Device types are structs representing peripherals. The name of the + device type for peripheral "foo" is ``struct foo_dev`` (so for + foo=ADC, it's ``struct adc_dev``. For foo=DMA, it's ``struct + dma_dev``; etc.). These are always ``typedef``\ ed to ``foo_dev``. + +- Each device type contains any information needed or used by libmaple + for operating on the peripheral the type represents. Device types + are defined alongside declarations for portable support routines in + the header ``<libmaple/foo.h>`` (examples: :ref:`libmaple-adc`, + :ref:`libmaple-dma`). + +- Direct :ref:`register access <libmaple-overview-regmaps>` is + possible via the ``regs`` field in each device type. (Given a + ``foo_dev *foo``, you can read and write the BAR register + ``FOO_BAR`` with ``foo->regs->BAR``.) + +- An :ref:`rcc_clk_id <libmaple-rcc-rcc_clk_id>` for the device is + available in the ``clk_id`` field; this is an opaque type that can + be used to uniquely identifies the peripheral. (Given ``foo_dev + *foo``, you can check which foo you have by looking at + ``foo->clk_id``.) + +- The backend for each supported STM32 series statically initializes + devices as appropriate, and ensures that the peripheral support + header includes declarations for pointers to these statically + allocated devices. + +- Peripheral support functions usually expect a pointer to a device as + their first argument. These functions' implementations may vary + with the particular microcontroller you're targeting, but their + semantics try to stay the same. To migrate to a different target, + you'll often be able to simply recompile your program (and libmaple) + for the new target. + +- When complete portability is not possible, libmaple tries to keep + the nonportable bits in data, rather than code. + +Example: ``adc_dev`` +~~~~~~~~~~~~~~~~~~~~ + +These rules are best explained by example. The device type for ADC +peripherals is ``struct adc_dev``. Its definition is provided by +``<libmaple/adc.h>``:: + + typedef struct adc_dev { + adc_reg_map *regs; + rcc_clk_id clk_id; + } adc_dev; + +An ``adc_dev`` contains a pointer to its register map in the ``regs`` +field. This ``regs`` field is available on all device types. Its value +is a :ref:`register map base pointer +<libmaple-overview-regmaps-base-pts>` (like ``ADC1_BASE``, etc.) for +the peripheral, as determined by the current target. For example, two +equivalent expressions for reading the ADC1 regular data register are +``ADC1_BASE->DR`` and ``ADC1->regs->DR`` (though the first one is +faster). Manipulating registers directly via ``->regs`` is thus +always possible, but can be nonportable, and should you choose to do +this, it's up to you to get it right. + +An ``adc_dev`` also contains an ``rcc_clk_id`` for the ADC peripheral +it represents in the ``clk_id`` field. The ``rcc_clk_id`` enum type +has an enumerator for each peripheral supported by your series. For +example, the ADC peripherals' ``rcc_clk_id`` enumerators are +``RCC_ADC1``, ``RCC_ADC2``, and ``RCC_ADC3``. In general, an +``rcc_clk_id`` is useful not only for managing the clock line to a +peripheral, but also as a unique identifier for that peripheral. + +(Device types can be more complicated than this; ``adc_dev`` was +chosen as a simple example of the minimum you can expect.) + +Rather than have you define your own ``adc_dev``\ s, libmaple defines +them for you as appropriate for your target STM32 series. For example, +on STM32F1, the file libmaple/stm32f1/adc.c contains the following:: + + static adc_dev adc1 = { + .regs = ADC1_BASE, + .clk_id = RCC_ADC1, + }; + /** ADC1 device. */ + const adc_dev *ADC1 = &adc1; + + static adc_dev adc2 = { + .regs = ADC2_BASE, + .clk_id = RCC_ADC2, + }; + /** ADC2 device. */ + const adc_dev *ADC2 = &adc2; + + #if defined(STM32_HIGH_DENSITY) || defined(STM32_XL_DENSITY) + static adc_dev adc3 = { + .regs = ADC3_BASE, + .clk_id = RCC_ADC3, + }; + /** ADC3 device. */ + const adc_dev *ADC3 = &adc3; + #endif + +Since all supported STM32F1 targets support ADC1 and ADC2, libmaple +predefines corresponding ``adc_dev`` instances for you. To save space, +it avoids defining an ``adc_dev`` for ADC3 unless you are targeting a +high- or XL-density STM32F1, as medium- and lower density MCUs don't +have ADC3. + +Note that the structs themselves are static and are exposed only via +pointers. These pointers are declared in a series-specific ADC +header, ``<series/adc.h>`` which is included by ``<libmaple/adc.h>`` +based on the MCU you're targeting. (**Never include <series/foo.h> +directly**. Instead, include ``<libmaple/foo.h>`` and let it take +care of that for you.) On STM32F1, the series ADC header contains the +following:: + + extern const struct adc_dev *ADC1; + extern const struct adc_dev *ADC2; + #if defined(STM32_HIGH_DENSITY) || defined(STM32_XL_DENSITY) + extern const struct adc_dev *ADC3; + #endif + +In general, you access the predefined devices via these pointers. As +illustrated by the ADC example, the variables for these pointers +follow the naming scheme used in ST's reference manuals -- the pointer +to ADC1's ``adc_dev`` is named ``ADC1``, and so on. + +The :ref:`API documentation <libmaple-apis>` for the peripherals +you're interested in will list the available devices on each target. + +Using Devices +~~~~~~~~~~~~~ + +Peripheral support routines usually expect pointers to their device +types as their first arguments. Here are some ADC examples:: + + uint16 adc_read(const adc_dev *dev, uint8 channel); + static inline void adc_enable(const adc_dev *dev); + static inline void adc_disable(const adc_dev *dev); + +So, to read channel 2 of ADC1, you could call ``adc_read(ADC1, 2)``. +To disable ADC2, call ``adc_disable(ADC2)``; etc. + +That's it; there's nothing complicated here. In general, just follow +links from the :ref:`libmaple-apis` page to the header for the +peripheral you're interested in. It will explain the supported +functionality, both portable and series-specific. + +Segregating Non-portable Functionality into Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As mentioned previously, when total portability isn't possible, +libmaple tries to do the right thing and segregate the nonportable +portions into data rather than code. The function +``adc_set_sample_rate()`` is a good example of how this works, and why +it's useful:: + + void adc_set_sample_rate(const adc_dev *dev, adc_smp_rate smp_rate); + +For example, while both STM32F1 and STM32F2 support setting the ADC +sample time via the same register interface, the actual sample times +supported are different. For instance, on STM32F1, available sample +times include 1.5, 7.5, and 13.5 ADC cycles. On STM32F2, none of these +are available, but 3, 15, and 28 ADC cycles are supported (which is +not true for STM32F1). To work with this, libmaple provides a single +function, ``adc_set_sample_rate()``, for setting an ADC controller's +channel sampling time, but the actual sample rates it takes are given +by the ``adc_smp_rate`` type, which is different on STM32F1 and +STM32F2. + +This is the STM32F1 implementation of adc_smp_rate:: + + typedef enum adc_smp_rate { + ADC_SMPR_1_5, /**< 1.5 ADC cycles */ + ADC_SMPR_7_5, /**< 7.5 ADC cycles */ + ADC_SMPR_13_5, /**< 13.5 ADC cycles */ + ADC_SMPR_28_5, /**< 28.5 ADC cycles */ + ADC_SMPR_41_5, /**< 41.5 ADC cycles */ + ADC_SMPR_55_5, /**< 55.5 ADC cycles */ + ADC_SMPR_71_5, /**< 71.5 ADC cycles */ + ADC_SMPR_239_5, /**< 239.5 ADC cycles */ + } adc_smp_rate; + +And here is the STM32F2 implementation:: + + typedef enum adc_smp_rate { + ADC_SMPR_3, /**< 3 ADC cycles */ + ADC_SMPR_15, /**< 15 ADC cycles */ + ADC_SMPR_28, /**< 28 ADC cycles */ + ADC_SMPR_56, /**< 56 ADC cycles */ + ADC_SMPR_84, /**< 84 ADC cycles */ + ADC_SMPR_112, /**< 112 ADC cycles */ + ADC_SMPR_144, /**< 144 ADC cycles */ + ADC_SMPR_480, /**< 480 ADC cycles */ + } adc_smp_rate; + +So, on F1, you could call ``adc_set_sample_rate(ADC1, ADC_SMPR_1_5)``, +and on F2, you could call ``adc_set_sample_rate(ADC1, +ADC_SMPR_3)``. If you're only interested in one of those series, then +that's all you need to know. + +However, if you're targeting multiple series, then this is useful +because it lets you put the actual sample time for the MCU you're +targeting into a variable (or macro, etc.), whose value depends on the +target you're compiling for. This lets you have a single codebase to +test and maintain, and lets you add support for a new target by simply +adding some new data. + +To continue the example, one easy way is to pick an ``adc_smp_rate`` +for each of STM32F1 and STM32F2 is with conditional compilation. Using +the :ref:`STM32_MCU_SERIES <libmaple-stm32-STM32_MCU_SERIES>` define +from :ref:`libmaple-stm32`, you can write:: + + #include <libmaple/adc.h> + #include <libmaple/stm32.h> + + #if STM32_MCU_SERIES == STM32_SERIES_F1 + /* Target is an STM32F1 */ + adc_smp_rate smp_rate = ADC_SMPR_1_5; + #elif STM32_MCU_SERIES == STM32_SERIES_F2 + /* Target is an STM32F2 */ + adc_smp_rate smp_rate = ADC_SMPR_3; + #else + #error "Unsupported STM32 target; can't pick a sample rate" + #endif + + void setup(void) { + adc_set_smp_rate(ADC1, smp_rate); + } + +Adding support for e.g. STM32F4 would only require adding a new +``#elif`` for that series. This is simple, but hackish, and can get +out of control if you're not careful. + +Another way to get the job done is to declare an ``extern adc_smp_rate +smp_rate``, and use the build system to compile a file defining +``smp_rate`` depending on your target. As was discussed earlier, this +is what libmaple does when choosing which files to use for defining +the appropriate ``adc_dev``\ s for your target. How to do this is +outside the scope of this overview, however. + +.. _libmaple-overview-regmaps: + +Register Maps +------------- + +Though we aim to enable libmaple's users to interact with the more +portable :ref:`device interface <libmaple-overview-devices>` as much +as possible, there will always be a need for efficient direct register +access. To allow for that, libmaple provides *register maps* as a +consistent set of names and abstractions for dealing with peripheral +registers and their bits. + +A *register map type* is a struct which names and provides access to a +peripheral's registers (we can use a struct because registers are +usually mapped into contiguous regions of memory). Here's an example +register map for the DAC peripheral on STM32F1 series MCUs (``__io`` +is just libmaple's way of saying ``volatile`` when referring to +register values):: + + 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 right-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 the chip reference +manual (for STM32F1, that's 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 (DAC_DHR12R1) is the ``DHR12R1`` field in +a ``dac_reg_map``. Second, if the reference manual 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. + +.. _libmaple-overview-regmaps-base-pts: + +So let's say you've included ``<libmaple/foo.h>``, and you want to +mess with some particular register. You'll do this using *register map +base pointers*, which are pointers to ``struct foo_reg_map``. What's +the name of the base pointer you want? That depends on if there's +more than one foo or not. If there's only one foo, then libmaple +guarantees there will be a ``#define`` that looks like like this:: + + #define FOO_BASE ((struct foo_reg_map*)0xDEADBEEF) + +That is, you're guaranteed there will be a pointer to the (only) +``foo_reg_map`` you want, and it will be called +``FOO_BASE``. (``0xDEADBEEF`` is the register map's *base address*, or +the fixed location in memory where the register map begins). Here's +an example for STM32F1:: + + #define DAC_BASE ((struct dac_reg_map*)0x40007400) + +Here are some examples for how to read and write to registers using +register map base pointers. + +* In order to write 2048 to the channel 1 12-bit left-aligned data + holding register (DAC_DHR12L1), you would write:: + + DAC_BASE->DHR12L1 = 2048; + +* In order to read the DAC control register, you would write:: + + uint32 cr = DAC_BASE->CR; + +That covers the case where there's a single foo peripheral. If +there's more than one (say, if there are *n*), then +``<libmaple/foo.h>`` provides the following:: + + #define FOO1_BASE ((struct foo_reg_map*)0xDEADBEEF) + #define FOO2_BASE ((struct foo_reg_map*)0xF00DF00D) + ... + #define FOOn_BASE ((struct foo_reg_map*)0x1EAF1AB5) + +Here are some examples for the ADCs on STM32F1:: + + #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 would write:: + + uint32 converted_result = ADC1_BASE->DR; + +Register Bit Definitions +------------------------ + +In ``<libmaple/foo.h>``, there will also be a variety of ``#define``\ +s for dealing with interesting bits in the xxx registers, called +*register bit definitions*. In keeping with the ST reference manuals, +these are named according to the scheme ``FOO_REG_FIELD``, where +"``REG``" refers to the register, and "``FIELD``" refers to the bit or +bits in ``REG`` that are special. + +Again, this is probably best explained by example. On STM32F1, each +Direct Memory Access (DMA) controller's register map has a certain +number of channel configuration registers (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 on +STM32F1:: + + #define DMA_CCR_MEM2MEM_BIT 14 + #define DMA_CCR_MEM2MEM (1U << 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 (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 set +the priority level of a DMA transfer to "high priority", you can +do a read-modify-write sequence on the DMA_CCR_PL bits like so:: + + uint32 ccr = DMA1_BASE->CCR2; + ccr &= ~DMA_CCR_PL; + ccr |= DMA_CCR_PL_HIGH; + DMA1_BASE->CCR2 = ccr; + +Of course, before doing that, you should check to make sure there's +not already a device-level function for performing the same task! (In +this case, there is. It's called :c:func:`dma_set_priority()`; see +:ref:`libmaple-dma`.) For instance, **none of the above code is +portable** to STM32F4, which uses DMA streams instead of channels for +this purpose. + +Peripheral Support Routines +--------------------------- + +This section describes patterns to look for in peripheral support +routines. + +In general, each device needs to be initialized before it can be used. +libmaple provides this initialization routine for each peripheral +``foo``; its name is ``foo_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 <libmaple/dma.h> */ + void dma_init(dma_dev *dev); + + /* From <libmaple/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 +``foo_enable()``, and often take additional arguments which specify a +particular configuration for the peripheral. Some examples:: + + /* From <libmaple/usart.h> */ + void usart_enable(usart_dev *dev); + + /* From <libmaple/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 :ref:`libmaple API pages +<libmaple-apis>` are your friends here. + +.. rubric:: Footnotes + +.. [#fgpio] As an exception, GPIO ports are given letters instead of + numbers (``GPIOA`` and ``GPIOB`` instead of ``GPIO1`` and + ``GPIO2``, etc.). diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst new file mode 100644 index 0000000..1ae0e87 --- /dev/null +++ b/docs/source/libraries.rst @@ -0,0 +1,80 @@ +.. highlight:: c++ +.. default-domain:: cpp + +.. _libraries: + +========================= + 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 lists the extra libraries that are part of the :ref:`Maple +IDE <ide>` (along with the rest of :ref:`libmaple <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 of a +library are noted in the library's documentation. + +.. contents:: Contents + :local: + +.. toctree:: + :hidden: + + libs/servo.rst + libs/wire.rst + +.. admonition:: **Looking for Something Else?** + + - See the :ref:`language` for information on the core functions + used for programming a Maple board. + + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + <arm-gcc>` used to compile your programs is configured to link + against `newlib <http://sourceware.org/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 low-level hardware support libraries, see + the :ref:`libmaple Reference <libmaple>`. + +.. _libraries-servo: + +Servo +----- + +The :ref:`Servo <libs-servo>` library is provided for convenient +control of RC servomotors. + +.. _libraries-liquid-crystal: + +LiquidCrystal +------------- + +.. 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 +<http://www.arduino.cc/en/Reference/LiquidCrystal>`_. + +**Arduino Compatibility** + +At this time, no incompatibilities between the Maple and Arduino +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: + +Wire +---- + +.. FIXME [0.0.13] Update with crenn's info + +We currently provide a soft (bit-banged) implementation of the +:ref:`Wire <libs-wire>` I2C library. A hardware version is planned +for Maple IDE release 0.1.0. diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst new file mode 100644 index 0000000..80288c6 --- /dev/null +++ b/docs/source/libs/servo.rst @@ -0,0 +1,92 @@ +.. 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 <timers>`. + +You can use this library in the :ref:`IDE <ide>` by choosing the Servo +item under the Sketch > Import Library... menu. + +If you are using the :ref:`Unix toolchain <unix-toolchain>`, the +library is located in the ``/libraries/Servo/`` :ref:`libmaple` +directory. + +.. contents:: Contents + :local: + +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); + +.. doxygenclass:: Servo + :members: + +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 +servos with "bit-banged" PWM (in the sense that timer interrupt +handlers are used to manually toggle pins), the Maple implementation +uses :ref:`timers <timers>` to drive the PWM directly. + +Consequently, **the Maple implementation only allows Servo instances +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 +in the list of :ref:`boardPWMPins <lang-board-values-pwm-pins>` in +your board's :ref:`hardware documentation <index-boards>`. + +RC Servos expect a pulse approximately every 20ms. In the Maple +implementation, :ref:`periods <lang-hardwaretimer-setperiod>` 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 +<gpio-pin-maps>` to match up pins and timer channels. + +And here's some fine print: + +- Although it is not publicly documented to do so, the Arduino + implementation of `attach() + <http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer + channel associated with the newly-attached pin, or 0 on failure (as + of Arduino 0021). The Maple implementation returns :ref:`true + <lang-constants-true>` on success, and :ref:`false + <lang-constants-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 + +.. [#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/docs/source/libs/wire.rst b/docs/source/libs/wire.rst new file mode 100644 index 0000000..2c5bed9 --- /dev/null +++ b/docs/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 <ide>` by choosing the +Wire item under the Sketch > Import Library... menu. + +If you are using the :ref:`Unix toolchain <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/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst new file mode 100644 index 0000000..7e9bfa2 --- /dev/null +++ b/docs/source/maple-ide-install.rst @@ -0,0 +1,176 @@ +.. 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 <troubleshooting>` for help with +some common problems. If all else fails, try our `forum`_, or `contact +us directly`_\ ! + +.. contents:: Contents + :local: + +Download +-------- + +.. FIXME [RELEASE] Update this for the release. + +This documentation was built from a development version of libmaple. +See the formally released `LeafLabs documentation +<http://leaflabs.com/docs/>`_ for more information about the current +Maple IDE release. + +.. Choose the correct version for your operating system: + +.. .. list-table:: +.. :widths: 15 30 +.. :header-rows: 1 + +.. * - Platform +.. - Status +.. - IDE Package +.. * - `Windows XP <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-0.0.10-windowsxp32.zip>`_ +.. - Tested on Debian Wheezy (64-bit) and Mint 14.1 (64-bit) +.. * - `Linux <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-0.0.10-linux32.tgz>`_ +.. - Tested on Ubuntu 10.04 (32-bit) +.. * - `Mac OS X <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-0.0.10-macosx-10_6.dmg>`_ +.. - Tested on Snow Leopard (10.6) + +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 <http://www.fsf.org/>`_; we are grateful to the `Arduino +<http://arduino.cc/>`_, `CodeSourcery +<http://www.codesourcery.com/>`_, `GNU <http://www.gnu.org/>`_, and +`OpenMoko <http://openmoko.com/>`_ developers, as well as many others, +who allow us to reuse their software. + +**Looking for something older?** `Source archives and binaries +<http://static.leaflabs.com/pub/leaflabs/maple-ide/>`_ are available +for previously-released versions. + +Installation +------------ + +* :ref:`Windows <maple-ide-install-windows>` +* :ref:`Linux <maple-ide-install-linux>` +* :ref:`OS X <maple-ide-install-osx>` + +.. _maple-ide-install-windows: + +Windows XP (Legacy Only) +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: Note that while these instructions work on Windows XP, + changes in Windows 7 (and later) mean that you won't be able to install the + IDE without disabling driver signing on your computer. + `Users on the forum have reported a workaround + <http://forums.leaflabs.com/topic.php?id=73#post-788>`_, but we + only officially support the IDE on 32-bit Windows XP. + +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: + + +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 + <troubleshooting-perpetual-bootloader>`. 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: +.. 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. + 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 + (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 will be prompted +with something along the lines of ``[sudo] password for +<username>:``). You now need to restart udev:: + + $ 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 by +running ``$ sudo adduser <your username> 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 <toolchain-udev>`). + +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. + diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst new file mode 100644 index 0000000..a4bc55a --- /dev/null +++ b/docs/source/maple-quickstart.rst @@ -0,0 +1,210 @@ +.. highlight:: sh + +.. _maple-quickstart: + +======================== + Maple Quickstart Guide +======================== + +.. 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 <http://leaflabs.com/store/>`_, a `Mini-B +USB cable <http://www.google.com/products?q=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:`troubleshooting page +<troubleshooting>` for help with some common problems. If all else +fails, try our `forum`_, or `contact`_ us directly! + +.. contents:: Contents + :local: + +.. _maple-quickstart-get-ide: + +Install and run the IDE +----------------------- + +See the :ref:`IDE installation page <maple-ide-install>` for instructions. + +.. _maple-quickstart-compile-blinky: + +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", where +"..." depends on the board you're using. + +.. image:: /_static/img/blinky-to-flash.png + :align: center + :alt: Upload to Flash + +.. note:: + + 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. + + 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 + :alt: Verify button + +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 + :alt: Code verified successfully. + +.. _maple-quickstart-upload: + +Upload that program! +-------------------- + +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 +<maple-powering>` 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 + :alt: Correctly plugged in Maple + +.. note:: + + On OS X, a network interface dialog will pop up every time you plug in + the board. + + .. 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" + +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: + +.. 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 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 quick blinking patterns, followed a +constant blinking on and off. Congratulations! You've successfully +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 <troubleshooting-throb>` for help. + +Next, go ahead and modify the file a little bit. If you change the +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 +of your program to your Maple. + +.. warning:: + + 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 + it back in, using :ref:`perpetual bootloader mode + <troubleshooting-perpetual-bootloader>`, or restarting the + IDE. + + If nothing works, please report the problem in the `forum`_. + +.. _maple-quickstart-serial-port: + +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 +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. 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! +--------------------- + +We really hope you got this far and didn't frown or make a bitter +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 <http://everything2.com/title/Velvet+Elvis>`_. + +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 +<unix-toolchain>` 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! Reach us at `leaflabs +<http://twitter.com/#!/leaflabs>`_ on Twitter, post in the `forum`_, +post on `our wiki's Projects page +<http://wiki.leaflabs.com/index.php?title=Projects>`_, track us down +in the real world, whatever. We love projects! diff --git a/docs/source/prolog.rst b/docs/source/prolog.rst new file mode 100644 index 0000000..8606555 --- /dev/null +++ b/docs/source/prolog.rst @@ -0,0 +1,8 @@ +.. 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` +.. |vdda| replace:: V\ :sub:`DDA` +.. |i2c| replace:: I\ :sup:`2`\ C diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst new file mode 100644 index 0000000..421229d --- /dev/null +++ b/docs/source/pwm.rst @@ -0,0 +1,103 @@ +.. _pwm: + +PWM +=== + +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 +("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 +-------- + +.. 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 +<timers>` for more information. See your board's :ref:`pin mapping +tables <gpio-pin-maps>` to track down the correspondence +between timer channels and GPIO pins. + +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 +<lang-hardwaretimer-setprescalefactor>` (clock divider) in front of +the counter can increase this maximum period. Setting the +:ref:`period <lang-hardwaretimer-setperiod>` 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 +------------------ + +- :ref:`lang-pinmode` +- :ref:`lang-pwmwrite` +- :ref:`Timer API<lang-hardwaretimer>` (especially :ref:`setOverflow() + <lang-hardwaretimer-setoverflow>`, :ref:`setPrescaleFactor() + <lang-hardwaretimer-setprescalefactor>`, and :ref:`setPeriod() + <lang-hardwaretimer-setperiod>`). +- :ref:`Timers reference <timers>`. + +Recommended Reading +------------------- + +* `Wikipedia Article on Pulse-width modulation + <http://en.wikipedia.org/wiki/Pulse-width_modulation>`_ +* `Arduino tutorial on PWM <http://www.arduino.cc/en/Tutorial/PWM>`_ +* `Secrets of Arduino PWM + <http://www.arcfn.com/2009/07/secrets-of-arduino-pwm.html>`_ by Ken + Shirriff +* `So You Want To Use PWM, Eh? <http://www.nlvocables.com/blog/?p=188>`_ at Non-Lexical Vocables +* STMicro documentation for STM32F103RB microcontroller: + + * `Datasheet <http://www.st.com/web/en/resource/technical/document/datasheet/CD00161566.pdf>`_ (pdf) + * `Reference Manual <http://www.st.com/st-web-ui/static/active/en/resource/technical/document/programming_manual/CD00228163.pdf>`_ (pdf) diff --git a/docs/source/spi.rst b/docs/source/spi.rst new file mode 100644 index 0000000..13c4c59 --- /dev/null +++ b/docs/source/spi.rst @@ -0,0 +1,30 @@ +.. _spi: + +===== + SPI +===== + +The Serial Peripheral Interface Bus (SPI) is a serial data transfer +protocol useful for interacting with a wide variety of hardware +peripherals. + +The public libmaple API for managing the SPI ports is the +:ref:`HardwareSPI <lang-hardwarespi>` class. + +Recommended Reading +------------------- + +* `Wikipedia Article on Serial Peripheral Interface Bus (SPI) + <http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus>`_ + +* `Arduino reference on SPI + <http://arduino.cc/en/Reference/SPI>`_ + +* `Hardcore SPI on Arduino <http://web.archive.org/web/20100522034122/http://klk64.com/arduino-spi/>`_ by kik64 + +* ST Documentation: + + * Reference Manual `RM0008 + <http://www.st.com/web/en/resource/technical/document/reference_manual/CD00171190.pdf>`_ + (PDF), Chapter 25, "Serial Peripheral Interface" + diff --git a/docs/source/stm32.rst b/docs/source/stm32.rst new file mode 100644 index 0000000..d918655 --- /dev/null +++ b/docs/source/stm32.rst @@ -0,0 +1,87 @@ +.. _stm32: + +Introduction to STM32 +===================== + +.. FIXME [v0.0.13] Stub page. + +Every Maple board is powered by an STM32 microcontroller (the chip +which controls all of the pins). Once you're comfortable using your +Maple, you'll probably start to get curious about what's going on +under the hood. This page is a good place to begin. It includes an +overview of the STM32, and helps you make sense of the sometimes +dizzying array of features, libraries, and documentation that are +available to you. + +The world of the STM32 is a big one, and it's only getting bigger. +With literally thousands of pages of manuals, datasheets, application +notes, etc. available for every STM32 microcontroller, and a huge +variety of categories and subcategories of STM32s available to choose +from, it's easy to get confused or feel daunted about getting started. +Don't panic! We've got `your towel +<http://en.wikipedia.org/wiki/Know_where_one%27s_towel_is#Knowing_where_one.27s_towel_is>`_ +right here. + +.. contents:: Contents + :local: + +.. _stm32-general: + +General Information +------------------- + +- Description of the history and present state of the STM32 line. ARM + Cortex-M series etc. + +- Introduction and pointers to ARM Cortex-M docs and other good books + on the subject. + +- Pointers to ST reference manuals. Note that the appropriate + reference manual for each board is always documented in that board's + hardware page. + +.. _stm32-series: +.. _stm32-series-f1-lines: + +STM32 Series +------------ + +- Describe families, F1 lines, etc. + +- Describe how a product name tells you what you need + +ST's Documentation +------------------ + +- Classes of documentation: product flyer, datasheet, reference + manual, programming manual, application note. + +.. _stm32-registers: + +Registers and Register Maps +--------------------------- + +- General purpose registers vs. peripheral registers. + +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 :ref:`USARTs <usart>` have data registers; (some of +the) the :ref:`timers <timers>` have capture/compare registers, the +:ref:`GPIOs <gpio>` have output data registers, etc. + +- Peripheral register maps; how they're duplicated for each peripheral + +- Portability concerns across series + +.. _stm32-libmaple-support: + +``libmaple`` STM32 support +-------------------------- + +- Descriptions of libmaple's present support for the STM32 line + (i.e. currently performance-line only; update when the F2 branch is + ready to merge into master etc.). diff --git a/docs/source/systick.rst b/docs/source/systick.rst new file mode 100644 index 0000000..afc8d09 --- /dev/null +++ b/docs/source/systick.rst @@ -0,0 +1,15 @@ +.. _systick: + +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/docs/source/timers.rst b/docs/source/timers.rst new file mode 100644 index 0000000..0fa0976 --- /dev/null +++ b/docs/source/timers.rst @@ -0,0 +1,123 @@ +.. highlight:: cpp + +.. _timers: + +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 +<pwm>` 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. + +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. + +Library Documentation +--------------------- + +See the :ref:`HardwareTimer <lang-hardwaretimer>` reference for more +information on controlling the built-in timers. + +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:`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: + +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 timer pin map to match up timer channels and pin +numbers: + +* :ref:`Maple <maple-timer-map>` +* :ref:`Maple RET6 Edition <maple-ret6-timer-map>` +* :ref:`Maple Mini <maple-mini-timer-map>` +* :ref:`Maple Native Beta <maple-native-b-timer-map>` + +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 <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 +<troubleshooting-perpetual-bootloader>` before uploading a new program +to it (or somehow causing your program to re-enable serial over USB +using :ref:`SerialUSB.begin() <lang-serialusb-begin>`). + +The :ref:`SysTick <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() +<libmaple-systick-disable>`, and re-enabled using +:ref:`systick_enable() <libmaple-systick-enable>`. 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/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 0000000..4d7cbb0 --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,258 @@ +.. highlight:: sh + +.. _troubleshooting: + +Troubleshooting +=============== + +This page documents common problems and their solutions. + +.. contents:: Contents + :local: + +=================== + Hardware problems +=================== + +.. _troubleshooting-throb: + +The LED is throbbing and my program is stopped! +----------------------------------------------- + +The LED throbs when there has been a failed software :ref:`ASSERT() +<lang-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 +<http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0337e/ch05s12s01.html>`_. + +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 +<troubleshooting-perpetual-bootloader>`. + +My board is bricked! I can't upload via the bootloader no matter what! +---------------------------------------------------------------------- + +Don't panic. First, make sure that the board is plugged in correctly +for program upload, using the instructions given in the +:ref:`quickstart <maple-quickstart-upload>`. If that doesn't work, +try using :ref:`perpetual bootloader mode +<troubleshooting-perpetual-bootloader>`. + +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 +<bootloader-reflashing>` over serial (or :ref:`JTAG <jtag>`). + +If your board really is bricked, and you think it's our fault, +`contact us <http://leaflabs.com/contact>`_\ ! + +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:`Arduino Compatibility +<arduino-compatibility>`, :ref:`GPIO <gpio>`, or other :ref:`hardware +specific documentation <index-hardware>` for more information. + +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:`Maple Errata +<maple-rev3-bad-buttons>` for details. `We're happy to replace these +for you <http://leaflabs.com/contact>`_\ ! + +.. _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 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! + +.. _troubleshooting-compilation: + +========================== + Common compiler problems +========================== + +``NullPointerException`` +------------------------ + +A classic! Make sure you have selected a board from the pulldown menu. + +``undefined reference to setup()/loop()`` +----------------------------------------- + +Your sketch/program either does not include one of the :ref:`setup() +<lang-setup>` or :ref:`loop() <lang-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 <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 <usart>`. + +``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. + +.. _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 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() <lang-serialusb-end>`. + +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 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! +--------------------------------------------------------------------- + +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 <unix-toolchain>`, Make sure +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: + +=================== +Command-Line Issues +=================== + +[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 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 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 +=============== + +.. _troubleshooting-perpetual-bootloader: + +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 (or other Maple board) into perpetual bootloader mode: + +#. Plug your board into the USB port. + +#. 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 normal button is labeled BUT). You + can release it once the slow blinks start. diff --git a/docs/source/unix-toolchain-linux-setup.rst b/docs/source/unix-toolchain-linux-setup.rst new file mode 100644 index 0000000..c1333e1 --- /dev/null +++ b/docs/source/unix-toolchain-linux-setup.rst @@ -0,0 +1,203 @@ +.. highlight:: sh + +.. _unix-toolchain-linux-setup: + +Unix Toolchain Linux Setup +========================== + +This page contains instructions for setting up a Linux computer for +use with the :ref:`Unix toolchain <unix-toolchain>`. (Setup +instructions for :ref:`other operating systems <toolchain-setup>` are +also available.) + +These instructions have been tested successfully on: + +- Ubuntu 10.04 and 12.04 (32- and 64-bit) +- Fedora 17 (64-bit) +- Debian Wheezy 64-bit + +Generic instructions for other distributions are also provided. Please +`contact`_ us with any updates for distros not already covered! + +.. contents:: Contents + :local: + +Collect and Install Tools +------------------------- + +First, you'll need some tools. + +.. warning:: Due to firmware bugs in our :ref:`bootloader + <bootloader>`, you must use recent versions of ``dfu-util``, or + uploads will not work. ``dfu-util`` versions 0.6 and greater + should work. + +**Debian-based distributions (Debian, Ubuntu, Mint, etc.)**: + + Install mandatory and optional tools with :: + + $ sudo apt-get install build-essential git-core screen dfu-util python python-serial + + On *64-bit distros only*, you will also need to install some 32-bit + libraries needed by the LeafLabs-supported :ref:`ARM GCC toolchain + <arm-gcc>` with :: + + # 64-bit systems only! + $ sudo apt-get install ia32-libs + + # As of Ubuntu 13, you should do this instead: + $ sudo apt-get install lib32z1 lib32ncurses5 lib32bz2-1.0 + + You may also need to remove `brltty <http://mielke.cc/brltty/>`_ + with :: + + # Optional + $ sudo apt-get remove brltty + + Brltty provides braille access to the console. It has been reported + to cause conflicts with Maple. + +**Red Hat-based distributions (RHEL, Fedora, Centos, etc.)**: + + Install mandatory and optional tools with :: + + $ sudo yum install screen git python pyserial dfu-util make + + On *64-bit distros only*, you will also need to install 32-bit + libraries needed by the LeafLabs-supported :ref:`ARM GCC toolchain + <arm-gcc>` with :: + + # 64-bit systems only! + $ sudo yum install glibc.i686 + + You may also need to remove `brltty <http://mielke.cc/brltty/>`_ + with one of these:: + + # Optional, 64-bit systems: + $ sudo yum erase brltty.x86_64 + + # Optional, 32-bit systems: + $ sudo yum erase brltty.i686 + + Brltty provides braille access to the console. It has been + reported to cause conflicts with Maple. + +**Other Linux distributions**: + + On other distributions, you'll need to figure this out for yourself + (please `contact`_ us if you have instructions for distros not + covered here!). + + Mandatory tools: + + * `Git`_ is a distributed version control system. We use it to track + our source code. + + * `dfu-util`_ is a tool from the `OpenMoko`_ project. It is used to + upload programs to the Maple over USB. + + * `Make <http://www.gnu.org/software/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 <bootloader>`, is written in Python (and + works with Python 2 or 3). Most Linux distributions these days + include Python by default. + + * `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`_. + + Optional tools: + + * `screen <http://www.gnu.org/s/screen/>`_ is a screen manager used + here to connect to serial port devices. (Some popular + alternatives are `Minicom + <http://alioth.debian.org/projects/minicom/>`_ and `Kermit + <http://www.kermitproject.org/>`_). + +Fetch ``libmaple`` and Compiler Toolchain +----------------------------------------- + +First, make a Git clone of :ref:`libmaple`:: + + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git libmaple + +Next, download the `Linux ARM GCC toolchain +<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz>`_ +you'll use to build your programs. Extract the archive into a +directory named :file:`arm`. Put the resulting :file:`arm/bin` +subdirectory somewhere in your ``PATH``. For example, if you have +`wget <http://www.gnu.org/software/wget/>`_ installed, you can run:: + + $ 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 + $ export PATH=$PATH:~/libmaple/arm/bin + +You can check that this worked by entering ``arm-none-`` and hitting +tab to auto-complete; your shell should show a bunch of results. After +you're done, you'll probably want to update your shell startup script +so the :file:`arm/bin` directory stays in your ``PATH``. + +.. _toolchain-udev: + +Install udev Rules +------------------ + +From the libmaple directory, copy our udev rules [#fudev]_ to +``/etc/udev/rules.d``:: + + $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules + +Then restart udev. + +**Ubuntu (NOT Debian)**: + + Make sure you are in the plugdev group (e.g. by running ``$ groups`` + and seeing if the output includes "plugdev"). If not, add yourself + to plugdev with :: + + $ sudo usermod -a -G plugdev $USER + + then log out and log back in. + + After that's done, restart udev:: + + $ sudo restart udev + +**Debian (NOT Ubuntu)**: + + Make sure you're in the dialout group. If not, add yourself with :: + + $ sudo usermod -a -G dialout $USER + + then log out and log back in. + + After that's done, restart udev:: + + $ sudo /etc/init.d/udev restart + +**Red Hat-based distros**: + + :: + + $ udevadm control --reload-rules + +After restarting ``udev``, you'll need to unplug and re-plug your +Maple. + +So far, so good? +---------------- + +Great! Move on by :ref:`compiling a sample program <toolchain-test>`. + +.. rubric:: Footnotes + +.. [#fudev] 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 (for Debian-based distros) grants + read/write permissions to the ``plugdev`` group. diff --git a/docs/source/unix-toolchain-osx-setup.rst b/docs/source/unix-toolchain-osx-setup.rst new file mode 100644 index 0000000..01b9e2c --- /dev/null +++ b/docs/source/unix-toolchain-osx-setup.rst @@ -0,0 +1,132 @@ +.. highlight:: sh + +.. _unix-toolchain-osx-setup: + +Unix Toolchain OS X Setup +========================= + +This page contains instructions for setting up an OS X computer for +use with the :ref:`Unix toolchain <unix-toolchain>`. (Setup +instructions for :ref:`other operating systems <toolchain-setup>` are +also available.) + +These instructions have been tested successfully on OS X 10.6.4 and +10.8.1. + +.. contents:: Contents + :local: + +Collect and Install Tools +------------------------- + +First, you'll need some tools. [#fpackman]_ + +* `XCode <https://developer.apple.com/xcode/>`_: Provides compilers + and other basic tools of the trade. XCode seems to only be available for + those with Apple IDs through the Mac App Store. If you'd rather not go + through that mechanism, you can probably get by with just a `make + <http://www.gnu.org/software/make/>`_ binary, but you're on your own. + +* `Git`_: All of our code is tracked by a distributed versioning + system called Git. A `Mac installer + <http://code.google.com/p/git-osx-installer/downloads/list?can=3>`_ + is available. + +* `dfu-util`_: A tool from `OpenMoko`_ that we use to upload programs + to the Maple over USB. + + .. warning:: Due to firmware bugs in our :ref:`bootloader + <bootloader>`, you must use recent versions of ``dfu-util``, or + uploads will not work. ``dfu-util`` versions 0.6 and greater + should work. + + If you prefer to compile from source, OpenMoko provides instructions + for `building dfu-util on OS X + <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_. + + If you're in a hurry, you can use the dfu-util binary bundled with + `OpenMoko Flasher + <http://www.handheld-linux.com/wiki.php?page=OpenMoko%20Flasher>`_. To + do this, first `download OpenMoko Flasher + <http://projects.goldelico.com/p/omflasher/downloads/>`_, 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` + + 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 + + .. note:: + + Copying the binary won't work, as it relies on dynamically linked + libraries found elsewhere in the .app bundle. + + To make sure this worked, plug in your Maple, put it into + :ref:`perpetual bootloader mode + <troubleshooting-perpetual-bootloader>` (press RESET, then quickly + press and hold BUT for several seconds), and run :: + + $ dfu-util -l + + The output should look like this:: + + 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" + +* `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 + extract the `latest version + <http://pypi.python.org/pypi/pyserial>`_, then install with :: + + $ cd /path/to/pyserial-x.y + $ python setup.py build + $ sudo python setup.py install + + PySerial is also available via `easy_install`_, so if you're + comfortable using that, you could alternatively install it with :: + + $ easy_install pyserial + +Fetch ``libmaple`` and Compiler Toolchain +----------------------------------------- + +First, make a `Git`_ clone of :ref:`libmaple`:: + + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git + +Next, `download the cross-compilers +<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_ +you'll use to build libmaple and your own programs. (These are just +special-purpose versions of :ref:`GCC <arm-gcc>`). + +Let's say you saved these into +:file:`~/Downloads/gcc-arm-none-eabi-latest-osx32.tar.gz`. Then unpack +the archive and tell the shell about its contents with:: + + $ cd ~/Downloads + $ tar -xvf gcc-arm-none-eabi-latest-osx32.tar.gz + $ mv arm ~/libmaple/arm + $ export PATH=$PATH:~/libmaple/arm/bin + +After that's done, update your shell startup script so +:file:`~/libmaple/arm/bin` stays in your ``PATH``. + +So far, so good? +---------------- + +Great! Move on by :ref:`compiling a sample program <toolchain-test>`. + +.. rubric:: Footnotes + +.. [#fpackman] Some of these software packages might be available on + `MacPorts <http://www.macports.org/>`_ or `Homebrew + <http://mxcl.github.com/homebrew/>`_. The author had some bad + experiences with MacPorts a few years ago, though, and hasn't + touched a package manager on OS X since. Your mileage may vary. diff --git a/docs/source/unix-toolchain-win-setup.rst b/docs/source/unix-toolchain-win-setup.rst new file mode 100644 index 0000000..099e7fe --- /dev/null +++ b/docs/source/unix-toolchain-win-setup.rst @@ -0,0 +1,163 @@ +.. highlight:: sh + +.. _unix-toolchain-win-setup: + +Unix Toolchain Windows Setup +============================ + +This page contains instructions for setting up a Windows computer for +use with the :ref:`Unix toolchain <unix-toolchain>`. (Setup +instructions for :ref:`other operating systems <toolchain-setup>` are +also available.) + +These instructions have been tested successfully on Windows 7 Home +Premium. + +.. contents:: Contents + :local: + +Collect and Install Tools +------------------------- + +First, you'll need some tools. + +* `GitHub for Windows <http://windows.github.com/>`_: this is a GUI + for `Git`_, the version control system we use for :ref:`libmaple`. + + If you don't have one, you need to sign up for a (free) `GitHub + account <https://github.com/signup/free>`_. + + .. note:: If you use Git from the command line, you can clone + libmaple with:: + + $ git clone git://github.com/leaflabs/libmaple.git + + If you go this route, you don't need a GitHub account. + +* `Python`_: choose the **latest 2.7.x version**. (Python 3 works, but + you're on your own.) + +* `PySerial`_: Choose the latest **pyserial-x.y-win32.exe version**. + +Fetch ``libmaple`` and Compiler Toolchain +----------------------------------------- + +First, make a Git clone of the :ref:`libmaple` repository with the +following steps: + +1. **Run GitHub for Windows**, and **sign in** using your GitHub + account. +2. **Visit** `libmaple's GitHub page + <https://github.com/leaflabs/libmaple/>`_, and **sign in** to + GitHub in your web browser as well. +3. **Click on the "Clone in Windows" button** on libmaple's GitHub + page, which looks like this: + + .. figure:: /_static/img/github-clone-in-windows.png + + Your browser may prompt you about what to do when you click the + "Clone in Windows" button. Choose the option that launches the + GitHub for Windows application. + +Next, you'll need to get some cross-compilers and other tools for +building and uploading your programs: + +- `Download a .zip of the latest tools + <http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-win32.zip>`_. + +- Extract the .zip, and **move the extracted "arm" folder into the + libmaple repository's folder**. + + You can open the libmaple repository folder by right-clicking + libmaple in the main GitHub for Windows screen and choosing "open in + explorer": + + .. figure:: /_static/img/win7-github-open-in-explorer.png + :align: center + +Update your PATH +---------------- + +You'll next need to configure your system to use the various tools +you've downloaded and installed. Do that by adding the Python and +``arm\bin`` directories to your PATH environment variable. + +If you've never set environment variables before, this section +explains what to do. + +**Add Python to your PATH**: + + Start by navigating to the folder where Python is installed on your + system (this is probably ``C:\Python27``). Right click on the folder + address, then choose "Copy address as text": + + .. figure:: /_static/img/win7-copy-python-address.png + :align: center + + Next, open your environment variables window: from the Start/Windows + menu, right click on Computer, then choose Properties > Advanced + System Settings > Environment Variables. Under the "User variables + for YOUR_USERNAME", look for PATH. + + - If PATH is missing from the list, click "New...". + + Under "Variable Name", write PATH. Under "Variable value", paste + the Python address you just copied, and click OK. The result looks + like this: + + .. figure:: /_static/img/win7-python-path.png + :align: center + + - If PATH is present in the list, click on it and choose "Edit...". + + Go to the end of the "Variable value:" text box, type a semicolon + (the ``;`` character), and then paste the path you just + copied. Click OK. + + Test that this worked by running the Git Shell program that came with + GitHub for Windows, then running ``python`` at the command prompt. You + should get a Python interpreter that looks like this: + + .. figure:: /_static/img/win7-python-prompt.png + :align: center + + If that worked, then close the window. + +**Add compiler toolchain to your PATH**: + + Do this by adding the ``arm\bin`` directory (earlier instructions + had you move ``arm`` to the libmaple repository folder) to your PATH + environment variable in the same way you added Python. + + Copy the address of the ``arm\bin`` folder by right-clicking on it + after navigating to it: + + .. figure:: /_static/img/win7-copy-arm-bin-address.png + :align: center + + The PATH environment variable should exist from when you added + Python to it, so make sure you choose "Edit..." from the + environment variables window. Then paste the ``arm\bin`` address you + copied after typing a semicolon. The final result will look + something like this: + + .. figure:: /_static/img/win7-python-arm-bin-path.png + :align: center + + Click OK. + +So far, so good? +---------------- + +Great! Open a new Git Shell, then type this at the prompt and hit +return to get to the libmaple directory:: + + cd libmaple + +.. warning:: You must open a new Git Shell window. If you use a shell + that's already open, then the changes to PATH you just + made won't be available, and the instructions in the next + section won't work. + +Now you're ready to move on by :ref:`compiling a sample program +<toolchain-test>`. diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst new file mode 100644 index 0000000..769b8ec --- /dev/null +++ b/docs/source/unix-toolchain.rst @@ -0,0 +1,375 @@ +.. highlight:: sh + +.. _unix-toolchain: + +=========================== + Unix Toolchain Quickstart +=========================== + +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 <maple-ide-install>` instead. + +.. contents:: Contents + :local: + +Requirements +------------ + +We assume you've had success with the :ref:`Maple IDE <ide>` (this is +important on Windows, as this document doesn't cover :ref:`driver +installation <maple-ide-install-windows-drivers>`). + +At a minimum, you need: + +* Maple board +* Mini-B USB cable +* root (or Administrator) access to your computer. + +On Linux and OS X, you need to know how to use `bash +<http://www.gnu.org/software/bash/>`_, and how to edit your .bashrc. +Some experience using `GCC <http://gcc.gnu.org/>`_ and `make +<http://www.gnu.org/software/make/>`_ is recommended, but is not +required. + +.. _toolchain-linux-setup: +.. _toolchain-osx-setup: +.. _toolchain-win-setup: +.. _toolchain-setup: + +Setup +----- + +You first need to set up your computer by installing and configuring +various things. Don't fret! We've got detailed instructions, just for +you. + +* :ref:`Linux <unix-toolchain-linux-setup>` +* :ref:`OS X <unix-toolchain-osx-setup>` +* :ref:`Windows <unix-toolchain-win-setup>` + +Come back when you're ready. We'll wait. + +.. _toolchain-test: + +Test compilation +---------------- + +Test that you've installed all the compilation tools correctly by +running the following commands in your shell. + +Windows users: + + - Don't type the ``$``'s, just the parts that come after. + - First get to libmaple by opening a Git Shell, then running ``cd libmaple``. + - **Always type** ``cs-make`` **instead of** ``make``. + +Linux and OS X users: + + - Run these from the top-level libmaple directory. + +:: + + $ cp main.cpp.example main.cpp + $ make clean + $ make + +If all goes well, you should see a bunch of output, then something +like this:: + + Final Size: + text data bss dec hex filename + 13164 1704 552 15420 3c3c build/maple.elf + +Hurray! You've just compiled your first program for Maple. + +**Important: if you're not using Maple (Maple Mini, etc.), make sure +to read the following note before moving on**. + +You can now move on to :ref:`uploading a program <toolchain-upload>`, +or take a quick detour to learn :ref:`more about the build output +<toolchain-build-info>`. + +.. _toolchain-setting-board: + +.. note:: This tutorial assumes you're using a Maple. If you're + compiling for another board, you'll need to set a ``BOARD`` + environment variable appropriately. + + To get a list of values for ``BOARD``, run :: + + $ make list-boards + + For example, to compile for Maple Mini: + + * On OS X or Linux, run:: + + $ export BOARD=maple_mini + $ make + + * On Windows, set a new environment variable named ``BOARD`` to + value ``maple_mini``, then open a new Git Shell, and run ``cd + libmaple`` followed by ``cs-make`` as explained above. + + You can check that this worked by making sure that the final + program file is named ``build/maple_mini.elf`` instead of + ``maple.elf``:: + + Final Size: + text data bss dec hex filename + 16848 2696 704 20248 4f18 build/maple_mini.elf + + Other notes for OS X and Linux: + + - You can also use the following, but you'll need to write the + ``BOARD=maple_mini`` part every time you call ``make`` (for + ``make install``, etc.):: + + $ BOARD=maple_mini make + + - To make the board setting permanent, add this line to your + .bashrc:: + + export BOARD=maple_mini + +.. warning:: You must start from a clean build after each time you + change ``BOARD`` (advanced users: or ``MEMORY_TARGET``). For + example, if you compile a program for Maple, then you want to + compile another program for Maple Mini, you must run ``$ make + clean`` **before** you compile the second program. If you do not, + you will experience strange errors. + +.. _toolchain-build-info: + +Notes about the ``libmaple`` build +---------------------------------- + +These are just some miscellaneous notes that are good to know. Feel +free to skip reading this section. + +- The ``dec`` field at the end of the build output under ``Final + Size:`` gives the total program size in bytes. The ``text``, + ``data``, and ``bss`` fields respectively break down the size of the + program into `code <http://en.wikipedia.org/wiki/Code_segment>`_, + `initialized data <http://en.wikipedia.org/wiki/Data_segment>`_, and + `zero-valued data <http://en.wikipedia.org/wiki/.bss>`_. + +- The long list of object files above the ``Final Size`` shows similar + information on a per-file basis. You can use it to help slim down + programs that use too much space. + +- ``build/$BOARD.elf`` is the final build result (where ``BOARD`` is + ``maple``, ``maple_mini``, etc. :ref:`depending on your build + <toolchain-setting-board>`). + +- There are other files under ``build`` you may be interested in, like + disassembly and map files. + +- If you want quicker build times, you should check out our blog post, + `Making libmaple compile faster + <http://leaflabs.com/2012/08/2549/>`_. + +.. _toolchain-upload: + +Upload a program +---------------- + +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 <usb>`. + +* Linux: you need udev rules set up :ref:`as described in the setup + doc <toolchain-udev>`. + +* Windows: you need to :ref:`install the Maple's device drivers + <maple-ide-install-windows-drivers>`. + +* OS X: everything Just Works for you. Aren't you special? + +Plug in your Maple using a Mini-B USB cable, then run :: + + # Window users: as usual, use cs-make instead of make. + + $ 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 +<troubleshooting-perpetual-bootloader>`, restarting the Maple a couple +times, ``make clean``, etc. If nothing works, the `forum`_ is your +friend. + +.. _toolchain-serialusb: + +Communicate over USB-Serial +--------------------------- + +Now let's try out the interactive test session. You need to connect +to the board's serial port device file. + +* Linux: this looks like :file:`/dev/ttyACM*`. +* OS X: it looks like :file:`/dev/tty.usbmodem*`. +* Windows: it will be :file:`COMx`, where ``x`` is some number. + +Try using one of these to find out which it is:: + + # Linux + $ ls /dev/ttyACM* + + # OS X + $ ls /dev/tty.usbmodem* + + # Windows, works from libmaple directory + $ python support/scripts/win-list-com-ports.py + +To open up a session on Linux or OS X, run :: + + $ screen /dev/ttyXXX + +(On Windows, you will need to use a separate program, such as Maple +IDE's serial console or `PuTTY +<http://www.chiark.greenend.org.uk/~sgtatham/putty/>`_.) + +``screen`` will present you an empty terminal. Your board is waiting +for you to send it a command. Type ``h`` to print a list of commands; +type any command's letter to run it. + +.. highlight:: none + +Example output (for Maple):: + + > u + Hello World! + > b + Board information + ================= + * Clock speed (MHz): 72 + * BOARD_LED_PIN: 13 + * BOARD_BUTTON_PIN: 38 + * GPIO information (BOARD_NR_GPIO_PINS = 44): + ADC pins (15): 0, 1, 2, 3, 10, 11, 12, 15, 16, 17, 18, 19, 20, 27, 28 + PWM pins (15): 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 27, 28 + Used pins (7): 13, 38, 39, 40, 41, 42, 43`` + +.. highlight:: sh + +To exit the screen session, type :kbd:`C-a k` (control-a k) on Linux, +or :kbd:`C-a C-\\` (Control-a, followed by Control-backslash) on OS X, +and type ``y`` when prompted if you're sure. + +.. note:: + + 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: + +Start your own project +---------------------- + +So everything worked, and you want to start your own project? Great! +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 <toolchain-upload>`. + +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. + +There is also a page on `starting a project with the Unix toolchain +<http://wiki.leaflabs.com/index.php?title=Starting_A_Project_%28No_IDE%29>`_ +on the `LeafLabs wiki <http://wiki.leaflabs.com>`_ that you may find +useful. + +Get 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 do our best to keep the master libmaple branch on GitHub free from +broken or half-finished code, so don't be too scared running the +latest and greatest. If you do, please report any bugs or regressions! + +We keep releases of libmaple and the Maple IDE in lockstep, so any IDE +updates will have corresponding library updates. Our `blog +<http://leaflabs.com/blog/>`_ is the place to watch for major +releases; an `RSS feed <http://leaflabs.com/blog/feed/>`_ is +available. + +You can sign up for a free `GitHub <https://github.com/plans>`_ +account and `watch libmaple +<https://github.com/leaflabs/libmaple/watchers>`_ to receive +notifications about bleeding-edge development. + +.. _toolchain-openocd: + +(Optional) Upload/Debug with JTAG/SWD +------------------------------------- + +Advanced users will wish to use a JTAG (or SWD) dongle for uploading +and debugging their programs. A big advantage to this approach is that +it lets you use `GDB <http://www.gnu.org/software/gdb/>`_ to +single-step through your code, inspect variables, etc. + +You can build your projects for JTAG or SWD upload with the ``jtag`` +Makefile target. That is, instead of compiling with ``make``, compile +with :: + + # (This is equivalent to $ MEMORY_TARGET=jtag make) + $ make jtag + +Then use your favorite JTAG/SWD dongle and driver software to upload +the resulting program. An `ELF +<http://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_ +suitable for upload is in :file:`build/$BOARD.elf`; the raw binary you +can copy directly to address 0x0 is :file:`build/$BOARD.bin`. + +.. warning:: Uploading code built with the ``jtag`` target will + overwrite the :ref:`bootloader <bootloader>`. This is a good thing + -- since you're using another upload method, this lets you use the + Flash and RAM the bootloader ordinarily reserves for itself. You + can always :ref:`reflash the bootloader <bootloader-reflashing>` + later. + +While LeafLabs doesn't officially support any particular way of using +JTAG with Maple, there is a `JTAG How-To +<http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ on the +`LeafLabs wiki <http://wiki.leaflabs.com>`_ that you may find useful. + +.. _toolchain-exuberantly: + +Go forth exuberantly! +--------------------- + +Let us know what you come up with! Mention `@leaflabs on Twitter +<http://twitter.com/#!/leaflabs>`_, post in the `forum`_, join the the +#leafblowers IRC channel on `freenode +<http://freenode.net/irc_servers.shtml>`_, whatever. We love projects! diff --git a/docs/source/usart.rst b/docs/source/usart.rst new file mode 100644 index 0000000..dbbc81c --- /dev/null +++ b/docs/source/usart.rst @@ -0,0 +1,62 @@ +.. _usart: + +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: + +.. _usart-circuit: + +Hardware/Circuit Design +----------------------- + +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. + +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 +the :ref:`Serial Ports <lang-serial>` 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 <maple-usart-map>` +* :ref:`Maple RET6 Edition <maple-ret6-usart-map>` +* :ref:`Maple Mini <maple-mini-usart-map>` +* :ref:`Maple Native Beta <maple-native-b-usart-map>` + +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 USART ports with an FT232R-based +USB-serial converter at up to 115200 baud. Higher speeds should +certainly be possible. + +Recommended Reading +------------------- + +* `Wikipedia article on Universal Asynchronous Receiver/Transmitter + (USART) + <http://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter>`_ +* `Arduino Serial reference + <http://arduino.cc/en/Reference/Serial>`_ +* ST `Reference Manual RM0008 + <http://www.st.com/web/en/resource/technical/document/reference_manual/CD00171190.pdf>`_ + (PDF), Chapter 27. +* `Serial and UART Tutorial + <http://www.freebsd.org/doc/en/articles/serial-uart/>`_ (written for + FreeBSD, but contains a large amount of general information). diff --git a/docs/source/usb.rst b/docs/source/usb.rst new file mode 100644 index 0000000..80c40ca --- /dev/null +++ b/docs/source/usb.rst @@ -0,0 +1,49 @@ +.. highlight:: cpp + +.. _usb: + +USB +=== + +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 +<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 <lang-serialusb>` reference. + +The SerialUSB channel is used with the :ref:`Maple bootloader +<bootloader>` to reprogram the board: a :ref:`magic sequence of +control line toggles and transmitted data <bootloader-rev3>` 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() <lang-serialusb-end>`). A +solution to the second problem is the use of :ref:`perpetual +bootloader mode <troubleshooting-perpetual-bootloader>`. + +Recommended Reading +------------------- + +* `USB in a Nutshell <http://www.beyondlogic.org/usbnutshell/usb1.shtml>`_, an overview from Beyond Logic +* `USB made simple <http://www.usbmadesimple.co.uk/>`_, an illustrated series of articles on USB +* The `USB 2.0 Specification <http://www.usb.org/developers/docs/>`_ (`direct link <http://www.usb.org/developers/docs/usb_20_070113.zip>`_) +* `Embedded USB - a brief tutorial <http://www.computer-solutions.co.uk/info/Embedded_tutorials/usb_tutorial.htm>`_ +* `Wikipedia article on Universal Serial Bus (USB) <http://en.wikipedia.org/wiki/Universal_Serial_Bus>`_ +* Linux Kernel documentation for `USB ACM <http://www.kernel.org/doc/Documentation/usb/acm.txt>`_ and `USB Serial <http://www.kernel.org/doc/Documentation/usb/usb-serial.txt>`_ +* `USB Glossary of Terms <http://belcarra.com/usb_glossary.html>`_ +* ST documentation: + * Reference Manual `RM0008 + <http://www.st.com/web/en/resource/technical/document/reference_manual/CD00171190.pdf>`_ + (PDF), Chapter 23, "Universal serial bus full-speed device + interface" + * Programming Manual `PM0056 + <http://www.st.com/st-web-ui/static/active/en/resource/technical/document/programming_manual/CD00228163.pdf>`_ + (PDF; assembly language and register reference) diff --git a/docs/source/whats-new.rst b/docs/source/whats-new.rst new file mode 100644 index 0000000..c7d10c5 --- /dev/null +++ b/docs/source/whats-new.rst @@ -0,0 +1,81 @@ +.. highlight:: c + +What's New +========== + +.. FIXME [RELEASE] finish. + +This page tracks updates to libmaple and MapleIDE. + +.. contents:: + :local: + :depth: 1 + +v0.0.13 +------- + +.. We started doing this as we updated the docs on 29 Jun 2012, so +.. updates before then need to be pulled from libmaple's Git logs. + +**General Changes** + +- Additional STM32 support: for this release, libmaple was taught + how to target STM32F1 value line (thanks to Anton Eltchaninov) and + STM32F2 series microcontrollers. It learned a huge bag of new + tricks as a result, so this list is only a summary of the most + important changes. + +- New include style: You should now include libmaple and Wirish + headers like this (respectively):: + + #include <libmaple/libmaple.h> + #include <wirish/wirish.h> + + The old include style (e.g. ``#include "libmaple.h"``) is now + **deprecated**, and will **break in the next release**. This is more + standard usage for libraries, and was necessary to e.g. allow for + implementing a Wiring/Arduino-style SPI library (which is included + as ``#include "SPI.h"`` and clashes with :ref:`libmaple-spi` on + case-insensitive filesystems like OS X's). + +- :ref:`Windows instructions <toolchain-win-setup>` for the + :ref:`unix-toolchain`. + +**Wirish** + +- Wire I2C library: New, improved, and more Arduino-compatible + :ref:`Wire <libs-wire>` library, thanks to Trystan Jones. + +**libmaple proper** + +Better documentation: The old documentation for libmaple's C layer did +little more than list the Doxygen comments in the source code. It now +includes explanatory material and usage notes. See +:ref:`libmaple-apis`. + +.. FIXME [0.0.13] this is ugly + +Major changes by header follow. + +.. list-table:: + :header-rows: 1 + :widths: 1 10 + + * - Header + - Changes + + * - :ref:`libmaple-rcc` + - :ref:`rcc_clk_init() <rcc-rcc_clk_init>` is deprecated. Use + :ref:`rcc_configure_pll() <libmaple-rcc-rcc_configure_pll>` as + the basis for a portable replacement; see the + ``rcc_clk_init()`` docs for a porting guide. + + * - :ref:`libmaple-libmaple_types` + - Various new attributes and type qualifiers. + + * - :ref:`libmaple-adc` + - New :ref:`adc_enable_single_swstart() + <adc-adc_enable_single_swstart>` and :ref:`adc_config_gpio() + <adc-adc_config_gpio>`, for portably enabling ADC peripherals + and their associated pins for use with :ref:`adc_read() + <adc-adc_read>`. diff --git a/docs/tmpl/libmaple-proper-page.rst.tmpl b/docs/tmpl/libmaple-proper-page.rst.tmpl new file mode 100644 index 0000000..c00dd63 --- /dev/null +++ b/docs/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 |
