diff options
Diffstat (limited to 'source')
223 files changed, 0 insertions, 21116 deletions
diff --git a/source/_static/.gitignore b/source/_static/.gitignore deleted file mode 100644 index e69de29..0000000 --- a/source/_static/.gitignore +++ /dev/null diff --git a/source/_static/breathe.css b/source/_static/breathe.css deleted file mode 100644 index d86028c..0000000 --- a/source/_static/breathe.css +++ /dev/null @@ -1 +0,0 @@ -/* This is a dummy css file to prevent 404 errors */ diff --git a/source/_static/img/blinky-to-flash.png b/source/_static/img/blinky-to-flash.png Binary files differdeleted file mode 100644 index 0320c5b..0000000 --- a/source/_static/img/blinky-to-flash.png +++ /dev/null diff --git a/source/_static/img/blinky.png b/source/_static/img/blinky.png Binary files differdeleted file mode 100644 index bda4cee..0000000 --- a/source/_static/img/blinky.png +++ /dev/null diff --git a/source/_static/img/button-new.png b/source/_static/img/button-new.png Binary files differdeleted file mode 100644 index 3fd98be..0000000 --- a/source/_static/img/button-new.png +++ /dev/null diff --git a/source/_static/img/button-open.png b/source/_static/img/button-open.png Binary files differdeleted file mode 100644 index 466fc10..0000000 --- a/source/_static/img/button-open.png +++ /dev/null diff --git a/source/_static/img/button-save.png b/source/_static/img/button-save.png Binary files differdeleted file mode 100644 index 7eba286..0000000 --- a/source/_static/img/button-save.png +++ /dev/null diff --git a/source/_static/img/button-serial-monitor.png b/source/_static/img/button-serial-monitor.png Binary files differdeleted file mode 100644 index aec9741..0000000 --- a/source/_static/img/button-serial-monitor.png +++ /dev/null diff --git a/source/_static/img/button-stop.png b/source/_static/img/button-stop.png Binary files differdeleted file mode 100644 index 4812ae9..0000000 --- a/source/_static/img/button-stop.png +++ /dev/null diff --git a/source/_static/img/button-upload.png b/source/_static/img/button-upload.png Binary files differdeleted file mode 100644 index 0f41eeb..0000000 --- a/source/_static/img/button-upload.png +++ /dev/null diff --git a/source/_static/img/button-verify.png b/source/_static/img/button-verify.png Binary files differdeleted file mode 100644 index 95abeb8..0000000 --- a/source/_static/img/button-verify.png +++ /dev/null diff --git a/source/_static/img/codeblocks_build.png b/source/_static/img/codeblocks_build.png Binary files differdeleted file mode 100644 index c98bcdc..0000000 --- a/source/_static/img/codeblocks_build.png +++ /dev/null diff --git a/source/_static/img/codeblocks_makefile.png b/source/_static/img/codeblocks_makefile.png Binary files differdeleted file mode 100644 index a0ef21f..0000000 --- a/source/_static/img/codeblocks_makefile.png +++ /dev/null diff --git a/source/_static/img/codeblocks_maketargets.png b/source/_static/img/codeblocks_maketargets.png Binary files differdeleted file mode 100644 index bbb68cb..0000000 --- a/source/_static/img/codeblocks_maketargets.png +++ /dev/null diff --git a/source/_static/img/codeblocks_newproject.png b/source/_static/img/codeblocks_newproject.png Binary files differdeleted file mode 100644 index 8d08d1f..0000000 --- a/source/_static/img/codeblocks_newproject.png +++ /dev/null diff --git a/source/_static/img/github-clone-in-windows.png b/source/_static/img/github-clone-in-windows.png Binary files differdeleted file mode 100644 index 41d76d1..0000000 --- a/source/_static/img/github-clone-in-windows.png +++ /dev/null diff --git a/source/_static/img/ide-blinky.png b/source/_static/img/ide-blinky.png Binary files differdeleted file mode 100644 index 3cccdb4..0000000 --- a/source/_static/img/ide-blinky.png +++ /dev/null diff --git a/source/_static/img/jtag-wiring.png b/source/_static/img/jtag-wiring.png Binary files differdeleted file mode 100644 index 8f31f99..0000000 --- a/source/_static/img/jtag-wiring.png +++ /dev/null diff --git a/source/_static/img/osx-network-prefs-unconfigured.png b/source/_static/img/osx-network-prefs-unconfigured.png Binary files differdeleted file mode 100644 index 70d2fa0..0000000 --- a/source/_static/img/osx-network-prefs-unconfigured.png +++ /dev/null diff --git a/source/_static/img/osx-unconfigured-popup.png b/source/_static/img/osx-unconfigured-popup.png Binary files differdeleted file mode 100644 index a43ad57..0000000 --- a/source/_static/img/osx-unconfigured-popup.png +++ /dev/null diff --git a/source/_static/img/round_logo_32x32.ico b/source/_static/img/round_logo_32x32.ico Binary files differdeleted file mode 100644 index 29fb2bf..0000000 --- a/source/_static/img/round_logo_32x32.ico +++ /dev/null diff --git a/source/_static/img/round_logo_60x60.png b/source/_static/img/round_logo_60x60.png Binary files differdeleted file mode 100644 index dacd36a..0000000 --- a/source/_static/img/round_logo_60x60.png +++ /dev/null diff --git a/source/_static/img/serial-monitor.png b/source/_static/img/serial-monitor.png Binary files differdeleted file mode 100644 index 6162dab..0000000 --- a/source/_static/img/serial-monitor.png +++ /dev/null diff --git a/source/_static/img/serial-port-mac.png b/source/_static/img/serial-port-mac.png Binary files differdeleted file mode 100644 index b3a1989..0000000 --- a/source/_static/img/serial-port-mac.png +++ /dev/null diff --git a/source/_static/img/serial-port-ubuntu.png b/source/_static/img/serial-port-ubuntu.png Binary files differdeleted file mode 100644 index 8038e41..0000000 --- a/source/_static/img/serial-port-ubuntu.png +++ /dev/null diff --git a/source/_static/img/serial-port-win.png b/source/_static/img/serial-port-win.png Binary files differdeleted file mode 100644 index 90dc1c4..0000000 --- a/source/_static/img/serial-port-win.png +++ /dev/null diff --git a/source/_static/img/upload-button.png b/source/_static/img/upload-button.png Binary files differdeleted file mode 100644 index 20a663f..0000000 --- a/source/_static/img/upload-button.png +++ /dev/null diff --git a/source/_static/img/verify-success.png b/source/_static/img/verify-success.png Binary files differdeleted file mode 100644 index 6928674..0000000 --- a/source/_static/img/verify-success.png +++ /dev/null diff --git a/source/_static/img/verify_button.png b/source/_static/img/verify_button.png Binary files differdeleted file mode 100644 index 37100db..0000000 --- a/source/_static/img/verify_button.png +++ /dev/null diff --git a/source/_static/img/win7-copy-arm-bin-address.png b/source/_static/img/win7-copy-arm-bin-address.png Binary files differdeleted file mode 100644 index a3886d1..0000000 --- a/source/_static/img/win7-copy-arm-bin-address.png +++ /dev/null diff --git a/source/_static/img/win7-copy-python-address.png b/source/_static/img/win7-copy-python-address.png Binary files differdeleted file mode 100644 index 34d3022..0000000 --- a/source/_static/img/win7-copy-python-address.png +++ /dev/null diff --git a/source/_static/img/win7-github-open-in-explorer.png b/source/_static/img/win7-github-open-in-explorer.png Binary files differdeleted file mode 100644 index 8320a90..0000000 --- a/source/_static/img/win7-github-open-in-explorer.png +++ /dev/null diff --git a/source/_static/img/win7-python-arm-bin-path.png b/source/_static/img/win7-python-arm-bin-path.png Binary files differdeleted file mode 100644 index 8dcc8ed..0000000 --- a/source/_static/img/win7-python-arm-bin-path.png +++ /dev/null diff --git a/source/_static/img/win7-python-path.png b/source/_static/img/win7-python-path.png Binary files differdeleted file mode 100644 index 8898a9e..0000000 --- a/source/_static/img/win7-python-path.png +++ /dev/null diff --git a/source/_static/img/win7-python-prompt.png b/source/_static/img/win7-python-prompt.png Binary files differdeleted file mode 100644 index 27ae62a..0000000 --- a/source/_static/img/win7-python-prompt.png +++ /dev/null diff --git a/source/_static/index-style.css b/source/_static/index-style.css deleted file mode 100644 index d7c42b3..0000000 --- a/source/_static/index-style.css +++ /dev/null @@ -1,19 +0,0 @@ -/* 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/source/_static/leaflabs-docs.css b/source/_static/leaflabs-docs.css deleted file mode 100644 index 18f5bcc..0000000 --- a/source/_static/leaflabs-docs.css +++ /dev/null @@ -1 +0,0 @@ -/* Any custom CSS you want applied goes here */ diff --git a/source/_templates/.gitignore b/source/_templates/.gitignore deleted file mode 100644 index e69de29..0000000 --- a/source/_templates/.gitignore +++ /dev/null diff --git a/source/_templates/indexcontent.html b/source/_templates/indexcontent.html deleted file mode 100644 index a043f8a..0000000 --- a/source/_templates/indexcontent.html +++ /dev/null @@ -1,117 +0,0 @@ -{# 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/source/_templates/layout.html b/source/_templates/layout.html deleted file mode 100644 index 2fd81ce..0000000 --- a/source/_templates/layout.html +++ /dev/null @@ -1,11 +0,0 @@ -{% 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/source/adc.rst b/source/adc.rst deleted file mode 100644 index 937b178..0000000 --- a/source/adc.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. _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/source/arduino-cc-attribution.txt b/source/arduino-cc-attribution.txt deleted file mode 100644 index ad1c1e0..0000000 --- a/source/arduino-cc-attribution.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. 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/source/arduino-compatibility.rst b/source/arduino-compatibility.rst deleted file mode 100644 index f7d3210..0000000 --- a/source/arduino-compatibility.rst +++ /dev/null @@ -1,275 +0,0 @@ -.. 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/source/arm-gcc.rst b/source/arm-gcc.rst deleted file mode 100644 index 30667a2..0000000 --- a/source/arm-gcc.rst +++ /dev/null @@ -1,107 +0,0 @@ - -.. _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/source/bootloader.rst b/source/bootloader.rst deleted file mode 100644 index 23b0448..0000000 --- a/source/bootloader.rst +++ /dev/null @@ -1,750 +0,0 @@ -.. 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/source/conf.py b/source/conf.py deleted file mode 100644 index f4a9bbb..0000000 --- a/source/conf.py +++ /dev/null @@ -1,283 +0,0 @@ -# -*- coding: utf-8 -*- -# -# libmaple documentation build configuration file, created by -# sphinx-quickstart on Thu Oct 7 06:42:30 2010. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os -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/source/contents.rst b/source/contents.rst deleted file mode 100644 index 7be7aec..0000000 --- a/source/contents.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _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/source/epilog.rst b/source/epilog.rst deleted file mode 100644 index b548001..0000000 --- a/source/epilog.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. 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/source/external-interrupts.rst b/source/external-interrupts.rst deleted file mode 100644 index 209d5af..0000000 --- a/source/external-interrupts.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. 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/source/faq.rst b/source/faq.rst deleted file mode 100644 index bd155ae..0000000 --- a/source/faq.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. 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/source/fsmc.rst b/source/fsmc.rst deleted file mode 100644 index c8f0125..0000000 --- a/source/fsmc.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _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/source/gpio.rst b/source/gpio.rst deleted file mode 100644 index caaae3d..0000000 --- a/source/gpio.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _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/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst deleted file mode 100644 index c28211d..0000000 --- a/source/hardware/maple-mini.rst +++ /dev/null @@ -1,402 +0,0 @@ -.. _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/source/hardware/maple-native-beta.rst b/source/hardware/maple-native-beta.rst deleted file mode 100644 index bdfd216..0000000 --- a/source/hardware/maple-native-beta.rst +++ /dev/null @@ -1,605 +0,0 @@ -.. 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/source/hardware/maple-native.rst b/source/hardware/maple-native.rst deleted file mode 100644 index 79115fc..0000000 --- a/source/hardware/maple-native.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _hardware-maple-native: - -Maple Native -============ - -Stub. diff --git a/source/hardware/maple-ret6.rst b/source/hardware/maple-ret6.rst deleted file mode 100644 index 3d2d037..0000000 --- a/source/hardware/maple-ret6.rst +++ /dev/null @@ -1,466 +0,0 @@ -.. 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/source/hardware/maple.rst b/source/hardware/maple.rst deleted file mode 100644 index b187115..0000000 --- a/source/hardware/maple.rst +++ /dev/null @@ -1,618 +0,0 @@ -.. 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/source/i2c.rst b/source/i2c.rst deleted file mode 100644 index a206ed4..0000000 --- a/source/i2c.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. _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/source/ide.rst b/source/ide.rst deleted file mode 100644 index e6d49fc..0000000 --- a/source/ide.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. _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/source/jtag.rst b/source/jtag.rst deleted file mode 100644 index caba223..0000000 --- a/source/jtag.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. 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/source/lang/api/abs.rst b/source/lang/api/abs.rst deleted file mode 100644 index d9f1ca3..0000000 --- a/source/lang/api/abs.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. highlight:: cpp - -.. _lang-abs: - - -abs() -====== - -(Macro) computes the absolute value of a number. - -Syntax ------- - -:: - - abs(x) - -Parameters ----------- - -**x**: the number. - -Returns -------- - -**x**: if **x** is greater than or equal to 0. - -**-x**: if **x** is less than 0. - -Warning -------- - -Because of the way ``abs()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - abs(a++); // avoid this - yields incorrect results - - abs(a); // use this instead - - a++; // keep other operations outside abs() - - -Arduino Compatibility ---------------------- - -Maple's implementation of ``abs()`` is compatible with Arduino. - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/analogread.rst b/source/lang/api/analogread.rst deleted file mode 100644 index 6665a94..0000000 --- a/source/lang/api/analogread.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. 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/source/lang/api/analogwrite.rst b/source/lang/api/analogwrite.rst deleted file mode 100644 index 0169976..0000000 --- a/source/lang/api/analogwrite.rst +++ /dev/null @@ -1,181 +0,0 @@ -.. 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/source/lang/api/assert.rst b/source/lang/api/assert.rst deleted file mode 100644 index 76330b6..0000000 --- a/source/lang/api/assert.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. highlight:: cpp - -.. _lang-assert: - -``ASSERT(...)`` -=============== - -ASSERT() can be very useful for basic program debugging. It accepts a -boolean; for example:: - - ASSERT(state == WAIT); - -Zero is false and any other number is true. If the boolean is true, -the assertion passes and the program continues as usual. If it is -false, the assertion fails: the program is halted, debug information -is printed to USART2, and the status LED begins to throb (it's -noticeably different from blinking). The debug information is printed -at 9600 baud and consists of the filename and line number where the -ASSERT() failed. - -Including assertions in a program increases the program size. When -using libmaple **from the command line only**, they can be disabled by -making the definition :: - - #define DEBUG_LEVEL DEBUG_NONE - -before including either wirish.h or libmaple.h. In this case, all -assertions will pass without any lost clock cycles. Note that this -will **not work in the IDE**; even with this definition, assertions -will still be enabled. diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst deleted file mode 100644 index 58e4764..0000000 --- a/source/lang/api/attachinterrupt.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. 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/source/lang/api/bit.rst b/source/lang/api/bit.rst deleted file mode 100644 index 3df042c..0000000 --- a/source/lang/api/bit.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _lang-bit: - -bit() -===== - -(Macro) Computes the value of an (unsigned) integer with the specified -bit set (``bit(0)`` is 1, ``bit(1)`` is 2, ``bit(2)`` is 4, then 8, -16, 32, etc.). - -Syntax ------- - -``bit(n)`` - -Parameters ----------- - -* **n** the bit to set. - -Value ------ - -The value of an integer with the given bit set. - -Arduino Compatibility ---------------------- - -The Maple implementation of ``bit()`` is compatible with Arduino. - -See Also --------- - -- :ref:`lang-bitread` -- :ref:`lang-bitwrite` -- :ref:`lang-bitset` -- :ref:`lang-bitclear` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bitclear.rst b/source/lang/api/bitclear.rst deleted file mode 100644 index f487059..0000000 --- a/source/lang/api/bitclear.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _lang-bitclear: - -bitClear() -========== - -(Macro) Clears (writes a 0 to) a bit of a numeric variable. - -Syntax ------- - -``bitClear(x, n)`` - -Parameters ----------- - -* **x** the numeric variable whose bit to clear - -* **n** which bit to clear, starting at 0 for the least-significant - (rightmost) bit - -Returns -------- - -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/source/lang/api/bitread.rst b/source/lang/api/bitread.rst deleted file mode 100644 index fd9fbbe..0000000 --- a/source/lang/api/bitread.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _lang-bitread: - -bitRead() -========= - -(Macro) Gets the value of a bit in a number. - -Syntax ------- - -``bitRead(x, n)`` - -Parameters ----------- - -* **x** the number from which to read the bit. - -* **n** which bit to read, starting at 0 for the least-significant - (rightmost) bit - -Value ------ - -The value of the bit (0 or 1). - -Arduino Compatibility ---------------------- - -The Maple implementation of ``bitRead`` is compatible with Arduino. - -See Also --------- - -- :ref:`lang-bit` -- :ref:`lang-bitwrite` -- :ref:`lang-bitset` -- :ref:`lang-bitclear` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bitset.rst b/source/lang/api/bitset.rst deleted file mode 100644 index 83ab5f8..0000000 --- a/source/lang/api/bitset.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _lang-bitset: - -bitSet() -======== - -(Macro) Sets (writes a 1 to) a bit of a numeric variable. - -Syntax ------- - -``bitSet(x, n)`` - -Parameters ----------- - -* **x** the numeric variable whose bit to set - -* **n** which bit to set, starting at 0 for the least-significant - (rightmost) bit - -Value ------ - -None. - -Arduino Compatibility ---------------------- - -The Maple implementation of bitSet is compatible with Arduino. - -See Also --------- - -- :ref:`lang-bit` -- :ref:`lang-bitread` -- :ref:`lang-bitwrite` -- :ref:`lang-bitclear` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/bitwrite.rst b/source/lang/api/bitwrite.rst deleted file mode 100644 index 6106545..0000000 --- a/source/lang/api/bitwrite.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. highlight:: cpp - -.. _lang-bitwrite: - -bitWrite() -========== - -(Macro) Writes a bit of a numeric variable. - -Syntax ------- - -:: - - bitWrite(x, n, b) - -Parameters ----------- - -**x**: the numeric variable whose bit to write. - -**n**: which bit of the number to write, starting at 0 for the -least-significant (rightmost) bit. - -**b**: the value to write to the bit (0 or 1). - -Returns -------- - -Nothing. - -Arduino Compatibility ---------------------- - -Maple's 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/source/lang/api/board-values.rst b/source/lang/api/board-values.rst deleted file mode 100644 index d944c8d..0000000 --- a/source/lang/api/board-values.rst +++ /dev/null @@ -1,189 +0,0 @@ -.. 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/source/lang/api/boardusespin.rst b/source/lang/api/boardusespin.rst deleted file mode 100644 index 126c4a0..0000000 --- a/source/lang/api/boardusespin.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. 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/source/lang/api/constants.rst b/source/lang/api/constants.rst deleted file mode 100644 index 6f69dfe..0000000 --- a/source/lang/api/constants.rst +++ /dev/null @@ -1,318 +0,0 @@ -.. _lang-constants: - -Constants -========= - -Constants are like predefined variables, whose values can't -change. They are used to make the programs easier to read and modify. -This page describes the most commonly used constants. - -.. contents:: Contents - :local: - -.. _lang-constants-bool: - -Boolean Constants ------------------ - -There are two constants used to represent truth and falsity: ``true``, -and ``false``. - -.. _lang-constants-false: - -false -^^^^^ - -``false`` is the false ``bool`` value. An integer which is 0 evaluates -to ``false`` as a boolean. - -.. _lang-constants-true: - -true -^^^^ - -``true`` is the true ``bool`` value. As an integer, ``true`` is often -said to be 1. This is correct in the sense that ``true`` evaluates to -1 as an integer. However, any integer which is *non-zero* is ``true`` -as a :ref:`bool <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/source/lang/api/constrain.rst b/source/lang/api/constrain.rst deleted file mode 100644 index 28af1e3..0000000 --- a/source/lang/api/constrain.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. highlight:: cpp - -.. _lang-constrain: - -constrain() -=========== - -(Macro) Constrains a number to be within a range. - -Syntax ------- - -:: - - constrain(x, a, b) - - -Parameters ----------- - -**x**: the number to constrain - -**a**: the lower end of the range - -**b**: the upper end of the range - -Returns -------- - -**x**: if **x** is between **a** and **b** - -**a**: if **x** is less than **a** - -**b**: if **x** is greater than **b** - -Example -------- - -:: - - // limits range of sensor values to between 10 and 150: - sensVal = constrain(sensVal, 10, 150); - - -Warning -------- - -Because of the way ``constrain()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - constrain(x,a++,b); // avoid this - yields incorrect results - - constrain(x,a,b); // use this instead- - a++; // keep other math outside constrain() - -Arduino Compatibility ---------------------- - -Maple's implementation of ``constrain()`` is compatible with Arduino. - -See Also --------- - -- :ref:`min() <lang-min>` -- :ref:`max() <lang-max>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/cos.rst b/source/lang/api/cos.rst deleted file mode 100644 index c340f09..0000000 --- a/source/lang/api/cos.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _lang-cos: - -cos() -===== - -Calculates the cosine of an angle. - -Library Documentation ---------------------- - -.. doxygenfunction:: cos - -Arduino Compatibility ---------------------- - -The Maple ``cos()`` implementation is compatible with Arduino. - -Note that the Maple implementation comes from `newlib -<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/source/lang/api/delay.rst b/source/lang/api/delay.rst deleted file mode 100644 index 30bd436..0000000 --- a/source/lang/api/delay.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. highlight:: cpp - -.. _lang-delay: - -delay() -======= - -Pauses the program for at least a given number of milliseconds. (There -are 1000 milliseconds in a second.) - -Library Documentation ---------------------- - -.. doxygenfunction:: delay - - -Discussion ----------- - -While it is easy to create a blinking LED with the ``delay()`` -function, and many sketches use short delays for such tasks as switch -debouncing, the use of ``delay()`` in a sketch has significant -drawbacks. No other reading of sensors, mathematical calculations, or -pin manipulation can go on during the delay function, so in effect, it -brings most other activity to a halt. For alternative approaches to -controlling timing see the :ref:`millis() <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/source/lang/api/delaymicroseconds.rst b/source/lang/api/delaymicroseconds.rst deleted file mode 100644 index 7078660..0000000 --- a/source/lang/api/delaymicroseconds.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. highlight:: cpp - -.. _lang-delaymicroseconds: - -delayMicroseconds() -=================== - -Pauses the program for the amount of time (in microseconds) -specified as parameter. There are a thousand microseconds in a -millisecond, and a million microseconds in a second. - -Library Documentation ---------------------- - -.. doxygenfunction:: delayMicroseconds - - -Example -------- - -The following example configures pin number 8 to work as an output -pin, and sends a train of pulses with a period of roughly 100 -microseconds:: - - int outPin = 8; - - void setup() { - pinMode(outPin, OUTPUT); // sets the digital pin as output - } - - void loop() { - digitalWrite(outPin, HIGH); // sets the pin on - delayMicroseconds(50); // pauses for 50 microseconds - digitalWrite(outPin, LOW); // sets the pin off - delayMicroseconds(50); // pauses for 50 microseconds - } - - -Caveats and Known Issues ------------------------- - -The longest time ``delayMicroseconds()`` can delay is bounded by its -argument type and the STM32 clock rate to be (2^32 - 1) / 12 -microseconds, or less than 6 minutes. For longer pauses, use of -:ref:`lang-delay` is possible. - -Arduino Compatibility ---------------------- - -While we have made every effort we could to ensure that the timing of -``delayMicroseconds()`` is as accurate as possible, we cannot -guarantee it will behave as the Arduino implementation down to the -microsecond, especially for smaller values of ``us``. - -See Also --------- - -- :ref:`millis <lang-millis>` -- :ref:`micros <lang-micros>` -- :ref:`delay <lang-delay>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/detachinterrupt.rst b/source/lang/api/detachinterrupt.rst deleted file mode 100644 index 6eb8e53..0000000 --- a/source/lang/api/detachinterrupt.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _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/source/lang/api/digitalread.rst b/source/lang/api/digitalread.rst deleted file mode 100644 index 03ccd7f..0000000 --- a/source/lang/api/digitalread.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. 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/source/lang/api/digitalwrite.rst b/source/lang/api/digitalwrite.rst deleted file mode 100644 index bae8db9..0000000 --- a/source/lang/api/digitalwrite.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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/source/lang/api/disabledebugports.rst b/source/lang/api/disabledebugports.rst deleted file mode 100644 index 283cdbf..0000000 --- a/source/lang/api/disabledebugports.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. 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/source/lang/api/enabledebugports.rst b/source/lang/api/enabledebugports.rst deleted file mode 100644 index bee2b0a..0000000 --- a/source/lang/api/enabledebugports.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. 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/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst deleted file mode 100644 index a44a65f..0000000 --- a/source/lang/api/hardwarespi.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. 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/source/lang/api/hardwaretimer.rst b/source/lang/api/hardwaretimer.rst deleted file mode 100644 index b919e52..0000000 --- a/source/lang/api/hardwaretimer.rst +++ /dev/null @@ -1,345 +0,0 @@ -.. 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/source/lang/api/highbyte.rst b/source/lang/api/highbyte.rst deleted file mode 100644 index 4cb6f9b..0000000 --- a/source/lang/api/highbyte.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. highlight:: cpp - -.. _lang-highbyte: - -highByte() -========== - -(Macro) Extracts the second lowest byte of an integral data type. - -.. warning:: This macro is provided for compatibility with Arduino - only. It returns the second-least significant byte in an integral - value. It makes sense to call this the "high" byte on a 16-bit - ``int`` microcontroller like the Atmel chips on Arduinos, but it - makes no sense at all on a 32-bit microcontroller like the STM32s - in the Maple line. - - In short: we provide this so that existing Arduino code works as - expected, but **strongly discourage its use** in new programs. - -Syntax ------- - -:: - - highByte(x) - -Parameters ----------- - -**x**: a value of any integral type. - -Returns -------- - -Second lowest byte in **x**. - -Example -------- - -:: - - int x = 0xDEADBEEF; - SerialUSB.println(x, HEX); // prints "BE" - -Arduino Compatibility ---------------------- - -The Maple version of ``highByte()`` is compatible with Arduino. - -See Also --------- - -- :ref:`lowByte() <lang-lowbyte>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/interrupts.rst b/source/lang/api/interrupts.rst deleted file mode 100644 index 58fd2cc..0000000 --- a/source/lang/api/interrupts.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. 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/source/lang/api/isbuttonpressed.rst b/source/lang/api/isbuttonpressed.rst deleted file mode 100644 index 8c350b9..0000000 --- a/source/lang/api/isbuttonpressed.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _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/source/lang/api/loop.rst b/source/lang/api/loop.rst deleted file mode 100644 index c2a5097..0000000 --- a/source/lang/api/loop.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. 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/source/lang/api/lowbyte.rst b/source/lang/api/lowbyte.rst deleted file mode 100644 index c513711..0000000 --- a/source/lang/api/lowbyte.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _lang-lowbyte: - -lowByte() -========= - -Extracts the low-order (rightmost) byte of a variable (e.g. a -word). - -Syntax ------- - -lowByte(x) - -Parameters ----------- - -**x**: a value of any type. However, if a non-integral type is used, -the results will be strange. - -Returns -------- - -The low byte's value (this will be between 0 and 255). - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/map.rst b/source/lang/api/map.rst deleted file mode 100644 index 69661a0..0000000 --- a/source/lang/api/map.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. highlight:: cpp - -.. _lang-map: - -map() -===== - -Re-maps a number from one range to another. - -.. contents:: Contents - :local: - -Library Documentation ---------------------- - -.. doxygenfunction:: map - -Discussion ----------- - -``map()`` does not constrain values to within the range, because -out-of-range values are sometimes intended and useful. The -:ref:`constrain() <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/source/lang/api/max.rst b/source/lang/api/max.rst deleted file mode 100644 index d356f08..0000000 --- a/source/lang/api/max.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. highlight:: cpp - -.. _lang-max: - -max() -===== - -(Macro) Calculates the maximum of two numbers. - -Syntax ------- - -:: - - max(x, y) - -Parameters ----------- - -**x**: the first number; may be any number or numeric expression. - -**y**: the second number; may be any number or numeric expression. - - -Returns -------- - -The larger of the two parameter values. - -Example -------- - -:: - - sensVal = max(senVal, 20); // assigns sensVal to the larger of sensVal or 20 - // (effectively ensuring that it is at least 20) - -.. note:: Perhaps counter-intuitively, max() is often used to - constrain the lower end of a variable's range, while :ref:`min() - <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/source/lang/api/micros.rst b/source/lang/api/micros.rst deleted file mode 100644 index de85303..0000000 --- a/source/lang/api/micros.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. highlight:: cpp - -.. _lang-micros: - -micros() -======== - -Returns the number of microseconds since the Maple board began running -the current program. This number will overflow (go back to zero), -after approximately 70 minutes. - -.. note:: There are 1,000 microseconds in a millisecond, and 1,000,000 - microseconds in a second. - -Library Documentation ---------------------- - -.. doxygenfunction:: micros - -Example -------- - -:: - - unsigned int time; - - void setup() { - } - - void loop() { - SerialUSB.print("Time: "); - time = micros(); - // prints time since program started - SerialUSB.println(time); - // wait a second so as not to send massive amounts of data - delay(1000); - } - -See Also --------- - -- :ref:`millis() <lang-millis>` -- :ref:`delay() <lang-delay>` -- :ref:`delayMicroseconds() <lang-delaymicroseconds>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/millis.rst b/source/lang/api/millis.rst deleted file mode 100644 index b6fbf55..0000000 --- a/source/lang/api/millis.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _lang-millis: - -millis() -======== - -Returns the number of milliseconds since the Maple board began running -the current program. This number will overflow (go back to zero) after -approximately 50 days. - -Library Documentation ---------------------- - -.. doxygenfunction:: millis - -Example -------- - -The following time prints the value returned by ``millis()`` roughly -once per second:: - - unsigned int time; - - void setup() { - } - - void loop() { - SerialUSB.print("Time: "); - time = millis(); - // prints time since program started - 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/source/lang/api/min.rst b/source/lang/api/min.rst deleted file mode 100644 index 3307105..0000000 --- a/source/lang/api/min.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. highlight:: cpp - -.. _lang-min: - -min() -===== - -(Macro) Calculates the minimum of two numbers. - -Syntax ------- - -:: - - min(x,y) - -Parameters ----------- - -**x**: the first number; may be any number or numeric expression. - -**y**: the second number; may be any number or numeric expression. - -Returns -------- - -The smaller of the two numbers. - -Example -------- - -:: - - sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 - // ensuring that it never gets above 100. - - -.. note:: Perhaps counter-intuitively, max() is often used to - constrain the lower end of a variable's range, while min() is used - to constrain the upper end of the range. - - -Warning -------- - -Because of the way ``min()`` is implemented, avoid using other -functions inside the parentheses. It may lead to incorrect results:: - - min(a++, 100); // avoid this - yields incorrect results - - a++; // use this instead - - min(a, 100); // keep other operations outside min() - -Arduino Compatibility ---------------------- - -The Maple version of ``min()`` is compatible with Arduino. - -See Also --------- - -- :ref:`max() <lang-max>` -- :ref:`constrain() <lang-constrain>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/nointerrupts.rst b/source/lang/api/nointerrupts.rst deleted file mode 100644 index 68f0498..0000000 --- a/source/lang/api/nointerrupts.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. 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/source/lang/api/pinmode.rst b/source/lang/api/pinmode.rst deleted file mode 100644 index 643e26e..0000000 --- a/source/lang/api/pinmode.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. 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/source/lang/api/pow.rst b/source/lang/api/pow.rst deleted file mode 100644 index 219a866..0000000 --- a/source/lang/api/pow.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _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/source/lang/api/pwmwrite.rst b/source/lang/api/pwmwrite.rst deleted file mode 100644 index 5cc112e..0000000 --- a/source/lang/api/pwmwrite.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. 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/source/lang/api/random.rst b/source/lang/api/random.rst deleted file mode 100644 index 9875ee6..0000000 --- a/source/lang/api/random.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. 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/source/lang/api/randomseed.rst b/source/lang/api/randomseed.rst deleted file mode 100644 index ca7b75f..0000000 --- a/source/lang/api/randomseed.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. 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/source/lang/api/serial.rst b/source/lang/api/serial.rst deleted file mode 100644 index e287015..0000000 --- a/source/lang/api/serial.rst +++ /dev/null @@ -1,282 +0,0 @@ -.. 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/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst deleted file mode 100644 index ed466f2..0000000 --- a/source/lang/api/serialusb.rst +++ /dev/null @@ -1,242 +0,0 @@ -.. highlight:: cpp - -.. _lang-serialusb: - -``SerialUSB`` -============= - -Used for communication between the Maple board and a computer. - -.. contents:: Contents - :local: - -Introduction ------------- - -In addition to three :ref:`serial ports <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/source/lang/api/setup.rst b/source/lang/api/setup.rst deleted file mode 100644 index 1e8e3b8..0000000 --- a/source/lang/api/setup.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. highlight:: cpp - -.. _lang-setup: - -setup() -======= - -The ``setup()`` function is called when a sketch starts. Use it to -initialize :ref:`variables <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/source/lang/api/shiftout.rst b/source/lang/api/shiftout.rst deleted file mode 100644 index 1d9ba12..0000000 --- a/source/lang/api/shiftout.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. 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/source/lang/api/sin.rst b/source/lang/api/sin.rst deleted file mode 100644 index 3e28c0b..0000000 --- a/source/lang/api/sin.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _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/source/lang/api/sq.rst b/source/lang/api/sq.rst deleted file mode 100644 index 96724d3..0000000 --- a/source/lang/api/sq.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. highlight:: cpp - -.. _lang-sq: - -sq() -==== - -(Macro) computes the square of a number. - -Syntax ------- - -:: - - sq(a) - -Parameters ----------- - -**a**: the number. - -Returns -------- - -**a** squared (**a** × **a**). - -Warning -------- - -Because of the way ``sq()`` is implemented, avoid using other -functions or causing side effects inside the parentheses, as it may -lead to incorrect results:: - - b = sq(a++); // avoid this - yields incorrect results - - b = sq(a); // use this instead - - a++; // keep other operations outside sq() - - -Arduino Compatibility ---------------------- - -Maple's implementation of ``sq()`` is compatible with Arduino. - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/api/tan.rst b/source/lang/api/tan.rst deleted file mode 100644 index b1aed31..0000000 --- a/source/lang/api/tan.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _lang-tan: - -tan() -===== - -Calculates the tangent of an angle. - -Library Documentation ---------------------- - -.. doxygenfunction:: tan - -Arduino Compatibility ---------------------- - -The Maple version of ``tan()`` is compatible with Arduino. - -Note that the Maple implementation comes from `newlib -<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/source/lang/api/toggleled.rst b/source/lang/api/toggleled.rst deleted file mode 100644 index cad347f..0000000 --- a/source/lang/api/toggleled.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. 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/source/lang/api/togglepin.rst b/source/lang/api/togglepin.rst deleted file mode 100644 index 290718d..0000000 --- a/source/lang/api/togglepin.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _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/source/lang/api/volatile.rst b/source/lang/api/volatile.rst deleted file mode 100644 index 1b72897..0000000 --- a/source/lang/api/volatile.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. highlight:: cpp - -.. _lang-volatile: - -``volatile`` -============ - -The ``volatile`` keyword known is a variable *qualifier*. It is -usually used before the datatype of a variable, to modify the way in -which the compiler treats the variable. - -Declaring a variable ``volatile`` is a directive to the compiler. The -compiler is software which translates your C++ code into the machine -code, which are the real instructions for the STM32 chip in the -Maple. (The particular compiler we provide for use with the Maple is a -version of :ref:`GCC <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/source/lang/api/waitforbuttonpress.rst b/source/lang/api/waitforbuttonpress.rst deleted file mode 100644 index 0e0fbaf..0000000 --- a/source/lang/api/waitforbuttonpress.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. 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/source/lang/cc-attribution.txt b/source/lang/cc-attribution.txt deleted file mode 100644 index 11302b2..0000000 --- a/source/lang/cc-attribution.txt +++ /dev/null @@ -1,10 +0,0 @@ -.. Included in all this directory's files in order to satisfy the -.. Arduino CC Attribution-ShareAlike 3.0 License - -.. admonition:: License and Attribution - - 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/source/lang/cpp/arithmetic.rst b/source/lang/cpp/arithmetic.rst deleted file mode 100644 index cef3954..0000000 --- a/source/lang/cpp/arithmetic.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. highlight:: cpp - -.. _lang-arithmetic: - -Arithmetic Operators (``+``, ``-``, ``*``, ``/``) -================================================= - -The operators ``+``, ``-``, ``*``, and ``/`` respectively evaluate to -the sum, difference, product, or quotient (respectively) of the two -operands. The operation is conducted using the data type of the -operands, so, for example, ``9 / 4`` gives ``2`` since 9 and 4 are -:ref:`int variables <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/source/lang/cpp/array.rst b/source/lang/cpp/array.rst deleted file mode 100644 index 39d4d91..0000000 --- a/source/lang/cpp/array.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. highlight:: cpp - -.. _lang-array: - -Arrays -====== - -An array is a collection of variables that are accessed with an index -number. Arrays in the C++ programming language, in which the Maple is -programmed, can be complicated, but using simple arrays is relatively -straightforward. - -.. contents:: Contents - :local: - -Creating (Declaring) an Array ------------------------------ - -All of the methods below are valid ways to create (declare) an -array. :: - - int myInts[6]; - int myPins[] = {2, 4, 8, 3, 6}; - int mySensVals[6] = {2, 4, -8, 3, 2}; - char message[6] = "hello"; - -You can declare an array without initializing it, as with myInts. In -the line referring to myPins, we declare an array without explicitly -choosing a size. The compiler counts the elements and creates an -array of the appropriate size. - -Finally, you can both initialize and size your array, as in -mySensVals. Note that when declaring an array with elements of type -char, one more element than your initialization is required, to hold -the required `null character <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/source/lang/cpp/assignment.rst b/source/lang/cpp/assignment.rst deleted file mode 100644 index 6379298..0000000 --- a/source/lang/cpp/assignment.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. highlight:: cpp - -.. _lang-assignment: - -Assignment Operator (``=``) -=========================== - -Stores the value to the right of the equal sign in the variable to -the left of the equal sign. - -The single equal sign in the C++ programming language is called the -assignment operator. It has a different meaning than in algebra -class, where it indicated an equation or equality. The assignment -operator tells the microcontroller to evaluate whatever value or -expression is on the right side of the equal sign, and store it in -the variable to the left of the equal sign [#fgross]_. - -Example -------- - -:: - - int sensVal; // declare an integer variable named sensVal - 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/source/lang/cpp/bitshift.rst b/source/lang/cpp/bitshift.rst deleted file mode 100644 index 47413f2..0000000 --- a/source/lang/cpp/bitshift.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. 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/source/lang/cpp/bitwisemath.rst b/source/lang/cpp/bitwisemath.rst deleted file mode 100644 index cfe34f2..0000000 --- a/source/lang/cpp/bitwisemath.rst +++ /dev/null @@ -1,185 +0,0 @@ -.. highlight:: cpp - -.. _lang-bitwisemath: - -Bitwise Operators (``&``, ``|``, ``^``, ``~``) -============================================== - -The bitwise operators perform their calculations at the bit level of -variables. They help solve a wide range of common programming -problems. - -Much of the material here is adapted for Maple from an (Arduino) -`tutorial on bitwise math -<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/source/lang/cpp/boolean.rst b/source/lang/cpp/boolean.rst deleted file mode 100644 index f09345e..0000000 --- a/source/lang/cpp/boolean.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. 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/source/lang/cpp/booleanvariables.rst b/source/lang/cpp/booleanvariables.rst deleted file mode 100644 index e032c74..0000000 --- a/source/lang/cpp/booleanvariables.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. 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/source/lang/cpp/break.rst b/source/lang/cpp/break.rst deleted file mode 100644 index f367b99..0000000 --- a/source/lang/cpp/break.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. 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/source/lang/cpp/built-in-types.rst b/source/lang/cpp/built-in-types.rst deleted file mode 100644 index f14dce5..0000000 --- a/source/lang/cpp/built-in-types.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. 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/source/lang/cpp/byte.rst b/source/lang/cpp/byte.rst deleted file mode 100644 index 4634594..0000000 --- a/source/lang/cpp/byte.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. highlight:: cpp - -.. _lang-byte: - -byte -==== - -The ``byte`` type stores a 1-byte (8-bit) unsigned integer number, -from 0 to 255. - -.. warning:: - - The ``byte`` type is provided for compatibility with Arduino. - However, it is a non-standard extension. The standard C++ type for - storing an 8-bit unsigned integer is ``unsigned char``; we - recommend using that instead. (Your code will still work on an - Arduino). - - -Example -------- - -:: - - byte b = 134; - -See Also --------- - -- :ref:`byte() <lang-bytecast>` (casting a value to a byte) -- :ref:`Variables <lang-variables>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/bytecast.rst b/source/lang/cpp/bytecast.rst deleted file mode 100644 index 24c3b9e..0000000 --- a/source/lang/cpp/bytecast.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. 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/source/lang/cpp/cc-attribution.txt b/source/lang/cpp/cc-attribution.txt deleted file mode 100644 index e100140..0000000 --- a/source/lang/cpp/cc-attribution.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. Included in all this directory's files in order to satisfy the -.. Arduino CC Attribution-ShareAlike 3.0 License - -.. admonition:: License and Attribution - - This documentation page was adapted from the `Arduino Reference - Documentation <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/source/lang/cpp/char.rst b/source/lang/cpp/char.rst deleted file mode 100644 index 686c0d1..0000000 --- a/source/lang/cpp/char.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. highlight:: cpp - -.. _lang-char: - -``char`` -======== - -The ``char`` type stores a 1-byte character value (or integer with -value from -128 to 127). Character literals are written in single -quotes, like this: ``'A'`` (for multiple characters - strings - use -double quotes: ``"ABC"``). - -Just like everything else on a computer, characters are stored as -numbers. You can see the specific encoding in the `ASCII chart -<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/source/lang/cpp/charcast.rst b/source/lang/cpp/charcast.rst deleted file mode 100644 index 640ad85..0000000 --- a/source/lang/cpp/charcast.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. 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/source/lang/cpp/comments.rst b/source/lang/cpp/comments.rst deleted file mode 100644 index 1428dc3..0000000 --- a/source/lang/cpp/comments.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. highlight:: cpp - -.. _lang-comments: - -Comments -======== - -Comments are lines in the program that are used to inform yourself or -others about the way the program works. They are ignored by the -compiler, and not exported to the processor, so they don't take up any -space in RAM or Flash. - -One use for comments is to help you understand (or remember) how your -program works, or to inform others how your program works. There are -two different ways of making comments. - -.. _lang-comments-singleline: - -**Single line comment**: Anything following two slashes, ``//``, until -the end of the line, is a comment:: - - x = 5; // the rest of this line is a comment - -.. _lang-comments-multiline: - -**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/`` -is a comment:: - - /* <-- a slash-star begins a multi-line comment - - all of this in the multi-line comment - you can use it to comment - out whole blocks of code - - if (gwb == 0){ // single line comment is OK inside a multi-line comment - x = 3; - } - - // don't forget the "closing" star-slash - they have to be balanced: - */ - -Note that it's okay to use single-line comments within a multi-line -comment, but you can't use multi-line comments within a multi-line -comment. Here's an example:: - - /* ok, i started a multi-line comment - - x = 3; /* this next star-slash ENDS the multi-line comment: */ - - x = 4; // this line is outside of the multi-line comment - - // next line is also outside of the comment, and causes a compile error: - */ - -Programming Tip ---------------- - -When experimenting with code, "commenting out" parts of your program -is a convenient way to remove lines that may be buggy. This leaves -the lines in the code, but turns them into comments, so the compiler -just ignores them. This can be especially useful when trying to locate -a problem, or when a program refuses to compile and the compiler error -is cryptic or unhelpful. - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/comparison.rst b/source/lang/cpp/comparison.rst deleted file mode 100644 index 9cd0a9f..0000000 --- a/source/lang/cpp/comparison.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. 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/source/lang/cpp/compoundarithmetic.rst b/source/lang/cpp/compoundarithmetic.rst deleted file mode 100644 index d70a43c..0000000 --- a/source/lang/cpp/compoundarithmetic.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. highlight:: cpp - -.. _lang-compoundarithmetic: - -Compound Arithmetic Operators (``+=`` , ``-=``, ``*=``, ``/=``) -=============================================================== - -These oparators perform a mathematical operation on a variable with -another constant or variable. These operators are just a convenient -shorthand:: - - x += y; // equivalent to the expression x = x + y; - x -= y; // equivalent to the expression x = x - y; - x *= y; // equivalent to the expression x = x * y; - x /= y; // equivalent to the expression x = x / y; - -Here is an example:: - - int x = 2; - int y = 10; - - x += 4; // x now contains 6 - x -= 3; // x now contains 3 - x *= y; // x now contains 30 - x /= 2; // x now contains 15 - x += max(20, 6); // x now contains 35 - x -= sq(5); // x now contains 15 - -Parameters ----------- - -**x**: a numeric variable - -**y**: a numeric variable, number constant, or any other expression -that evaluates to a number (e.g. call to a function that returns a -number). - -See Also --------- - -- :ref:`Arithmetic operators <lang-arithmetic>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/compoundbitwise.rst b/source/lang/cpp/compoundbitwise.rst deleted file mode 100644 index 4efe5df..0000000 --- a/source/lang/cpp/compoundbitwise.rst +++ /dev/null @@ -1,229 +0,0 @@ -.. highlight:: cpp - -.. _lang-compoundbitwise: - -Compound Bitwise Operators (``&=``, ``|=``, ``^=``) -=================================================== - -The compound bitwise operators perform their calculations at the -bit level of variables. They are often used to clear and set -specific bits of a variable. - -See the :ref:`bitwise math tutorial <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/source/lang/cpp/const.rst b/source/lang/cpp/const.rst deleted file mode 100644 index ad0c580..0000000 --- a/source/lang/cpp/const.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. highlight:: cpp - -.. _lang-const: - -``const`` -========= - -The ``const`` keyword stands for "constant". It is a variable -*qualifier* that modifies the behavior of the variable, making a -variable "*read-only*". This means that the variable can be used just -as any other variable of its type, but its value cannot be -changed. You will get a compiler error if you try to assign a value to -a ``const`` variable. - -Constants defined with the ``const`` keyword obey the same rules of -:ref:`variable scoping <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/source/lang/cpp/continue.rst b/source/lang/cpp/continue.rst deleted file mode 100644 index 2a694f6..0000000 --- a/source/lang/cpp/continue.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. 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/source/lang/cpp/curly-braces.rst b/source/lang/cpp/curly-braces.rst deleted file mode 100644 index df2fe2a..0000000 --- a/source/lang/cpp/curly-braces.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. highlight:: cpp - -.. _lang-curly-braces: - -Curly Braces (``{``, ``}``) -=========================== - -.. contents:: Contents - :local: - -Introduction ------------- - -Curly braces (also referred to as just "braces" or as "curly -brackets") are a major part of the C and C++ programming -languages. They are used in several different constructs, outlined -below, and this can sometimes be confusing for beginners. - -An opening curly brace, ``{`` must always be followed by a closing -curly brace ``}``. This is a condition that is often referred to as -the braces being *balanced*. The Maple IDE (integrated development -environment) includes a convenient feature to check the balance of -curly braces. Just select a brace, or even click the insertion point -immediately following a brace, and its companion will be highlighted\ -[#fbug]_\ . - -Beginning programmers, and programmers coming to C++ from languages -without braces, often find using them confusing or daunting. - -Because the use of the curly brace is so varied, it is good -programming practice to type the closing brace immediately after -typing the opening brace when inserting a construct which requires -curly braces. Then insert some blank lines between your braces and -begin inserting statements. Your braces, and your attitude, will never -become unbalanced. - -Unbalanced braces can often lead to cryptic, impenetrable compiler -errors that can sometimes be hard to track down in a large program. -Because of their varied usages, braces are also incredibly important -to the syntax of a program and moving a brace one or two lines will -usually dramatically affect the meaning of a program. - -The main uses of curly braces ------------------------------ - -**Functions**:: - - // a function body needs braces around it - void myFunction(datatype argument) { - // ... function body goes in here ... - } - -**Loops** (see the :ref:`while <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/source/lang/cpp/define.rst b/source/lang/cpp/define.rst deleted file mode 100644 index b22085f..0000000 --- a/source/lang/cpp/define.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. highlight:: cpp - -.. _lang-define: - -``#define`` -=========== - -``#define`` is a useful C and C++ feature that allows the programmer -to give a name to a constant value before the program is compiled. -The compiler will replace references to these constants with the -defined value at compile time. - -This can have some unwanted side effects. In general, the :ref:`const -<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/source/lang/cpp/double.rst b/source/lang/cpp/double.rst deleted file mode 100644 index 59422eb..0000000 --- a/source/lang/cpp/double.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _lang-double: - -``double`` -========== - -Double precision floating point type. Occupies 8 bytes. On Maple, the -``double`` type has a range of approximately -1.79769×10^308 to -1.79769×10^308; the ``double`` type subject to the same :ref:`overflow -issues <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/source/lang/cpp/doublecast.rst b/source/lang/cpp/doublecast.rst deleted file mode 100644 index d3f32ce..0000000 --- a/source/lang/cpp/doublecast.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. 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/source/lang/cpp/dowhile.rst b/source/lang/cpp/dowhile.rst deleted file mode 100644 index d229122..0000000 --- a/source/lang/cpp/dowhile.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. 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/source/lang/cpp/enum.rst b/source/lang/cpp/enum.rst deleted file mode 100644 index b6409eb..0000000 --- a/source/lang/cpp/enum.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. highlight:: cpp - -.. _lang-enum: - -``enum`` -======== - -The ``enum`` keyword is used to specify an enumeration type. An -enumeration type is a type whose values are taken from a specified, -fixed list of constant values. - -Example -------- - -Here's an example defining an enumeration type called ``weather``, -which has values ``HOT``, ``COMFY``, and ``COLD``:: - - enum weather {HOT, COMFY, COLD}; - -Once you've defined this type, you can create variables of type -``weather``, in the same way you would with an :ref:`int <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/source/lang/cpp/float.rst b/source/lang/cpp/float.rst deleted file mode 100644 index 5195fac..0000000 --- a/source/lang/cpp/float.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. highlight:: cpp - -.. _lang-float: - -``float`` -========= - -Single-precision floating point number. Occupies 4 bytes. On Maple, -the ``float`` type has a range of approximately -3.40282×10^38 to -3.40282×10^38; the ``float`` type is subject to the same -:ref:`overflow issues <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/source/lang/cpp/floatcast.rst b/source/lang/cpp/floatcast.rst deleted file mode 100644 index af92543..0000000 --- a/source/lang/cpp/floatcast.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. 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/source/lang/cpp/for.rst b/source/lang/cpp/for.rst deleted file mode 100644 index 78ea562..0000000 --- a/source/lang/cpp/for.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. highlight:: cpp - -.. _lang-for: - -``for`` -======= - -A ``for`` loop is used to repeat a block of statements enclosed in -curly braces. ``for`` loops are useful for performing repetitive -operations, and are often used in combination with :ref:`arrays -<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/source/lang/cpp/goto.rst b/source/lang/cpp/goto.rst deleted file mode 100644 index 2c0b3b0..0000000 --- a/source/lang/cpp/goto.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. highlight:: cpp - -.. _lang-goto: - -Labels and ``goto`` -=================== - -A *label* gives a name to a line of code within a function. You can -label a line by writing a name for it, then a colon (``:``), before -the line starts. The ``goto`` keyword allows program flow to transfer -to a labeled line from anywhere within the same function. - -.. warning:: The use of ``goto`` is discouraged in C and C++ - programming. It is *never necessary* to use ``goto`` to write a - program. - - Unless you know what you're doing, using ``goto`` tends to - encourage code which is harder to debug and understand than - programs without ``goto`` that do the same thing. That said, - however, it's sometimes useful; :ref:`see below <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/source/lang/cpp/if.rst b/source/lang/cpp/if.rst deleted file mode 100644 index f248b05..0000000 --- a/source/lang/cpp/if.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. highlight:: cpp - -.. _lang-if: - -``if``/``else`` -=============== - -An ``if`` statement is used to execute code when certain conditions -are met. The general syntax for an ``if`` statement is:: - - if (condition) { - body - } - -An ``if`` statement first tests whether its *condition* is true (such -as an input being above a certain number). If the condition is true, -the ``if`` statement executes its *body*, which is made up of lines of -code inside :ref:`curly braces <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/source/lang/cpp/include.rst b/source/lang/cpp/include.rst deleted file mode 100644 index 163509d..0000000 --- a/source/lang/cpp/include.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. highlight:: cpp - -.. _lang-include: - -``#include`` -============ - -``#include`` is used to include outside libraries in your sketch. -This gives the programmer access to a large group of standard C -libraries (groups of pre-made functions and data types), and also -libraries written especially for Maple. - -Example -------- - -This example (from the `Arduino LiquidCrystal Tutorial -<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/source/lang/cpp/increment.rst b/source/lang/cpp/increment.rst deleted file mode 100644 index c423d1a..0000000 --- a/source/lang/cpp/increment.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. highlight:: cpp - -.. _lang-increment: - -Increment and Decrement Operators (``++``, ``--``) -================================================== - -These operators increment (add one to) or decrement (subtract one -from) a variable. If they come before the variable, they return its -new value; otherwise, they return its old value. - -Some quick examples:: - - x++; // adds one to x, and returns the old value of x - ++x; // adds one to x, and returns the new value of x - - x--; // decrement x by one and returns the old value of x - --x; // decrement x by one and returns the new value of x - -A more extended example:: - - x = 2; - y = ++x; // x now contains 3, y contains 3 - y = x--; // x contains 2 again, y still contains 3 - -.. warning:: Be careful! You cannot put a space in between the two - ``+`` or ``-`` signs. This example is broken:: - - // this line won't compile (notice the extra space): - int y = x+ +; - -See Also --------- - -- :ref:`lang-compoundarithmetic` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/int.rst b/source/lang/cpp/int.rst deleted file mode 100644 index fa63946..0000000 --- a/source/lang/cpp/int.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. highlight:: cpp - -.. _lang-int: - -``int`` -======= - -The ``int`` data type represents integers. Integers are your primary -data type for number storage, and store a 4 byte value. This yields a -range of -2,147,483,648 to 2,147,483,647 (minimum value of -2^31 and a -maximum value of (2^31) - 1; that's about negative 2 billion to -positive 2 billion). - -An ``int`` stores a negative number with a technique called `two's -complement math -<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/source/lang/cpp/intcast.rst b/source/lang/cpp/intcast.rst deleted file mode 100644 index da838c7..0000000 --- a/source/lang/cpp/intcast.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. 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/source/lang/cpp/keywords.rst b/source/lang/cpp/keywords.rst deleted file mode 100644 index f21cd0d..0000000 --- a/source/lang/cpp/keywords.rst +++ /dev/null @@ -1,204 +0,0 @@ -.. _lang-keywords: - -Keywords -======== - -This page lists all of the C++ keywords, and either links to a -reference page explaining their use, or provides a brief description. - -List of Keywords ----------------- - -The C++ keywords are: - -``and``, ``and_eq``, ``asm``, ``auto``, ``bitand``, ``bitor``, -``bool``, ``break``, ``case``, ``catch``, ``char``, ``class``, -``compl``, ``const``, ``const_cast``, ``continue``, ``default``, -``delete``, ``do``, ``double``, ``dynamic_cast``, ``else``, ``enum``, -``explicit``, ``export``, ``extern``, ``false``, ``float``, ``for``, -``friend``, ``goto``, ``if``, ``inline``, ``int``, ``long``, -``mutable``, ``namespace``, ``new``, ``not``, ``not_eq``, -``operator``, ``or``, ``or_eq``, ``private``, ``protected``, -``public``, ``register``, ``reinterpret_cast``, ``return``, ``short``, -``signed``, ``sizeof``, ``static``, ``static_cast``, ``struct``, -``switch``, ``template``, ``this``, ``throw``, ``true``, ``try``, -``typedef``, ``typeid``, ``typename``, ``union``, ``unsigned``, -``using``, ``virtual``, ``void``, ``volatile``, ``wchar_t``, -``while``, ``xor``, ``xor_eq`` - -Boolean Operator Synonyms -------------------------- - -- ``and`` is a synonym for :ref:`&& <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/source/lang/cpp/longcast.rst b/source/lang/cpp/longcast.rst deleted file mode 100644 index 493ad67..0000000 --- a/source/lang/cpp/longcast.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. 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/source/lang/cpp/longlong.rst b/source/lang/cpp/longlong.rst deleted file mode 100644 index d942cb4..0000000 --- a/source/lang/cpp/longlong.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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/source/lang/cpp/modulo.rst b/source/lang/cpp/modulo.rst deleted file mode 100644 index 013d07e..0000000 --- a/source/lang/cpp/modulo.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. 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/source/lang/cpp/pointer.rst b/source/lang/cpp/pointer.rst deleted file mode 100644 index ff4ec32..0000000 --- a/source/lang/cpp/pointer.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _lang-pointer: - -Pointer Operators (``&``, ``*``) -================================ - -The pointer operators ``&`` (reference) and ``*`` (dereference) are -different from the bitwise math operator :ref:`& -<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/source/lang/cpp/return.rst b/source/lang/cpp/return.rst deleted file mode 100644 index d9aecbe..0000000 --- a/source/lang/cpp/return.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. highlight:: cpp - -.. _lang-return: - -``return`` -========== - -Terminates a function and return a value from a function to the -calling function, if the function has non-``void`` return type. - -Syntax: -------- - -:: - - // from within a "void" function: - return; - - // from within a non-"void" function: - return value; - -In the second case, ``value`` should have a type which is the same as -the return type of the function, or be convertible to it (like an -``int`` to a ``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/source/lang/cpp/scope.rst b/source/lang/cpp/scope.rst deleted file mode 100644 index a270428..0000000 --- a/source/lang/cpp/scope.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. highlight:: cpp - -.. _lang-scope: - -Scope -===== - -Variables in the C++ programming language, which Maple uses (all of -your sketches are C++ programs in disguise), have a property called -*scope*. Simply put, a variable's scope is made up of all of the -lines where the variable can be used. - -Scope in C++ is a fairly complex topic, so we won't try to describe it -in full here. Instead, we present a simplified view, describing two -different kinds of scopes, *global* and *local*. For more detailed -information, consult a C++ reference. - -Global and Local Variables --------------------------- - -A global variable is one that can be "seen" by every function in a -program. In the :ref:`Maple IDE <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/source/lang/cpp/semicolon.rst b/source/lang/cpp/semicolon.rst deleted file mode 100644 index 05e6218..0000000 --- a/source/lang/cpp/semicolon.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. highlight:: cpp - -.. _lang-semicolon: - -Semicolon (``;``) -================= - -Used to end a line of code. Example:: - - int a = 13; - -Tip ---- - -Forgetting to end a line in a semicolon will result in a compiler -error. The error text may be obvious, and refer to a missing -semicolon, or it may not. If an impenetrable or seemingly illogical -compiler error comes up, one of the first things to check is a -missing semicolon, in the immediate vicinity, preceding the line at -which the compiler complained. - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/sizeof.rst b/source/lang/cpp/sizeof.rst deleted file mode 100644 index ec2dea6..0000000 --- a/source/lang/cpp/sizeof.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. highlight:: cpp - -.. _lang-sizeof: - -``sizeof()`` -============ - -The ``sizeof`` operator on the Maple returns the number of bytes -needed to store a value of a given type\ [#fcharsize]_. This can be -an ordinary numeric type, like ``int``. It can be something more -complicated, like a ``struct`` or ``union``. If the argument to -``sizeof`` is an array, it returns the total number of bytes occupied -by the array. - -The general syntax looks like this:: - - sizeof(type) - sizeof(var) - -Example -------- - -The ``sizeof`` operator is useful for dealing with arrays (such as -strings) where it is convenient to be able to change the size of the -array without breaking other parts of the program. - -This program prints out a text string one character at a time. Try -changing the text phrase:: - - char myStr[] = "this is a test"; - int i; - - void setup() { - Serial.begin(9600); - } - - void loop() { - for (i = 0; i < sizeof(myStr) - 1; i++) { - Serial.print(i, DEC); - Serial.print(" = "); - Serial.println(myStr[i], BYTE); - } - } - - -Note that ``sizeof`` returns the total number of bytes. So for larger -variable types such as ``int``, the :ref:`for loop <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/source/lang/cpp/sqrt.rst b/source/lang/cpp/sqrt.rst deleted file mode 100644 index fbabf82..0000000 --- a/source/lang/cpp/sqrt.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _lang-sqrt: - -sqrt() -====== - -Calculates the square root of a number. - -Library Documentation ---------------------- - -.. doxygenfunction:: sqrt - -Arduino Compatibility ---------------------- - -The Maple versino of ``sqrt()`` is compatible with Arduino. - -See Also --------- - -- :ref:`pow <lang-pow>` -- :ref:`sq <lang-sq>` - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/static.rst b/source/lang/cpp/static.rst deleted file mode 100644 index 8c52ba0..0000000 --- a/source/lang/cpp/static.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. highlight:: cpp - -.. _lang-static: - -``static`` -========== - -The ``static`` keyword can be used to create variables that are -visible to only one function. However, unlike local variables that get -created and destroyed every time a function is called, ``static`` -variables persist beyond the function call, preserving their data -between function calls. - -Variables declared as ``static`` will only be created and initialized -the first time a function is called. - -.. note:: This is only one use of the ``static`` keyword in C++. It - has some other important uses that are not documented here; consult - a reliable C++ reference for details. - -Example -------- - -One use case for ``static`` variables is implementing counters that -last longer than the functions which need them, but shouldn't be -shared to other functions. Here's an example:: - - void setup() { - SerialUSB.begin(); - } - - void loop() { - int reading; - if (timeToReadSensors()) { - reading = readSensors(); - } - // do something with reading - } - - int readSensors() { - static int numSensorReadings = 0; - numSensorReadings++; - if (numSensorReadings % 100 == 0) { - SerialUSB.print("just got to another 100 sensor readings"); - } - return analogRead(...); - } - -In this example, the static variable ``numSensorReadings`` is -initialized to zero the first time ``readSensors()`` is called, and -then incremented, so it starts out at one. Subsequent calls to -``readSensors()`` won't reset ``numSensorReadings`` to zero, because -it was declared ``static``. Thus, ``numSensorReadings`` is a count of -the number of times that ``readSensors()`` has been called. - -.. include:: /arduino-cc-attribution.txt diff --git a/source/lang/cpp/string.rst b/source/lang/cpp/string.rst deleted file mode 100644 index 3497484..0000000 --- a/source/lang/cpp/string.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. 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/source/lang/cpp/switchcase.rst b/source/lang/cpp/switchcase.rst deleted file mode 100644 index e31ccf3..0000000 --- a/source/lang/cpp/switchcase.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. 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/source/lang/cpp/unsignedchar.rst b/source/lang/cpp/unsignedchar.rst deleted file mode 100644 index 45fedeb..0000000 --- a/source/lang/cpp/unsignedchar.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. 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/source/lang/cpp/unsignedint.rst b/source/lang/cpp/unsignedint.rst deleted file mode 100644 index f8ea473..0000000 --- a/source/lang/cpp/unsignedint.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. 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/source/lang/cpp/unsignedlonglong.rst b/source/lang/cpp/unsignedlonglong.rst deleted file mode 100644 index a1143f0..0000000 --- a/source/lang/cpp/unsignedlonglong.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. 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/source/lang/cpp/variables.rst b/source/lang/cpp/variables.rst deleted file mode 100644 index 9ffdd1d..0000000 --- a/source/lang/cpp/variables.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. highlight:: cpp - -.. _lang-variables: - -Variables -========= - -A variable is a way of naming and storing a value for later use by -the program, such as data from a sensor or an intermediate value -used in a calculation. - -.. contents:: Contents - :local: - -.. _lang-variables-declaring: - -Declaring Variables -------------------- - -Before they are used, all variables have to be *declared*. Declaring a -variable means defining its type, giving it a name, and (optionally) -giving it an initial value (this is often referred to as -*initializing* the variable). Variables do not have to be initialized -(given a value) when they are declared, but it is good style to give -them an initial value whenever possible. - -Here is an example of declaring a variable named ``inputVariable1`` -with type :ref:`int <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/source/lang/cpp/void.rst b/source/lang/cpp/void.rst deleted file mode 100644 index 7af0acd..0000000 --- a/source/lang/cpp/void.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. 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/source/lang/cpp/while.rst b/source/lang/cpp/while.rst deleted file mode 100644 index e66e0aa..0000000 --- a/source/lang/cpp/while.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. highlight:: cpp - -.. _lang-while: - -``while`` -========= - -Syntax ------- - -:: - - while (expression) { - // block of code - } - -Description ------------ - -``while`` loops will repeat the statements inside their associated -block of code until the expression inside the parentheses becomes -:ref:`false <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/source/lang/unimplemented/notone.rst b/source/lang/unimplemented/notone.rst deleted file mode 100644 index 8af878b..0000000 --- a/source/lang/unimplemented/notone.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _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/source/lang/unimplemented/pulsein.rst b/source/lang/unimplemented/pulsein.rst deleted file mode 100644 index 2b52428..0000000 --- a/source/lang/unimplemented/pulsein.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _lang-pulsein: - -pulseIn() -========= - -Description ------------ - -Reads a pulse (either HIGH or LOW) on a pin. For example, if -**value** is **HIGH**, **pulseIn()** waits for the pin to go -**HIGH**, starts timing, then waits for the pin to go **LOW** and -stops timing. Returns the length of the pulse in microseconds. -Gives up and returns 0 if no pulse starts within a specified time -out. - - - -The timing of this function has been determined empirically and -will probably show errors in longer pulses. Works on pulses from 10 -microseconds to 3 minutes in length. - - - -Syntax ------- - -pulseIn(pin, value) -pulseIn(pin, value, timeout) - - - -Parameters ----------- - -pin: the number of the pin on which you want to read the pulse. -(*int*) - - - -value: type of pulse to read: either -`HIGH <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/source/lang/unimplemented/stringclass.rst b/source/lang/unimplemented/stringclass.rst deleted file mode 100644 index b893e83..0000000 --- a/source/lang/unimplemented/stringclass.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _lang-stringclass: - -String Class -============ - -.. include:: /lang/cc-attribution.txt diff --git a/source/lang/unimplemented/stringobject.rst b/source/lang/unimplemented/stringobject.rst deleted file mode 100644 index e47ed7e..0000000 --- a/source/lang/unimplemented/stringobject.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. _lang-stringobject: - -String -====== - -Description ------------ - -The String class, part of the core as of version 0019, allows you to -use and manipulate strings of text in more complex ways than character -arrays do. You can concatenate Strings, append to them, search for and -replace substrings, and more. It takes more memory than a simple -character array, but it is also more useful. - - - -For reference, character arrays are referred to as strings with a -small s, and instances of the String class are referred to as -Strings with a capital S. Note that constant strings, specified in -"double quotes" are treated as char arrays, not instances of the -String class. - - - -Functions ---------- - - -- `String <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/source/lang/unimplemented/tone.rst b/source/lang/unimplemented/tone.rst deleted file mode 100644 index 13d581e..0000000 --- a/source/lang/unimplemented/tone.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _lang-tone: - -tone() -====== - -Description ------------ - -Generates a square wave of the specified frequency (and 50% duty -cycle) on a pin. A duration can be specified, otherwise the wave -continues until a call to -`noTone <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/source/language-index.rst b/source/language-index.rst deleted file mode 100644 index 5e4c609..0000000 --- a/source/language-index.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _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/source/language.rst b/source/language.rst deleted file mode 100644 index a24bb5f..0000000 --- a/source/language.rst +++ /dev/null @@ -1,431 +0,0 @@ -.. 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/source/libmaple.rst b/source/libmaple.rst deleted file mode 100644 index 458241e..0000000 --- a/source/libmaple.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. 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/source/libmaple/api/adc.rst b/source/libmaple/api/adc.rst deleted file mode 100644 index 2f06926..0000000 --- a/source/libmaple/api/adc.rst +++ /dev/null @@ -1,231 +0,0 @@ -.. 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/source/libmaple/api/bitband.rst b/source/libmaple/api/bitband.rst deleted file mode 100644 index 768f678..0000000 --- a/source/libmaple/api/bitband.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. 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/source/libmaple/api/bkp.rst b/source/libmaple/api/bkp.rst deleted file mode 100644 index 4f0115b..0000000 --- a/source/libmaple/api/bkp.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. 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/source/libmaple/api/dac.rst b/source/libmaple/api/dac.rst deleted file mode 100644 index 55c8faf..0000000 --- a/source/libmaple/api/dac.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. 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/source/libmaple/api/delay.rst b/source/libmaple/api/delay.rst deleted file mode 100644 index d11496b..0000000 --- a/source/libmaple/api/delay.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. 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/source/libmaple/api/dma.rst b/source/libmaple/api/dma.rst deleted file mode 100644 index a9893e2..0000000 --- a/source/libmaple/api/dma.rst +++ /dev/null @@ -1,215 +0,0 @@ -.. 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/source/libmaple/api/exti.rst b/source/libmaple/api/exti.rst deleted file mode 100644 index 1038fbf..0000000 --- a/source/libmaple/api/exti.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. 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/source/libmaple/api/flash.rst b/source/libmaple/api/flash.rst deleted file mode 100644 index 52ff4d2..0000000 --- a/source/libmaple/api/flash.rst +++ /dev/null @@ -1,249 +0,0 @@ -.. 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/source/libmaple/api/fsmc.rst b/source/libmaple/api/fsmc.rst deleted file mode 100644 index e2bf87a..0000000 --- a/source/libmaple/api/fsmc.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. 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/source/libmaple/api/gpio.rst b/source/libmaple/api/gpio.rst deleted file mode 100644 index faf0ad2..0000000 --- a/source/libmaple/api/gpio.rst +++ /dev/null @@ -1,243 +0,0 @@ -.. 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/source/libmaple/api/i2c.rst b/source/libmaple/api/i2c.rst deleted file mode 100644 index ff380cc..0000000 --- a/source/libmaple/api/i2c.rst +++ /dev/null @@ -1,124 +0,0 @@ -.. 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/source/libmaple/api/iwdg.rst b/source/libmaple/api/iwdg.rst deleted file mode 100644 index 65f9f7b..0000000 --- a/source/libmaple/api/iwdg.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. 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/source/libmaple/api/libmaple.rst b/source/libmaple/api/libmaple.rst deleted file mode 100644 index 7deb659..0000000 --- a/source/libmaple/api/libmaple.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. 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/source/libmaple/api/libmaple_types.rst b/source/libmaple/api/libmaple_types.rst deleted file mode 100644 index 5ca446e..0000000 --- a/source/libmaple/api/libmaple_types.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. 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/source/libmaple/api/nvic.rst b/source/libmaple/api/nvic.rst deleted file mode 100644 index 505e36e..0000000 --- a/source/libmaple/api/nvic.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. 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/source/libmaple/api/pwr.rst b/source/libmaple/api/pwr.rst deleted file mode 100644 index 6a2cf22..0000000 --- a/source/libmaple/api/pwr.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. 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/source/libmaple/api/rcc-reg-bits.txt b/source/libmaple/api/rcc-reg-bits.txt deleted file mode 100644 index 6b1133d..0000000 --- a/source/libmaple/api/rcc-reg-bits.txt +++ /dev/null @@ -1,1017 +0,0 @@ -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/source/libmaple/api/rcc.rst b/source/libmaple/api/rcc.rst deleted file mode 100644 index ce58ec8..0000000 --- a/source/libmaple/api/rcc.rst +++ /dev/null @@ -1,360 +0,0 @@ -.. 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/source/libmaple/api/ring_buffer.rst b/source/libmaple/api/ring_buffer.rst deleted file mode 100644 index ef082dd..0000000 --- a/source/libmaple/api/ring_buffer.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. 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/source/libmaple/api/scb.rst b/source/libmaple/api/scb.rst deleted file mode 100644 index 96d464f..0000000 --- a/source/libmaple/api/scb.rst +++ /dev/null @@ -1,156 +0,0 @@ -.. 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/source/libmaple/api/spi.rst b/source/libmaple/api/spi.rst deleted file mode 100644 index e72696b..0000000 --- a/source/libmaple/api/spi.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. 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/source/libmaple/api/stm32.rst b/source/libmaple/api/stm32.rst deleted file mode 100644 index 335bda4..0000000 --- a/source/libmaple/api/stm32.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. 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/source/libmaple/api/systick.rst b/source/libmaple/api/systick.rst deleted file mode 100644 index 45b6d63..0000000 --- a/source/libmaple/api/systick.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. 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/source/libmaple/api/timer.rst b/source/libmaple/api/timer.rst deleted file mode 100644 index f315cb0..0000000 --- a/source/libmaple/api/timer.rst +++ /dev/null @@ -1,453 +0,0 @@ -.. 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/source/libmaple/api/usart.rst b/source/libmaple/api/usart.rst deleted file mode 100644 index 68f2c37..0000000 --- a/source/libmaple/api/usart.rst +++ /dev/null @@ -1,197 +0,0 @@ -.. 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/source/libmaple/api/util.rst b/source/libmaple/api/util.rst deleted file mode 100644 index 54377c0..0000000 --- a/source/libmaple/api/util.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. 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/source/libmaple/apis.rst b/source/libmaple/apis.rst deleted file mode 100644 index 31f4902..0000000 --- a/source/libmaple/apis.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _libmaple-apis: - -``libmaple`` API Index -====================== - -This is the master index for libmaple proper's APIs. - -**Contents** - -.. toctree:: - :maxdepth: 1 - :glob: - - api/* diff --git a/source/libmaple/coding-standard.rst b/source/libmaple/coding-standard.rst deleted file mode 100644 index 9ed56cc..0000000 --- a/source/libmaple/coding-standard.rst +++ /dev/null @@ -1,422 +0,0 @@ -.. _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/source/libmaple/contributing.rst b/source/libmaple/contributing.rst deleted file mode 100644 index 25c6c17..0000000 --- a/source/libmaple/contributing.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. _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/source/libmaple/overview.rst b/source/libmaple/overview.rst deleted file mode 100644 index 006f1d8..0000000 --- a/source/libmaple/overview.rst +++ /dev/null @@ -1,516 +0,0 @@ -.. 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/source/libraries.rst b/source/libraries.rst deleted file mode 100644 index 1ae0e87..0000000 --- a/source/libraries.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. 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/source/libs/servo.rst b/source/libs/servo.rst deleted file mode 100644 index 80288c6..0000000 --- a/source/libs/servo.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. 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/source/libs/wire.rst b/source/libs/wire.rst deleted file mode 100644 index 2c5bed9..0000000 --- a/source/libs/wire.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. 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/source/maple-ide-install.rst b/source/maple-ide-install.rst deleted file mode 100644 index 7e9bfa2..0000000 --- a/source/maple-ide-install.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. 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/source/maple-quickstart.rst b/source/maple-quickstart.rst deleted file mode 100644 index a4bc55a..0000000 --- a/source/maple-quickstart.rst +++ /dev/null @@ -1,210 +0,0 @@ -.. 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/source/prolog.rst b/source/prolog.rst deleted file mode 100644 index 8606555..0000000 --- a/source/prolog.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. 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/source/pwm.rst b/source/pwm.rst deleted file mode 100644 index 421229d..0000000 --- a/source/pwm.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. _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/source/spi.rst b/source/spi.rst deleted file mode 100644 index 13c4c59..0000000 --- a/source/spi.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _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/source/stm32.rst b/source/stm32.rst deleted file mode 100644 index d918655..0000000 --- a/source/stm32.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. _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/source/systick.rst b/source/systick.rst deleted file mode 100644 index afc8d09..0000000 --- a/source/systick.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _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/source/timers.rst b/source/timers.rst deleted file mode 100644 index 0fa0976..0000000 --- a/source/timers.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. 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/source/troubleshooting.rst b/source/troubleshooting.rst deleted file mode 100644 index 4d7cbb0..0000000 --- a/source/troubleshooting.rst +++ /dev/null @@ -1,258 +0,0 @@ -.. 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/source/unix-toolchain-linux-setup.rst b/source/unix-toolchain-linux-setup.rst deleted file mode 100644 index c1333e1..0000000 --- a/source/unix-toolchain-linux-setup.rst +++ /dev/null @@ -1,203 +0,0 @@ -.. 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/source/unix-toolchain-osx-setup.rst b/source/unix-toolchain-osx-setup.rst deleted file mode 100644 index 01b9e2c..0000000 --- a/source/unix-toolchain-osx-setup.rst +++ /dev/null @@ -1,132 +0,0 @@ -.. 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/source/unix-toolchain-win-setup.rst b/source/unix-toolchain-win-setup.rst deleted file mode 100644 index 099e7fe..0000000 --- a/source/unix-toolchain-win-setup.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. 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/source/unix-toolchain.rst b/source/unix-toolchain.rst deleted file mode 100644 index 769b8ec..0000000 --- a/source/unix-toolchain.rst +++ /dev/null @@ -1,375 +0,0 @@ -.. 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/source/usart.rst b/source/usart.rst deleted file mode 100644 index dbbc81c..0000000 --- a/source/usart.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _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/source/usb.rst b/source/usb.rst deleted file mode 100644 index 80c40ca..0000000 --- a/source/usb.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. 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/source/whats-new.rst b/source/whats-new.rst deleted file mode 100644 index c7d10c5..0000000 --- a/source/whats-new.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. 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>`. |
