diff options
Diffstat (limited to 'docs/source')
204 files changed, 0 insertions, 14849 deletions
diff --git a/docs/source/_static/.gitignore b/docs/source/_static/.gitignore deleted file mode 100644 index e69de29..0000000 --- a/docs/source/_static/.gitignore +++ /dev/null diff --git a/docs/source/_static/apilist.html b/docs/source/_static/apilist.html deleted file mode 100644 index 556fcc9..0000000 --- a/docs/source/_static/apilist.html +++ /dev/null @@ -1,5 +0,0 @@ -{# Filename: .static/apilist.html #} -{% set parents = parents.pop() %} -{% if parents %} -<a href="{{ parents.link|e }}">{{ parents.title }}</a> -{% endif %} diff --git a/docs/source/_static/img/blinky-to-flash.png b/docs/source/_static/img/blinky-to-flash.png Binary files differdeleted file mode 100644 index 0320c5b..0000000 --- a/docs/source/_static/img/blinky-to-flash.png +++ /dev/null diff --git a/docs/source/_static/img/blinky.png b/docs/source/_static/img/blinky.png Binary files differdeleted file mode 100644 index bda4cee..0000000 --- a/docs/source/_static/img/blinky.png +++ /dev/null diff --git a/docs/source/_static/img/button-new.png b/docs/source/_static/img/button-new.png Binary files differdeleted file mode 100644 index 3fd98be..0000000 --- a/docs/source/_static/img/button-new.png +++ /dev/null diff --git a/docs/source/_static/img/button-open.png b/docs/source/_static/img/button-open.png Binary files differdeleted file mode 100644 index 466fc10..0000000 --- a/docs/source/_static/img/button-open.png +++ /dev/null diff --git a/docs/source/_static/img/button-save.png b/docs/source/_static/img/button-save.png Binary files differdeleted file mode 100644 index 7eba286..0000000 --- a/docs/source/_static/img/button-save.png +++ /dev/null diff --git a/docs/source/_static/img/button-serial-monitor.png b/docs/source/_static/img/button-serial-monitor.png Binary files differdeleted file mode 100644 index aec9741..0000000 --- a/docs/source/_static/img/button-serial-monitor.png +++ /dev/null diff --git a/docs/source/_static/img/button-stop.png b/docs/source/_static/img/button-stop.png Binary files differdeleted file mode 100644 index 4812ae9..0000000 --- a/docs/source/_static/img/button-stop.png +++ /dev/null diff --git a/docs/source/_static/img/button-upload.png b/docs/source/_static/img/button-upload.png Binary files differdeleted file mode 100644 index 0f41eeb..0000000 --- a/docs/source/_static/img/button-upload.png +++ /dev/null diff --git a/docs/source/_static/img/button-verify.png b/docs/source/_static/img/button-verify.png Binary files differdeleted file mode 100644 index 95abeb8..0000000 --- a/docs/source/_static/img/button-verify.png +++ /dev/null diff --git a/docs/source/_static/img/codeblocks_build.png b/docs/source/_static/img/codeblocks_build.png Binary files differdeleted file mode 100644 index c98bcdc..0000000 --- a/docs/source/_static/img/codeblocks_build.png +++ /dev/null diff --git a/docs/source/_static/img/codeblocks_makefile.png b/docs/source/_static/img/codeblocks_makefile.png Binary files differdeleted file mode 100644 index a0ef21f..0000000 --- a/docs/source/_static/img/codeblocks_makefile.png +++ /dev/null diff --git a/docs/source/_static/img/codeblocks_maketargets.png b/docs/source/_static/img/codeblocks_maketargets.png Binary files differdeleted file mode 100644 index bbb68cb..0000000 --- a/docs/source/_static/img/codeblocks_maketargets.png +++ /dev/null diff --git a/docs/source/_static/img/codeblocks_newproject.png b/docs/source/_static/img/codeblocks_newproject.png Binary files differdeleted file mode 100644 index 8d08d1f..0000000 --- a/docs/source/_static/img/codeblocks_newproject.png +++ /dev/null diff --git a/docs/source/_static/img/ide-blinky.png b/docs/source/_static/img/ide-blinky.png Binary files differdeleted file mode 100644 index 3cccdb4..0000000 --- a/docs/source/_static/img/ide-blinky.png +++ /dev/null diff --git a/docs/source/_static/img/jtag-wiring.png b/docs/source/_static/img/jtag-wiring.png Binary files differdeleted file mode 100644 index 8f31f99..0000000 --- a/docs/source/_static/img/jtag-wiring.png +++ /dev/null diff --git a/docs/source/_static/img/osx-network-prefs-unconfigured.png b/docs/source/_static/img/osx-network-prefs-unconfigured.png Binary files differdeleted file mode 100644 index 70d2fa0..0000000 --- a/docs/source/_static/img/osx-network-prefs-unconfigured.png +++ /dev/null diff --git a/docs/source/_static/img/osx-unconfigured-popup.png b/docs/source/_static/img/osx-unconfigured-popup.png Binary files differdeleted file mode 100644 index a43ad57..0000000 --- a/docs/source/_static/img/osx-unconfigured-popup.png +++ /dev/null diff --git a/docs/source/_static/img/round_logo_32x32.ico b/docs/source/_static/img/round_logo_32x32.ico Binary files differdeleted file mode 100644 index 29fb2bf..0000000 --- a/docs/source/_static/img/round_logo_32x32.ico +++ /dev/null diff --git a/docs/source/_static/img/round_logo_60x60.png b/docs/source/_static/img/round_logo_60x60.png Binary files differdeleted file mode 100644 index dacd36a..0000000 --- a/docs/source/_static/img/round_logo_60x60.png +++ /dev/null diff --git a/docs/source/_static/img/serial-monitor.png b/docs/source/_static/img/serial-monitor.png Binary files differdeleted file mode 100644 index 6162dab..0000000 --- a/docs/source/_static/img/serial-monitor.png +++ /dev/null diff --git a/docs/source/_static/img/serial-port-mac.png b/docs/source/_static/img/serial-port-mac.png Binary files differdeleted file mode 100644 index b3a1989..0000000 --- a/docs/source/_static/img/serial-port-mac.png +++ /dev/null diff --git a/docs/source/_static/img/serial-port-ubuntu.png b/docs/source/_static/img/serial-port-ubuntu.png Binary files differdeleted file mode 100644 index 8038e41..0000000 --- a/docs/source/_static/img/serial-port-ubuntu.png +++ /dev/null diff --git a/docs/source/_static/img/serial-port-win.png b/docs/source/_static/img/serial-port-win.png Binary files differdeleted file mode 100644 index 90dc1c4..0000000 --- a/docs/source/_static/img/serial-port-win.png +++ /dev/null diff --git a/docs/source/_static/img/upload-button.png b/docs/source/_static/img/upload-button.png Binary files differdeleted file mode 100644 index 20a663f..0000000 --- a/docs/source/_static/img/upload-button.png +++ /dev/null diff --git a/docs/source/_static/img/verify-success.png b/docs/source/_static/img/verify-success.png Binary files differdeleted file mode 100644 index 6928674..0000000 --- a/docs/source/_static/img/verify-success.png +++ /dev/null diff --git a/docs/source/_static/img/verify_button.png b/docs/source/_static/img/verify_button.png Binary files differdeleted file mode 100644 index 37100db..0000000 --- a/docs/source/_static/img/verify_button.png +++ /dev/null diff --git a/docs/source/_templates/.gitignore b/docs/source/_templates/.gitignore deleted file mode 100644 index e69de29..0000000 --- a/docs/source/_templates/.gitignore +++ /dev/null diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html deleted file mode 100644 index 4d92d33..0000000 --- a/docs/source/_templates/layout.html +++ /dev/null @@ -1,5 +0,0 @@ -{% extends "!layout.html" %} -{% block rootrellink %} - <li><a href="http://leaflabs.com/">LeafLabs</a> |</li> - {{ super() }} -{% endblock %} diff --git a/docs/source/adc.rst b/docs/source/adc.rst deleted file mode 100644 index 18c54ab..0000000 --- a/docs/source/adc.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _adc: - -===== - ADC -===== - -Analog-Digital Conversion is the process of reading a physical voltage -as a number. The Maple has a large number of pins which are capable of -taking 12-bit ADC measurements, which means that voltages from 0 to -3.3V are read as numbers from 0 to 4095. This corresponds to a -theoretical sensitivity of just under 1 millivolt. In reality, a -number of factors introduce noise and bias into this reading, and a -number of techniques must be used to get good precision and accuracy. - -.. contents:: Contents - :local: - -.. _adc-noise-bias: - -Noise and Bias --------------- - -.. FIXME [0.0.12, Maple Native] - -The biggest issues with analog to digital conversion are noise and -bias. With the Maple line, we have tried to isolate the ADC pins and -traces from strong noise sources, but there are always trade-offs -between noise, additional functionality, cost, and package size. -We've tried to enable good analog performance by isolating as many ADC -pins as possible from digital noise on each board. - -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 <maple-native-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/Voltage_source#Zener_voltage_source>`_\ -. However, `operational amplifiers -<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other -powered components can also be used if greater precision is required. - -.. _adc-function-reference: - -Function Reference ------------------- - -* :ref:`lang-analogread` -* :ref:`lang-pinmode` - -.. _adc-recommended-reading: - -Recommended Reading -------------------- - -* `Wikipedia: Analog-to-Digital Converter - <http://en.wikipedia.org/wiki/Analog-to-digital_converter>`_ -* `Arduino Analog Input Tutorial - <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ -* ST documentation: - - * `Application Note on ADC Modes - <http://www.st.com/stonline/products/literature/an/16840.pdf>`_ (PDF) - * `Application Note on ADC Oversampling - <http://www.st.com/stonline/products/literature/an/14183.pdf>`_ (PDF) diff --git a/docs/source/arduino-cc-attribution.txt b/docs/source/arduino-cc-attribution.txt deleted file mode 100644 index ad1c1e0..0000000 --- a/docs/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/docs/source/arduino-compatibility.rst b/docs/source/arduino-compatibility.rst deleted file mode 100644 index c200411..0000000 --- a/docs/source/arduino-compatibility.rst +++ /dev/null @@ -1,271 +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 program) 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 -------------------------------- - -.. 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/mcu/maple-eeprom-emulation-library/>`_ by - `x893 <http://akb77.com/g/>`_, but we haven't tested it. - - * - Firmata - - Not yet - - Planned - - * - Matrix - - Not yet - - Planned - - * - Servo - - **Yes** - - :ref:`Included since IDE 0.0.9 <libraries-servo>` - - * - SoftwareSerial - - Not yet - - Planned - - * - Sprite - - Not yet - - Planned - - * - Stepper - - Not yet - - Planned - -Sketch and Library Porting HOWTO --------------------------------- - -In addition to the suggestions in this section, you may find many of -the individual :ref:`language reference <language>` pages useful. As -appropriate, these have "Arduino Compatibility" sections; one good -example is the :ref:`analogWrite() <lang-analogwrite-compatibility>` -function. - -- Check the hardware and header differences above, and see if your - project or shield needs to be modified (eg, add 3.3V level - converters or reroute PWM to header D10). - -- Check for ported library functionality. We intend to port all of the - core and popular libraries (like Wire, Ethernet, and the LCD screen - driver), but this task is not yet finished. (:ref:`Patches are - welcome! <libmaple-contributing>`). - -- Check for peripheral conflicts; changing the configuration of timers - and bus speeds for a feature on one header may impact all the - features on that hardware "port". For example, changing the timer - prescaler to do long PWM pulses could impact |i2c| communications on - nearby headers. - -- Rewrite any low-level code. This could potentially be very - difficult, but hopefully you've used the Arduino libraries to - abstract away the registers and other hardware-specific - details. Your sketch probably doesn't have any low-level code; a - library which wraps a particular peripheral very well may. Some - help is available in the :ref:`arm-gcc` reference. - -- Redeclare variable sizes if necessary: generics like ``int`` will - probably work unless you depend on side-effects like rollover. - -- Check every ``pinMode()``: the Maple has more modes for GPIO - pins. For example, make sure to set analog pins to ``INPUT_ANALOG`` - before reading and PWM pins to ``PWM`` before writing. The full set - of pin modes is documented in the :ref:`lang-pinmode` reference. - -- Modify PWM writes: ``pinMode()`` must be set to ``PWM``, the - frequency of the PWM pulse configured, and the duty cycle written - with up to 16-bit resolution. - -- Modify ADC reads: :ref:`lang-analogread` takes the full pin number - (not 0-5) and returns a full 12-bit reading. The ADC pin must have - its ``pinMode()`` set to ``INPUT_ANALOG``. - -- Possibly convert all Serial-over-USB communications to use - :ref:`lang-serialusb` instead of a USART :ref:`serial port - <lang-serial>`. The Maple has a dedicated USB port which is not - connected to the USART TX/RX pins in any way. - -- Check timing: Maple clock cycles are just 13.9 nanoseconds, though - the peripheral bus speeds (which limit GPIO output) are clocked - slower. diff --git a/docs/source/arm-gcc.rst b/docs/source/arm-gcc.rst deleted file mode 100644 index e97bb2f..0000000 --- a/docs/source/arm-gcc.rst +++ /dev/null @@ -1,85 +0,0 @@ - -.. _arm-gcc: - -GCC for Maple -============= - -This document provides notes on using of ``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/>`_. - -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. - -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-avr-gcc: - -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. - -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``: You can direct the linker script provided - with libmaple to store a variable in Flash (instead of RAM) by using - the libmaple macro ``__FLASH__``, like so:: - - uint32 array[] __FLASH__ = {0, 1, 2}; - - Be aware, however, that if you do that, you can only store values - which are compile-time constants, and that if you attempt to change - a variable stored in Flash, your program will crash. diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst deleted file mode 100644 index ec4fe73..0000000 --- a/docs/source/bootloader.rst +++ /dev/null @@ -1,716 +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. - -This section applies to Maple Rev 3 or higher. If you have a Maple -Rev 1; you don't have a BUT button, and won't be able to follow these -directions. A workaround is detailed in `this forum posting -<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 -- Hardware for communicating between the Maple and your computer over - serial. -- `Python <http://python.org>`_ version 2.5 or higher, with the - `PySerial <http://pyserial.sourceforge.net/>`_ library installed. - -**Step 1: Obtain a bootloader binary**. The first thing you'll need to -do is to compile your bootloader binary. Note that an ASCII -representation of the binary, such as the Intel .hex format, won't -work. - -.. FIXME [Mini, Native] links to precompiled bootloaders - -If you just want to flash the default Maple bootloader (the one that -was installed on your Maple when it arrived), we host a `pre-compiled -copy -<http://static.leaflabs.com/pub/leaflabs/maple-bootloader/maple_boot-rev3-9c5f8e.bin>`_, -which works on all Maple Revs. - -To obtain the latest development version, you can run (on a -:ref:`suitably configured system <unix-toolchain>`) the following to -obtain a binary of the bootloader currently used on the Maple:: - - $ git checkout git://github.com/leaflabs/maple-bootloader.git - $ cd maple-bootloader - $ make - $ ls -lh build/maple-boot.bin # this is the compiled bootloader binary - -**Step 2: Connect Maple Serial1 to your computer**. -There are a variety of ways of doing this. We use Sparkfun's `FTDI -breakout boards <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. - -.. FIXME [Maple-specific values] - -If you do use an FTDI breakout board, first make sure your Maple is -disconnected from an external power source, be it battery, USB, or -barrel jack. Then, connect the FTDI board's TX pin to ``Serial1``\ 's -RX pin (pin 8), FTDI RX to ``Serial1`` TX (pin 7), FTDI ground to -Maple's GND, and its 3.3V pin to Maple's Vin (use the Maple's -silkscreen for help locating these pins). - -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: Put your Maple into serial bootloader mode**. Do this by -pressing the RESET button, then *while RESET is held down*, pressing -and holding the BUT button. Next, *making sure to keep BUT held -down*, release the RESET button and wait for a few seconds before -releasing BUT. - -**Step 4: 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". 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`_! diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 005a988..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,274 +0,0 @@ -# -*- coding: utf-8 -*- -# -# libmaple documentation build configuration file, created by -# sphinx-quickstart on Thu Oct 7 06:42:30 2010. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# We rely on Michael Jones's breathe as a Doxygen-to-Sphinx bridge. -# See libmaple/docs/README for information on obtaining it and letting -# Sphinx know where it is. -sys.path.append(os.environ['BREATHE_HOME']) - -# -- General configuration ---------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', 'sphinx.ext.todo', - 'sphinx.ext.coverage', 'breathe'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates', '_static'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Maple' -copyright = u'2010, LeafLabs, LLC' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.0' -# The full version, including alpha/beta/rc tags. -# FIXME [0.0.12] 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' : 'Lucidia' -} - -# 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 + ' Documentation' - -# 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. -# re-add commented line when custom template for api finished -html_sidebars = { - '**': ['globaltoc.html', 'searchbox.html'], - #'lang/api**':['searchbox.html', 'apilist.html'], -} - - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# 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 ------------------------------------------ - -breathe_projects = {'libmaple' : os.path.join(os.environ['LIB_MAPLE_HOME'], - 'docs', 'doxygen', 'xml')} - -breathe_default_project = 'libmaple' diff --git a/docs/source/epilog.rst b/docs/source/epilog.rst deleted file mode 100644 index e64103c..0000000 --- a/docs/source/epilog.rst +++ /dev/null @@ -1,8 +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/ diff --git a/docs/source/external-interrupts.rst b/docs/source/external-interrupts.rst deleted file mode 100644 index 9089d77..0000000 --- a/docs/source/external-interrupts.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. highlight:: cpp - -.. _external-interrupts: - -External Interrupts -=================== - -External interrupts can be used to make a voltage change on a pin -cause a function to be called. Each :ref:`GPIO pin <gpio>` can be -used to detect transitions, such as when the voltage goes from -:ref:`LOW <lang-constants-low>` to :ref:`HIGH <lang-constants-high>`, -or from ``HIGH`` to ``LOW``. This can be used to avoid checking for -changes on a pin "manually" by waiting in a loop until the pin -changes. - -.. _contents: Contents - :local: - -Overview --------- - -External interrupts are often used to detect when events happen -outside of the Maple. These can be used to tell Maple when events -happen, such as when a sensor has data ready to be read, or when a -button has been pushed. When such an event happens, an interrupt is -raised, and the Maple stops whatever it was doing to react to it by -calling a function (called an *interrupt handler*) which you specify -using :ref:`lang-attachinterrupt`. - -.. _external-interrupts-exti-line: - -Every pin can generate an external interrupt, but there are some -restrictions. At most 16 different external interrupts can be used at -one time. Further, you can't just pick any 16 pins to use. This is -because every pin on the Maple connects to what is called an *EXTI -line*, and only one pin per EXTI line can be used for external -interrupts at a time [#fextisports]_. - -.. TODO [0.0.12] Maple Native links - -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>` - -.. 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``). - -Function Reference ------------------- - -- :ref:`attachInterrupt() <lang-attachinterrupt>` -- :ref:`detachInterrupt() <lang-detachinterrupt>` - -Recommended Reading -------------------- - -* ST manual `RM0008 - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - (PDF), Chapter 9, "General-purpose and alternate-function I/Os", and - Chapter 10, "Interrupts and Events". - -.. rubric:: Footnotes - -.. [#fextisports] The underlying reason for this restriction is that - the external interrupt lines on the STM32 are shared between - :ref:`GPIO ports <gpio-ports>`. There can be only one external - interrupt on each GPIO bit, out of all of the ports. That is, if - PA4 has an external interrupt on it, then PB4 can't have one, too. - Since the GPIO bit numbers only go from 0 to 15, there can only be - 16 external interrupts at a time. diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst deleted file mode 100644 index af1de20..0000000 --- a/docs/source/gpio.rst +++ /dev/null @@ -1,107 +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: - -.. TODO [0.0.12] Native link - -* :ref:`Maple <maple-gpios>` -* :ref:`Maple RET6 Edition <maple-ret6-gpios>` -* :ref:`Maple Mini <maple-mini-gpios>` - -.. * :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/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_ - (PDF); general, definitive resource for 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. - -.. rubric:: Footnotes - -.. [#fnumports] The total number of GPIO ports depends on what board - you have. For example, Maple Mini has three: ports A, B, and C. - Maple Native has seven: ports A through G. diff --git a/docs/source/hardware/maple-mini.rst b/docs/source/hardware/maple-mini.rst deleted file mode 100644 index b142e77..0000000 --- a/docs/source/hardware/maple-mini.rst +++ /dev/null @@ -1,367 +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: **STM32F103RCBT6**, a 32-bit ARM Cortex M3 microprocessor -* Clock Speed: **72 MHz** -* **128 KB Flash** and **20 KB SRAM** -* 34 Digital I/O Pins (:ref:`gpio`) -* 12 **PWM** pins at 16 bit resolution (:ref:`pwm`) -* 9 analog input pins, 12 bit **ADC** resolution (:ref:`adc`) -* 2 **SPI** peripherals (:ref:`spi`) -* 2 **I2C** peripherals (:ref:`i2c`) -* 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) -* 3 **USART** peripherals (:ref:`usart`) -* 1 advanced and 3 general-purpose **timers** (:ref:`timers`) -* Dedicated **USB** port for programming and communications (:ref:`usb`) -* **JTAG** (:ref:`jtag`) -* Nested Vectored Interrupt Controller (NVIC) (including - :ref:`external interrupt <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:`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**. - - See :ref:`this erratum <maple-mini-vin>` for more information. - -.. _maple-mini-gpios: - -GPIO Information ----------------- - -The Maple Mini features 34 total input/output pins, numbered ``D0`` -through ``D33``. These numbers correspond to the numeric values next -to each header on the Maple Mini's silkscreen. However, some of them -have special uses by default [#fusedpins]_. - -.. _maple-mini-usb-pins: - -Pin ``D23`` is the :ref:`USB <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>`. - -.. 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>` on the Maple. - -.. list-table:: - :widths: 1 1 - :header-rows: 1 - - * - EXTI Line - - Pins - * - EXTI0 - - 3, 11 - * - EXTI1 - - 10, 33 - * - EXTI2 - - 2, 9 - * - EXTI3 - - 8, 19 - * - EXTI4 - - 7, 18 - * - EXTI5 - - 6, 17 - * - EXTI6 - - 5, 16 - * - EXTI7 - - 4, 15 - * - EXTI8 - - 27, 32 - * - EXTI9 - - 26 - * - EXTI10 - - 1, 25 - * - EXTI11 - - 0, 24 - * - EXTI12 - - 23, 31 - * - EXTI13 - - 14, 22, 30 - * - EXTI14 - - 13, 21, 29 - * - EXTI15 - - 12, 20, 28 - -.. _maple-mini-usart-map: - -USART Pin Map -^^^^^^^^^^^^^ - -The Maple RET6 Edition has three serial ports whose pins are broken -out to headers (also known as :ref:`USARTs <usart>`). They communicate -using the pins summarized in the following table: - -.. csv-table:: - :header: Serial Port, TX, RX, CK, CTS, RTS - :delim: | - - ``Serial1`` | 26 | 25 | 27 | 24 | 23 - ``Serial2`` | 9 | 8 | 7 | 11 | 10 - ``Serial3`` | 1 | 0 | 31 | 30 | 29 - -.. _maple-mini-adc-bank: - -Low-Noise ADC Pins -^^^^^^^^^^^^^^^^^^ - -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 16 V. We - recommend an input voltage **no greater than 12 V**. - - The voltage regulator on the Mini is rated up to 16 V. However, our - tests indicate that as its input voltage approaches 16 V, its output - begins to rise to levels higher than those recommended by ST for - supplying the STM32F103CB. The limit of 12 V keeps the voltage - supplied to the processor at safe levels. - -Recommended Reading -------------------- - -STMicro documentation for STM32F103CB microcontroller: - -* `Datasheet - <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); general, definitive resource for STM32F1 line. -* `Programming Manual PM0056 - <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_ - (PDF); assembly language and register reference. -* `STM32F103CB <http://www.st.com/internet/mcu/product/189782.jsp>`_ - overview page with links to further references. - -.. rubric:: Footnotes - -.. [#fusedpins] See :ref:`boardUsedPins <lang-board-values-used-pins>` - for more information. diff --git a/docs/source/hardware/maple-native.rst b/docs/source/hardware/maple-native.rst deleted file mode 100644 index 79115fc..0000000 --- a/docs/source/hardware/maple-native.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _hardware-maple-native: - -Maple Native -============ - -Stub. diff --git a/docs/source/hardware/maple-ret6.rst b/docs/source/hardware/maple-ret6.rst deleted file mode 100644 index 1de2465..0000000 --- a/docs/source/hardware/maple-ret6.rst +++ /dev/null @@ -1,442 +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 than the one on the base Maple -(the STM32F103RET6, hence the name) in the hands of Maple developers. - -.. contents:: Contents - :local: - -.. TODO [dma.rst] Ref to dma.rst in sequel instead of libmaple-dma -.. TODO [dac.rst] Ref to dac.rst in sequel instead of libmaple-dac -.. TODO [nvic.rst] Ref to nvic.rst in sequel - -Technical Specifications ------------------------- - -* MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor -* Clock Speed: **72 MHz** -* **512 KB Flash** and **64 KB SRAM** -* 43 Digital I/O Pins (:ref:`gpio`) -* 18 **PWM** pins at 16 bit resolution (:ref:`pwm`) -* 15 analog input pins, 12 bit **ADC** resolution (:ref:`adc`) -* Built-in, 2 channel **DAC** at 12 bit resolution (:ref:`libmaple-dac`). -* 2 **SPI** peripherals with **I2S** support (:ref:`spi`) -* 2 **I2C** peripherals (:ref:`i2c`) -* 12 Channels of Direct Memory Access (**DMA**) - (:ref:`libmaple-dma`) with 2 DMA controllers -* 3 **USART** devices (:ref:`usart`) -* 2 advanced, 4 general-purpose, and 2 basic **timers** (:ref:`timers`) -* Dedicated **USB** port for programming and communications (:ref:`usb`) -* **JTAG** (:ref:`jtag`) -* Nested Vectored Interrupt Controller (NVIC) (including - :ref:`external interrupt <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:`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 12 V**. - - See :ref:`this erratum <maple-barrel-jack>` for more information. - -Using the Built-in Battery Charger ----------------------------------- - -The RET6 Edition has a built-in LiPo battery charger. In order to use -it, put a jumper across the CHRG header on the power selection header -and across the USB, or EXT selectors, depending on whether you're -charging the battery via USB cable or barrel jack connector. The LED -labeled CHRG will light up while the battery is being charged. When -the battery is finished charging, the LED labeled DONE will also light -up. - -.. _maple-ret6-gpios: - -GPIO Information ----------------- - -The RET6 Edition features 38 ready-to-use general purpose input/output -(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>`. - -.. 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 - - 2, 15, 27 - * - EXTI1 - - 3, 16, 28 - * - EXTI2 - - 1, 17, 25 - * - EXTI3 - - 0, 18, 42 - * - EXTI4 - - 10, 19 - * - EXTI5 - - 4, 13, 20 - * - EXTI6 - - 5, 12, 35 - * - EXTI7 - - 9, 11, 36 - * - EXTI8 - - 6, 14, 37 - * - EXTI9 - - 7, 25, 28 - * - EXTI10 - - 8, 26, 29 - * - EXTI11 - - 30 - * - EXTI12 - - 31 - * - EXTI13 - - 21, 32, 39 - * - EXTI14 - - 22, 33, 40 - * - EXTI15 - - 23, 34, 41 - -.. _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 summarized in the following table: - -.. csv-table:: - :header: Serial Port, TX, RX, CK, CTS, RTS - :delim: | - - ``Serial1`` | 7 | 8 | 6 | - | - - ``Serial2`` | 1 | 0 | 10 | 2 | 3 - ``Serial3`` | 29 | 30 | 31 | 32 | 33 - -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 silkscreen next to - the barrel jack connector incorrectly indicates that up to an 18 V - input voltage is allowed. **We do not recommend exceeding 12 V**. - - See this :ref:`Maple erratum <maple-barrel-jack>` 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 libmaple) its - output is buffered by default, so this may not significantly - interfere with its functionality. - -.. _maple-ret6-nrst-pb4: - -* **Reset and PB4 tied together**: The RET6 Edition's reset line is - also connected to PB4, which is labeled on the silkscreen as pin 43. - Thus, attempting to use pin 43 as a GPIO 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 -------------------- - -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); general, definitive resource for STM32F1 line. -* `Programming Manual PM0056 - <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_ - (PDF); assembly language and register reference. -* `STM32F103RE <http://www.st.com/internet/mcu/product/164485.jsp>`_ - overview page with links to further references. diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst deleted file mode 100644 index 91198f2..0000000 --- a/docs/source/hardware/maple.rst +++ /dev/null @@ -1,572 +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: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor -* Clock Speed: **72 MHz** -* **128 KB Flash** and **20 KB SRAM** -* 43 Digital I/O Pins (:ref:`gpio`) -* 15 **PWM** pins at 16 bit resolution (:ref:`pwm`) -* 15 analog input pins, 12-bit **ADC** resolution (:ref:`adc`) -* 2 **SPI** peripherals (:ref:`spi`) -* 2 **I2C** peripherals (:ref:`i2c`) -* 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`) -* 3 **USART** peripherals (:ref:`usart`) -* One advanced and three general-purpose **timers** (:ref:`timers`) -* Dedicated **USB** port for programming and communications (:ref:`usb`) -* **JTAG** (:ref:`jtag`) -* Nested Vectored Interrupt Controller (NVIC) (including - :ref:`external interrupt <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:`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. - -.. warning:: Silkscreens on Maples up through Rev 5s manufactured in - Spring 2011 falsely indicated that the barrel jack could be - supplied by up to 18 V. We recommend a barrel jack input voltage - **no greater than 12 V**. - - See :ref:`this erratum <maple-barrel-jack>` for more information. - -Using the Built-in Battery Charger ----------------------------------- - -Maples Rev 3 and Rev 5 also have a built-in LiPo battery charger. In -order to use it, put a jumper across the CHRG header on the power -selection header and across the USB, or EXT selectors, depending on -whether you're charging the battery via USB cable or barrel jack -connector. The LED labeled CHRG will light up while the battery is -being charged. When the battery is finished charging, the LED labeled -DONE will also light up. - -.. _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>`. - -.. 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 - - 2, 15, 27 - * - EXTI1 - - 3, 16, 28 - * - EXTI2 - - 1, 17, 25 - * - EXTI3 - - 0, 18, 42 - * - EXTI4 - - 10, 19 - * - EXTI5 - - 4, 13, 20 - * - EXTI6 - - 5, 12, 35 - * - EXTI7 - - 9, 11, 36 - * - EXTI8 - - 6, 14, 37 - * - EXTI9 - - 7, 25, 28 - * - EXTI10 - - 8, 26, 29 - * - EXTI11 - - 30 - * - EXTI12 - - 31 - * - EXTI13 - - 21, 32, 39 - * - EXTI14 - - 22, 33, 40 - * - EXTI15 - - 23, 34, 41 - -.. _maple-usart-map: - -USART Pin Map -^^^^^^^^^^^^^ - -The Maple has three serial ports (also known as USARTs): ``Serial1``, -``Serial2``, and ``Serial3``. They communicate using the pins -summarized in the following table: - -.. csv-table:: - :header: Serial Port, TX, RX, CK, CTS, RTS - :delim: | - - ``Serial1`` | 7 | 8 | 6 | - | - - ``Serial2`` | 1 | 0 | 10 | 2 | 3 - ``Serial3`` | 29 | 30 | 31 | 32 | 33 - -.. _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 7 - V — 18 V. In fact, **18 V is too high** and should not be supplied - to your board. The recommended maximum voltage you should apply is - **12 V**. - - The original voltage regulators used on the Maple were rated up to - 18 V. However, the voltage regulators on current Maple Revs are - rated up to 16 V. Our tests indicate that they operate correctly - through 12 V. We do not recommend higher input voltages. - -.. _maple-nrst-pb4: - -* **Reset and PB4 tied together**: The Maple's reset line is also - connected to PB4, which is labeled on the silkscreen as pin 43. - Thus, attempting to use pin 43 as a GPIO can reset your board. This - has other implications. Since PB4 is also the JTAG NJTRST line, - this prevents the :ref:`JTAG <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, 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 -------------------- - -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); general, definitive resource for STM32F1 line. -* `Programming Manual PM0056 - <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_ - (PDF); assembly language and register reference. -* `STM32F103RB <http://www.st.com/internet/mcu/product/164487.jsp>`_ - overview page with links to further references. - -.. rubric:: Footnotes - -.. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal - testing. diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst deleted file mode 100644 index 670b91d..0000000 --- a/docs/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/playground/Learning/I2C>`_ -* ST `Application Note on Advanced I2C Usage - <http://www.st.com/stonline/products/literature/an/15021.pdf>`_ (PDF) diff --git a/docs/source/ide.rst b/docs/source/ide.rst deleted file mode 100644 index b3ef653..0000000 --- a/docs/source/ide.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. _ide: - -Maple IDE -========= - -This page documents the basic functionality of the Maple IDE. -Specifically, it describes the operation of the buttons on the main -toolbar. It is expected to become more comprehensive over time. - -The :ref:`Maple Quickstart <maple-quickstart>` is another good source of -information on the IDE; it is especially useful for setting up a -computer for the first time. - -.. figure:: /_static/img/ide-blinky.png - :align: center - :alt: Maple IDE - -.. _ide-verify: - -Verify ------- - -.. image:: /_static/img/button-verify.png - :align: left - -Click Verify to compile the current sketch. - -.. _ide-stop: - -Stop ----- - -.. image:: /_static/img/button-stop.png - :align: left - -Click Stop to cancel a compilation. - -.. _ide-new: - -New ---- - -.. image:: /_static/img/button-new.png - :align: left - -Click New to begin a fresh sketch. - -.. _ide-open: - -Open ----- - -.. image:: /_static/img/button-open.png - :align: left - -Click Open to open a new sketch. By default, this will look in you -*sketchbook*, which is a directory on your system which contains all -of your sketches. The default directory of your sketchbook varies by -operating system; you can change it in the IDE preferences. - -.. _ide-save: - -Save ----- - -.. image:: /_static/img/button-save.png - :align: left - -Click Save to save the currently opened sketch. - -.. _ide-upload: - -Upload ------- - -.. image:: /_static/img/button-upload.png - :align: left - -Click Upload to send the compiled sketch to your Maple to run. Before -you click Upload, you must have a memory location and serial port -selected. The memory location, either Flash or RAM, determines -whether the compiled sketch binary will be stored on the Maple. You -can choose this using the Tools > Board menu. The serial port -corresponds to the Serial-over-USB connection the Maple has -established with your computer. This looks like "COM1", "COM2", -etc. on Windows, "/dev/tty.usbmodemXXX" on Mac (where "XXX" is some -sequence of letters and numbers), or "/dev/ttyACMXXX" on Linux (again, -where "XXX" is some sequence of letters and numbers). You can choose -a serial port using the Tools > Serial Port menu. - -If you click Upload without having made these choices; The IDE -*should* prompt you to do so. However, if you're trying to upload and -are unsuccessful, make sure you've made choices for both board and -serial port. - -For more help, the upload process is documented in more detail (with -screenshots) in the :ref:`quickstart <maple-quickstart-upload>`. - -If all else fails, try putting your Maple in :ref:`perpetual -bootloader mode <troubleshooting-perpetual-bootloader>` before -uploading. - -In any case, you can always find us on the `forum`_ or `contact us -directly`_. - -.. _ide-serial-monitor: - -Serial Monitor --------------- - -.. image:: /_static/img/button-serial-monitor.png - :align: left - -Click Serial Monitor to open up a communications channel between your -PC and the Maple's :ref:`Serial-over-USB <lang-serialusb>` -(``SerialUSB``) virtual serial port. - -If the serial monitor is open, any information sent to the computer -(e.g. using :ref:`SerialUSB.println() <lang-serialusb-println>` will -be displayed in the large text area. You can send data to the Maple -(to be read with e.g. :ref:`SerialUSB.read() <lang-serialusb-read>`) -by typing into the small text box and either hitting the Enter key or -pressing the Send button. - -Here is an example serial monitor session with the InteractiveTest -sketch (which you can load in the IDE by choosing menu item File > -Examples > Maple > InteractiveTest): - -.. image:: /_static/img/serial-monitor.png - -This is the result of typing "?" in the text box and clicking Send. - -.. note:: You cannot upload a sketch while the serial monitor is open. - If you click :ref:`Upload <ide-upload>` while the serial monitor is - open, the IDE will close it for you before proceeding with the - upload. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index d17c4db..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _index: - -LeafLabs Documentation Index -============================ - -Welcome! This is the Maple documentation index. - -If you just bought a Maple board, you probably want to head to the -:ref:`quickstart <maple-quickstart>`. If you're having problems, -check out the :ref:`troubleshooting <troubleshooting>` page. - -Have fun! - -.. _index-usage: - -**Usage Guides:** - -.. toctree:: - :maxdepth: 1 - - Quickstart <maple-quickstart> - IDE Installation <maple-ide-install> - IDE Usage <ide> - Command-Line Toolchain <unix-toolchain> - -.. _index-maple-programming: - -**Maple Programming:** - -.. toctree:: - :maxdepth: 1 - - Language <language> - Libraries <libraries> - Arduino Compatibility <arduino-compatibility> - libmaple <libmaple> - Bootloader <bootloader> - Troubleshooting <troubleshooting> - Notes on GCC's ARM target <arm-gcc> - Complete Language Index <language-index> - -.. _index-hardware: - -**Hardware Peripherals:** - -.. toctree:: - :maxdepth: 1 - - adc - external-interrupts - gpio - i2c - jtag - pwm - spi - timers - systick - usb - usart - -.. _index-boards: - -**Board Hardware Documentation:** - -.. toctree:: - :maxdepth: 1 - - hardware/maple.rst - hardware/maple-ret6.rst - hardware/maple-mini.rst - -.. TODO write/include these upon Mini and Native release -.. hardware/maple-native.rst diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst deleted file mode 100644 index 0558a29..0000000 --- a/docs/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 - - JTAG wiring diagram (`large version - <http://leaflabs.com/wp-content/uploads/2010/11/maple-jtagadapter.png>`_) - to connect a standard 20-pin ARM JTAG device to the 8-pin JTAG port - on the Maple. - -The Maple has holes for a 8-pin JTAG header, but that header is not -soldered on. To use JTAG, simply solder on standard 0.1" pitch male -header pins (either the exact 4 by 2 block, or two 4-pin pieces of -straight breakaway header). - -Compatible Devices ------------------- - -We have had good experience with the `Olimex ARM-USB-OCD -<http://www.olimex.com/dev/arm-usb-ocd.html>`_ device, which costs -about €55 plus shipping (as of April 2011). - -Function Reference ------------------- - -You can disable or enable the JTAG and Serial Wire debugging ports in -software using the ``disableDebugPorts()`` and ``enableDebugPorts()`` -functions. - -* :ref:`lang-disabledebugports` -* :ref:`lang-enabledebugports` - -Recommended Reading -------------------- - -* `Wikipedia Article on Joint Test Action Group (JTAG) - <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ - -* `STM32, GDB, OpenOCD How To - <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_ - -* `LeafLabs Wiki JTAG How To - <http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ - -* `LeafLabs forum thread on JTAG - <http://forums.leaflabs.com/topic.php?id=536>`_ - -* ST documentation: - - * Reference Manual `RM0008 - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - (PDF), Chapter 31, "Debug support", and Chapter 9, - "General-purpose and alternate function I/Os". diff --git a/docs/source/lang/api/abs.rst b/docs/source/lang/api/abs.rst deleted file mode 100644 index d9f1ca3..0000000 --- a/docs/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/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst deleted file mode 100644 index 6665a94..0000000 --- a/docs/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/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst deleted file mode 100644 index 0169976..0000000 --- a/docs/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/docs/source/lang/api/assert.rst b/docs/source/lang/api/assert.rst deleted file mode 100644 index 76330b6..0000000 --- a/docs/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/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst deleted file mode 100644 index 39902ac..0000000 --- a/docs/source/lang/api/attachinterrupt.rst +++ /dev/null @@ -1,94 +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 - -Discussion ----------- - -Because the function will run in interrupt context, inside of it, -:ref:`lang-delay` won't work, and the value returned by -:ref:`lang-millis` will not increment. Serial data received while in -the function may be lost. You should declare as ``volatile`` any -global variables that you modify within the attached function. - -There are a few limits you should be aware of if you're using more -than one interrupt at a time; the :ref:`External Interrupts -<external-interrupts-exti-line>` page has more information. - -Example -------- - - :: - - volatile int state = LOW; // must declare volatile, since it's - // modified within the blink() handler - - void setup() { - pinMode(BOARD_LED_PIN, OUTPUT); - attachInterrupt(0, blink, CHANGE); - } - - void loop() { - digitalWrite(BOARD_LED_PIN, state); - } - - void blink() { - state = !state; - } - -Arduino Compatibility ---------------------- - -Most Arduino boards have two external interrupts: numbers 0 (on -digital pin 2) and 1 (on digital pin 3). The Arduino Mega has an -additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 -(pin 18). On the Maple, you don't have to remember which interrupt -number goes with which pin -- just tell ``attachInterrupt()`` the pin -you want. - -See Also --------- - -- :ref:`lang-detachinterrupt` -- :ref:`external-interrupts` - -.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bit.rst b/docs/source/lang/api/bit.rst deleted file mode 100644 index 3df042c..0000000 --- a/docs/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/docs/source/lang/api/bitclear.rst b/docs/source/lang/api/bitclear.rst deleted file mode 100644 index f487059..0000000 --- a/docs/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/docs/source/lang/api/bitread.rst b/docs/source/lang/api/bitread.rst deleted file mode 100644 index fd9fbbe..0000000 --- a/docs/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/docs/source/lang/api/bitset.rst b/docs/source/lang/api/bitset.rst deleted file mode 100644 index 83ab5f8..0000000 --- a/docs/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/docs/source/lang/api/bitwrite.rst b/docs/source/lang/api/bitwrite.rst deleted file mode 100644 index 6106545..0000000 --- a/docs/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/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst deleted file mode 100644 index d944c8d..0000000 --- a/docs/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/docs/source/lang/api/boardusespin.rst b/docs/source/lang/api/boardusespin.rst deleted file mode 100644 index 126c4a0..0000000 --- a/docs/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/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst deleted file mode 100644 index 6f69dfe..0000000 --- a/docs/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/docs/source/lang/api/constrain.rst b/docs/source/lang/api/constrain.rst deleted file mode 100644 index 28af1e3..0000000 --- a/docs/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/docs/source/lang/api/cos.rst b/docs/source/lang/api/cos.rst deleted file mode 100644 index c340f09..0000000 --- a/docs/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/docs/source/lang/api/delay.rst b/docs/source/lang/api/delay.rst deleted file mode 100644 index 30bd436..0000000 --- a/docs/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/docs/source/lang/api/delaymicroseconds.rst b/docs/source/lang/api/delaymicroseconds.rst deleted file mode 100644 index 7078660..0000000 --- a/docs/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/docs/source/lang/api/detachinterrupt.rst b/docs/source/lang/api/detachinterrupt.rst deleted file mode 100644 index 82ce974..0000000 --- a/docs/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 detachInterupt(), -.. replace with doxygenfunction. - -.. cpp:function:: void detachInterrupt(uint8 pin) - - Disable any registered external interrupt on the given pin. - - *Parameters* - - - ``pin`` Maple pin number - -Arduino Compatibility ---------------------- - -There is one important difference between the Maple version of -detachInterrupt and the Arduino version. On the Maple, the argument -to ``detachInterrupt()`` is the *pin* on which the interrupt is -attached, while on the Arduino, the argument is the *interrupt -number*, which is different from the pin the interrupt is enabled on. - -If you're calling this function, you've already called -:ref:`lang-attachinterrupt` to set up your interrupt handler, so -just call ``detachInterrupt()`` with the same pin argument you gave to -``attachInterrupt()``. - -See Also --------- - -- :ref:`attachInterrupt() <lang-attachInterrupt>` -- :ref:`external-interrupts` - -.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/digitalread.rst b/docs/source/lang/api/digitalread.rst deleted file mode 100644 index ccf4a4c..0000000 --- a/docs/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, val); - } - -Arduino Compatibility ---------------------- - -The Maple version of ``digitalRead()`` is compatible with Arduino. - -See Also --------- - -- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>` -- :ref:`lang-isButtonPressed` -- :ref:`lang-pinmode` -- :ref:`lang-digitalWrite` -- :ref:`lang-togglepin` - -.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/digitalwrite.rst b/docs/source/lang/api/digitalwrite.rst deleted file mode 100644 index bae8db9..0000000 --- a/docs/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/docs/source/lang/api/disabledebugports.rst b/docs/source/lang/api/disabledebugports.rst deleted file mode 100644 index 283cdbf..0000000 --- a/docs/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/docs/source/lang/api/enabledebugports.rst b/docs/source/lang/api/enabledebugports.rst deleted file mode 100644 index bee2b0a..0000000 --- a/docs/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/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst deleted file mode 100644 index 054d1a8..0000000 --- a/docs/source/lang/api/hardwarespi.rst +++ /dev/null @@ -1,165 +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 ---------------- - -.. TODO [0.1.0] Add a note about calling disableDebugPorts() when -.. using SPI3 on Maple Native - -In order to get started, you'll first need to define a ``HardwareSPI`` -variable, which you'll use to control the SPI port. Do this by -putting the line "``HardwareSPI spi(number);``" with your variables, -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 - -The speed at which the SPI port communicates is configured using a -``SPIFrequency`` value: - -.. FIXME [0.1.0] Breathe's enum output is enormous; shrink & submit pull req - -.. doxygenenum:: SPIFrequency - -.. note:: Due to hardware issues, you can't use the frequency - ``SPI_140_625KHz`` with SPI port 1. - -You'll need to determine the correct values for ``frequency``, -``bitOrder``, and ``mode`` yourself, by consulting the datasheet for -the device you're communicating with. Continuing our example from -before, we'll add a call to ``begin()`` to our ``setup()``:: - - // Use SPI port number 1 - HardwareSPI spi(1); - - void setup() { - // 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::transmit(byte data) - - Send a byte, then return the next byte received. - - **Parameters:** - - - ``data``: Byte to send - - **Returns:** Next unread byte - -Continuing our example from before, let's send a number over SPI and -print out whatever we get back over :ref:`lang-serialusb`:: - - // Use SPI port number 1 - HardwareSPI spi(1); - - void setup() { - // Turn on the SPI port - spi.begin(SPI_18MHZ, MSBFIRST, 0); - } - - void loop() { - // Send 245 over SPI, and wait for a response. - spi.write(245); - byte response = spi.read(); - // Print out the response received. - SerialUSB.print("response: "); - SerialUSB.println(response, DEC); - } - -HardwareSPI Class Reference ---------------------------- - -There are a number of other things you can accomplish with your -``spi`` object. A full function listing follows. - -.. doxygenclass:: HardwareSPI - :members: HardwareSPI, begin, beginSlave, end, read, write, transfer - -Deprecated Functions --------------------- - -The following functions are defined for now, but they have been -deprecated, and will be removed in a future Maple IDE release. You -shouldn't use them in new programs, and you should change any of your -programs which do use them to the up-to-date functions discussed -above. - -.. cpp:function:: uint8 HardwareSPI::send(uint8 *data, uint32 length) - - Writes ``data`` into the port buffer to be transmitted as soon as - possible, where ``length`` is the number of bytes to send from - ``data``. Returns the last byte shifted back from slave. - -.. cpp:function:: uint8 HardwareSPI::send(uint8 data) - - Writes the single byte ``data`` into the port buffer to be - transmitted as soon as possible. Returns the data byte shifted - back from the slave. - -.. cpp:function:: uint8 HardwareSPI::recv() - - Reads a byte from the peripheral. Returns the next byte in the - buffer. diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst deleted file mode 100644 index 09245f0..0000000 --- a/docs/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.setChannel1Mode(TIMER_OUTPUT_COMPARE); - timer.setCompare(TIMER_CH1, 1); // Interrupt 1 count after each update - timer.attachCompare1Interrupt(handler_led); - - // Refresh the timer's count, prescale, and overflow - timer.refresh(); - - // Start the timer counting - timer.resume(); - } - - void loop() { - // Nothing! It's all in the handler_led() interrupt: - } - - void handler_led(void) { - toggleLED(); - } - -**Racing Counters**: This example shows how to use multiple timers at -the same time. :: - - int count3 = 0; - int count4 = 0; - - // We'll use timers 3 and 4 - HardwareTimer timer3(3); - HardwareTimer timer4(4); - - void setup() { - // Set up the button for input - pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); - - // Set up timers to add 1 to their counts each time - // their interrupts fire. - timer3.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE); - timer4.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE); - timer3.pause(); - timer4.pause(); - timer3.setCount(0); - timer4.setCount(0); - timer3.setOverflow(30000); - timer4.setOverflow(30000); - timer3.setCompare(TIMER_CH1, 1000); // somewhere in the middle - timer4.setCompare(TIMER_CH1, 1000); - timer3.attachCompare1Interrupt(handler3); - timer4.attachCompare1Interrupt(handler4); - timer3.refresh(); - timer4.refresh(); - timer3.resume(); - timer4.resume(); - } - - void loop() { - // Display the running counts - SerialUSB.print("Count 3: "); - SerialUSB.print(count3); - SerialUSB.print("\t\tCount 4: "); - SerialUSB.println(count4); - - // While the button is held down, pause timer 4 - for (int i = 0; i < 1000; i++) { - if (digitalRead(BOARD_BUTTON_PIN)) { - timer4.pause(); - } else { - timer4.resume(); - } - delay(1); - } - } - - void handler3(void) { - count3++; - } - - void handler4(void) { - count4++; - } - -``HardwareTimer`` Class Reference ---------------------------------- - -This section gives a full listing of the capabilities of a -``HardwareTimer``. - -.. doxygenclass:: HardwareTimer - :members: HardwareTimer, pause, resume, getPrescaleFactor, setPrescaleFactor, getOverflow, setOverflow, getCount, setCount, setPeriod, setMode, getCompare, setCompare, attachInterrupt, detachInterrupt, refresh - -.. _lang-hardwaretimer-timermode: - -.. doxygenenum:: timer_mode - -Deprecated Functionality ------------------------- - -The following functionality exists for now, but it has been -deprecated, and will be removed in a future Maple IDE release. You -shouldn't use it in new programs, and you should change any of your -programs which do use them to use the up-to-date features described -above. - -The ``TimerMode`` type from previous releases has been renamed -``timer_mode``. The mode ``TIMER_OUTPUTCOMPARE`` is still present, -but will be removed in a future release. Use ``TIMER_OUTPUT_COMPARE`` -instead. - -.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) - - Use ``attachInterrupt(1, handler)`` instead. - -.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) - - Use ``attachInterrupt(2, handler)`` instead. - -.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) - - Use ``attachInterrupt(3, handler)`` instead. - -.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) - - Use ``attachInterrupt(4, handler)`` instead. - -.. _lang-hardwaretimer-setchannelmode: - -.. cpp:function:: void HardwareTimer::setChannelMode(int channel, timer_mode mode) - - Use ``setMode(channel, mode)`` instead. - -.. cpp:function:: void HardwareTimer::setChannel1Mode(timer_mode mode) - - Use ``setMode(1, mode)`` instead. - -.. cpp:function:: void HardwareTimer::setChannel2Mode(timer_mode mode) - - Use ``setMode(2, mode)`` instead. - -.. cpp:function:: void HardwareTimer::setChannel3Mode(timer_mode mode) - - Use ``setMode(3, mode)`` instead. - -.. cpp:function:: void HardwareTimer::setChannel4Mode(timer_mode mode) - - Use ``setMode(4, mode)`` instead. - -.. cpp:function:: uint16 HardwareTimer::getCompare1() - - Use ``getCompare(1, mode)`` instead. - -.. cpp:function:: uint16 HardwareTimer::getCompare2() - - Use ``getCompare(2, mode)`` instead. - -.. cpp:function:: uint16 HardwareTimer::getCompare3() - - Use ``getCompare(3, mode)`` instead. - -.. cpp:function:: uint16 HardwareTimer::getCompare4() - - Use ``getCompare(4, mode)`` instead. - -.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) - - Use ``setCompare(1, compare)`` instead. - -.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) - - Use ``setCompare(2, compare)`` instead. - -.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) - - Use ``setCompare(3, compare)`` instead. - -.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) - - Use ``setCompare(4, compare)`` instead. - -.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() - - Use ``detachInterrupt(1)`` instead. - -.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() - - Use ``detachInterrupt(2)`` instead. - -.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() - - Use ``detachInterrupt(3)`` instead. - -.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() - - Use ``detachInterrupt(4)`` instead. - -.. cpp:function:: void HardwareTimer::generateUpdate() - - Use ``refresh()`` instead. - -In previous releases, to interact with a particular timers, you would -use one of the predefined ``HardwareTimer`` instances ``Timer1``, -``Timer2``, ``Timer3``, and ``Timer4``. These are still available for -now, but they are also deprecated, and will be removed in a future -release. As detailed in :ref:`lang-hardwaretimer-getting-started`, -you should define your own ``HardwareTimer`` variables. diff --git a/docs/source/lang/api/highbyte.rst b/docs/source/lang/api/highbyte.rst deleted file mode 100644 index 4cb6f9b..0000000 --- a/docs/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/docs/source/lang/api/interrupts.rst b/docs/source/lang/api/interrupts.rst deleted file mode 100644 index 58fd2cc..0000000 --- a/docs/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/docs/source/lang/api/isbuttonpressed.rst b/docs/source/lang/api/isbuttonpressed.rst deleted file mode 100644 index 8c350b9..0000000 --- a/docs/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/docs/source/lang/api/loop.rst b/docs/source/lang/api/loop.rst deleted file mode 100644 index c2a5097..0000000 --- a/docs/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/docs/source/lang/api/lowbyte.rst b/docs/source/lang/api/lowbyte.rst deleted file mode 100644 index c513711..0000000 --- a/docs/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/docs/source/lang/api/map.rst b/docs/source/lang/api/map.rst deleted file mode 100644 index 69661a0..0000000 --- a/docs/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/docs/source/lang/api/max.rst b/docs/source/lang/api/max.rst deleted file mode 100644 index d356f08..0000000 --- a/docs/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/docs/source/lang/api/micros.rst b/docs/source/lang/api/micros.rst deleted file mode 100644 index de85303..0000000 --- a/docs/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/docs/source/lang/api/millis.rst b/docs/source/lang/api/millis.rst deleted file mode 100644 index b6fbf55..0000000 --- a/docs/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/docs/source/lang/api/min.rst b/docs/source/lang/api/min.rst deleted file mode 100644 index 3307105..0000000 --- a/docs/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/docs/source/lang/api/nointerrupts.rst b/docs/source/lang/api/nointerrupts.rst deleted file mode 100644 index 68f0498..0000000 --- a/docs/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/docs/source/lang/api/pinmode.rst b/docs/source/lang/api/pinmode.rst deleted file mode 100644 index 643e26e..0000000 --- a/docs/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/docs/source/lang/api/pow.rst b/docs/source/lang/api/pow.rst deleted file mode 100644 index 219a866..0000000 --- a/docs/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/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst deleted file mode 100644 index 5cc112e..0000000 --- a/docs/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/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst deleted file mode 100644 index 9875ee6..0000000 --- a/docs/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/docs/source/lang/api/randomseed.rst b/docs/source/lang/api/randomseed.rst deleted file mode 100644 index ca7b75f..0000000 --- a/docs/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/docs/source/lang/api/serial.rst b/docs/source/lang/api/serial.rst deleted file mode 100644 index a08c9b7..0000000 --- a/docs/source/lang/api/serial.rst +++ /dev/null @@ -1,201 +0,0 @@ -.. _lang-serial: - -Serial Ports (``Serial1``, ``Serial2``, ``Serial3``) -==================================================== - -Used for communication between the Maple board and a computer or other -devices. - -.. contents:: Contents - :local: - -Introduction ------------- - -.. FIXME [0.0.12/Maple Native] UART4, UART5 - -To use a serial port to communicate with an external serial device, -connect the TX pin to your device's RX pin, the RX to your device's TX -pin, and your Maple board's ground to your device's ground. - -.. warning:: Don't connect these pins directly to an RS232 serial - port; they operate at +/- 12V and can damage your board. - -Library Documentation ---------------------- - -.. FIXME [0.1.0] Tutorial-style usage introduction - -All of the ``Serial[1,2,3]`` objects are instances of the -``HardwareSerial`` class, which is documented in this section. (This -means that you can use any of these functions on any of ``Serial1``, -``Serial2``, and ``Serial3``). - -.. cpp:class:: HardwareSerial - - Serial port class. Predefined instances are ``Serial1``, - ``Serial2``, and ``Serial3``. - -.. cpp:function:: HardwareSerial::begin(unsigned int baud) - - Set up a ``HardwareSerial`` object for communications. This method - must be called before attempting to use the ``HardwareSerial`` - object (typically, you call this in your :ref:`setup() - <lang-setup>` function). - -.. cpp:function:: HardwareSerial::end() - - Disables the USART associated with this object, allowing any - associated communication pins to be used for other purposes. - -.. cpp:function:: unsigned int HardwareSerial::available() - - Returns the number of bytes available for reading. - -.. cpp:function:: unsigned char HardwareSerial::read() - - Returns the next available, unread character. If there are no - available characters (you can check this with :cpp:func:`available - <HardwareSerial::available>`), the call will block until one - becomes available. - -.. cpp:function:: HardwareSerial::flush() - - Throw away the contents of the serial port's receiver (RX) buffer. - That is, clears any buffered characters, so that the next character - read is guaranteed to be new. - -.. cpp:function:: HardwareSerial::print(unsigned char b) - - Print the given byte over the USART. - -.. cpp:function:: HardwareSerial::print(char c) - - Print the given character over the USART. 7-bit clean characters - are typically interpreted as ASCII text. - -.. cpp:function:: HardwareSerial::print(const char *str) - - Print the given null-terminated string over the USART. - -.. cpp:function:: HardwareSerial::print(int n) - - Print the argument's digits over the USART, in decimal format. - Negative values will be prefixed with a ``'-'`` character. - -.. cpp:function:: HardwareSerial::print(unsigned int n) - - Print the argument's digits over the USART, in decimal format. - -.. cpp:function:: HardwareSerial::print(long n) - - Print the argument's digits over the USART, in decimal format. - Negative values will be prefixed with a ``'-'`` character. - -.. cpp:function:: HardwareSerial::print(unsigned long n) - - Print the argument's digits over the USART, in decimal format. - -.. cpp:function:: HardwareSerial::print(long n, int base) - - Print the digits of ``n`` over the USART, in base ``base`` (which - may be between 2 and 16). The ``base`` value 2 corresponds to - binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative - values will be prefixed with a ``'-'`` character. - -.. cpp:function:: HardwareSerial::print(double n) - - Print ``n``, accurate to 2 digits after the decimal point. - -.. _lang-serial-println: - -.. cpp:function:: HardwareSerial::println(char c) - - Like ``print(c)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(const char *c) - - Like ``print(c)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(unsigned char b) - - Like ``print(b)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(int n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(unsigned int n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(long n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(unsigned long n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(long n, int base) - - Like ``print(n, b)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println(double n) - - Like ``print(n)``, followed by ``"\r\n"``. - -.. cpp:function:: HardwareSerial::println() - - Prints ``"\r\n"`` over the USART. - -.. cpp:function:: HardwareSerial::write(unsigned char ch) - - Sends one character over the USART. This function is currently - blocking, although nonblocking writes are a planned future - extension. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -.. cpp:function:: HardwareSerial::write(const char* str) - - Send the given null-terminated character string over the USART. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -.. cpp:function:: HardwareSerial::write(void *buf, unsigned int size) - - Writes the first ``size`` bytes of ``buf`` over the USART. Each - byte is transmitted as an individual character. - - This is a low-level function. One of the ``print()`` or - ``println()`` functions is likely to be more useful when printing - multiple characters, when formatting numbers for printing, etc. - -Arduino Compatibility Note --------------------------- - -Unlike the Arduino, none of the Maple's serial ports is connected to -the USB port on the Maple board. If you want to communicate using the -built-in USB port, use :ref:`SerialUSB <lang-serialusb>` instead. You -will need an additional USB-to-serial adapter to communicate between a -USART and your computer. - -.. FIXME [0.1.0] port these examples over - -.. Examples -.. -------- - -.. - `ASCII Table <http://arduino.cc/en/Tutorial/ASCIITable>`_ -.. - `Dimmer <http://arduino.cc/en/Tutorial/Dimmer>`_ -.. - `Graph <http://arduino.cc/en/Tutorial/Graph>`_ -.. - `Physical Pixel <http://arduino.cc/en/Tutorial/PhysicalPixel>`_ -.. - `Virtual Color Mixer <http://arduino.cc/en/Tutorial/VirtualColorMixer>`_ -.. - `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_ -.. - `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_ - -.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/serialusb.rst b/docs/source/lang/api/serialusb.rst deleted file mode 100644 index ed466f2..0000000 --- a/docs/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/docs/source/lang/api/setup.rst b/docs/source/lang/api/setup.rst deleted file mode 100644 index 1e8e3b8..0000000 --- a/docs/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/docs/source/lang/api/shiftout.rst b/docs/source/lang/api/shiftout.rst deleted file mode 100644 index 1d9ba12..0000000 --- a/docs/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/docs/source/lang/api/sin.rst b/docs/source/lang/api/sin.rst deleted file mode 100644 index 3e28c0b..0000000 --- a/docs/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/docs/source/lang/api/sq.rst b/docs/source/lang/api/sq.rst deleted file mode 100644 index 96724d3..0000000 --- a/docs/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/docs/source/lang/api/tan.rst b/docs/source/lang/api/tan.rst deleted file mode 100644 index b1aed31..0000000 --- a/docs/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/docs/source/lang/api/toggleled.rst b/docs/source/lang/api/toggleled.rst deleted file mode 100644 index cad347f..0000000 --- a/docs/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/docs/source/lang/api/togglepin.rst b/docs/source/lang/api/togglepin.rst deleted file mode 100644 index 290718d..0000000 --- a/docs/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/docs/source/lang/api/volatile.rst b/docs/source/lang/api/volatile.rst deleted file mode 100644 index 1b72897..0000000 --- a/docs/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/docs/source/lang/api/waitforbuttonpress.rst b/docs/source/lang/api/waitforbuttonpress.rst deleted file mode 100644 index 0e0fbaf..0000000 --- a/docs/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/docs/source/lang/cc-attribution.txt b/docs/source/lang/cc-attribution.txt deleted file mode 100644 index 11302b2..0000000 --- a/docs/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/docs/source/lang/cpp/arithmetic.rst b/docs/source/lang/cpp/arithmetic.rst deleted file mode 100644 index cef3954..0000000 --- a/docs/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/docs/source/lang/cpp/array.rst b/docs/source/lang/cpp/array.rst deleted file mode 100644 index 39d4d91..0000000 --- a/docs/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/docs/source/lang/cpp/assignment.rst b/docs/source/lang/cpp/assignment.rst deleted file mode 100644 index 6379298..0000000 --- a/docs/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/docs/source/lang/cpp/bitshift.rst b/docs/source/lang/cpp/bitshift.rst deleted file mode 100644 index 47413f2..0000000 --- a/docs/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/docs/source/lang/cpp/bitwisemath.rst b/docs/source/lang/cpp/bitwisemath.rst deleted file mode 100644 index cfe34f2..0000000 --- a/docs/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/docs/source/lang/cpp/boolean.rst b/docs/source/lang/cpp/boolean.rst deleted file mode 100644 index f09345e..0000000 --- a/docs/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/docs/source/lang/cpp/booleanvariables.rst b/docs/source/lang/cpp/booleanvariables.rst deleted file mode 100644 index e032c74..0000000 --- a/docs/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/docs/source/lang/cpp/break.rst b/docs/source/lang/cpp/break.rst deleted file mode 100644 index f367b99..0000000 --- a/docs/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/docs/source/lang/cpp/built-in-types.rst b/docs/source/lang/cpp/built-in-types.rst deleted file mode 100644 index 28e8cdc..0000000 --- a/docs/source/lang/cpp/built-in-types.rst +++ /dev/null @@ -1,100 +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. - -Other 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. diff --git a/docs/source/lang/cpp/byte.rst b/docs/source/lang/cpp/byte.rst deleted file mode 100644 index 4634594..0000000 --- a/docs/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/docs/source/lang/cpp/bytecast.rst b/docs/source/lang/cpp/bytecast.rst deleted file mode 100644 index 24c3b9e..0000000 --- a/docs/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/docs/source/lang/cpp/cc-attribution.txt b/docs/source/lang/cpp/cc-attribution.txt deleted file mode 100644 index e100140..0000000 --- a/docs/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/docs/source/lang/cpp/char.rst b/docs/source/lang/cpp/char.rst deleted file mode 100644 index 686c0d1..0000000 --- a/docs/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/docs/source/lang/cpp/charcast.rst b/docs/source/lang/cpp/charcast.rst deleted file mode 100644 index 640ad85..0000000 --- a/docs/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/docs/source/lang/cpp/comments.rst b/docs/source/lang/cpp/comments.rst deleted file mode 100644 index 1428dc3..0000000 --- a/docs/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/docs/source/lang/cpp/comparison.rst b/docs/source/lang/cpp/comparison.rst deleted file mode 100644 index 9cd0a9f..0000000 --- a/docs/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/docs/source/lang/cpp/compoundarithmetic.rst b/docs/source/lang/cpp/compoundarithmetic.rst deleted file mode 100644 index d70a43c..0000000 --- a/docs/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/docs/source/lang/cpp/compoundbitwise.rst b/docs/source/lang/cpp/compoundbitwise.rst deleted file mode 100644 index 4efe5df..0000000 --- a/docs/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/docs/source/lang/cpp/const.rst b/docs/source/lang/cpp/const.rst deleted file mode 100644 index ad0c580..0000000 --- a/docs/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/docs/source/lang/cpp/continue.rst b/docs/source/lang/cpp/continue.rst deleted file mode 100644 index 2a694f6..0000000 --- a/docs/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/docs/source/lang/cpp/curly-braces.rst b/docs/source/lang/cpp/curly-braces.rst deleted file mode 100644 index df2fe2a..0000000 --- a/docs/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/docs/source/lang/cpp/define.rst b/docs/source/lang/cpp/define.rst deleted file mode 100644 index b22085f..0000000 --- a/docs/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/docs/source/lang/cpp/double.rst b/docs/source/lang/cpp/double.rst deleted file mode 100644 index 59422eb..0000000 --- a/docs/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/docs/source/lang/cpp/doublecast.rst b/docs/source/lang/cpp/doublecast.rst deleted file mode 100644 index d3f32ce..0000000 --- a/docs/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/docs/source/lang/cpp/dowhile.rst b/docs/source/lang/cpp/dowhile.rst deleted file mode 100644 index d229122..0000000 --- a/docs/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/docs/source/lang/cpp/enum.rst b/docs/source/lang/cpp/enum.rst deleted file mode 100644 index b6409eb..0000000 --- a/docs/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/docs/source/lang/cpp/float.rst b/docs/source/lang/cpp/float.rst deleted file mode 100644 index 5195fac..0000000 --- a/docs/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/docs/source/lang/cpp/floatcast.rst b/docs/source/lang/cpp/floatcast.rst deleted file mode 100644 index af92543..0000000 --- a/docs/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/docs/source/lang/cpp/for.rst b/docs/source/lang/cpp/for.rst deleted file mode 100644 index 78ea562..0000000 --- a/docs/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/docs/source/lang/cpp/goto.rst b/docs/source/lang/cpp/goto.rst deleted file mode 100644 index 2c0b3b0..0000000 --- a/docs/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/docs/source/lang/cpp/if.rst b/docs/source/lang/cpp/if.rst deleted file mode 100644 index f248b05..0000000 --- a/docs/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/docs/source/lang/cpp/include.rst b/docs/source/lang/cpp/include.rst deleted file mode 100644 index 163509d..0000000 --- a/docs/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/docs/source/lang/cpp/increment.rst b/docs/source/lang/cpp/increment.rst deleted file mode 100644 index c423d1a..0000000 --- a/docs/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/docs/source/lang/cpp/int.rst b/docs/source/lang/cpp/int.rst deleted file mode 100644 index fa63946..0000000 --- a/docs/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/docs/source/lang/cpp/intcast.rst b/docs/source/lang/cpp/intcast.rst deleted file mode 100644 index da838c7..0000000 --- a/docs/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/docs/source/lang/cpp/keywords.rst b/docs/source/lang/cpp/keywords.rst deleted file mode 100644 index f21cd0d..0000000 --- a/docs/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/docs/source/lang/cpp/longcast.rst b/docs/source/lang/cpp/longcast.rst deleted file mode 100644 index 493ad67..0000000 --- a/docs/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/docs/source/lang/cpp/longlong.rst b/docs/source/lang/cpp/longlong.rst deleted file mode 100644 index d942cb4..0000000 --- a/docs/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/docs/source/lang/cpp/modulo.rst b/docs/source/lang/cpp/modulo.rst deleted file mode 100644 index 013d07e..0000000 --- a/docs/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/docs/source/lang/cpp/pointer.rst b/docs/source/lang/cpp/pointer.rst deleted file mode 100644 index ff4ec32..0000000 --- a/docs/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/docs/source/lang/cpp/return.rst b/docs/source/lang/cpp/return.rst deleted file mode 100644 index d9aecbe..0000000 --- a/docs/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/docs/source/lang/cpp/scope.rst b/docs/source/lang/cpp/scope.rst deleted file mode 100644 index a270428..0000000 --- a/docs/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/docs/source/lang/cpp/semicolon.rst b/docs/source/lang/cpp/semicolon.rst deleted file mode 100644 index 05e6218..0000000 --- a/docs/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/docs/source/lang/cpp/sizeof.rst b/docs/source/lang/cpp/sizeof.rst deleted file mode 100644 index ec2dea6..0000000 --- a/docs/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/docs/source/lang/cpp/sqrt.rst b/docs/source/lang/cpp/sqrt.rst deleted file mode 100644 index fbabf82..0000000 --- a/docs/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/docs/source/lang/cpp/static.rst b/docs/source/lang/cpp/static.rst deleted file mode 100644 index 8c52ba0..0000000 --- a/docs/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/docs/source/lang/cpp/string.rst b/docs/source/lang/cpp/string.rst deleted file mode 100644 index 3497484..0000000 --- a/docs/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/docs/source/lang/cpp/switchcase.rst b/docs/source/lang/cpp/switchcase.rst deleted file mode 100644 index e31ccf3..0000000 --- a/docs/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/docs/source/lang/cpp/unsignedchar.rst b/docs/source/lang/cpp/unsignedchar.rst deleted file mode 100644 index 45fedeb..0000000 --- a/docs/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/docs/source/lang/cpp/unsignedint.rst b/docs/source/lang/cpp/unsignedint.rst deleted file mode 100644 index f8ea473..0000000 --- a/docs/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/docs/source/lang/cpp/unsignedlonglong.rst b/docs/source/lang/cpp/unsignedlonglong.rst deleted file mode 100644 index a1143f0..0000000 --- a/docs/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/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst deleted file mode 100644 index 9ffdd1d..0000000 --- a/docs/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/docs/source/lang/cpp/void.rst b/docs/source/lang/cpp/void.rst deleted file mode 100644 index 7af0acd..0000000 --- a/docs/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/docs/source/lang/cpp/while.rst b/docs/source/lang/cpp/while.rst deleted file mode 100644 index e66e0aa..0000000 --- a/docs/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/docs/source/lang/unimplemented/notone.rst b/docs/source/lang/unimplemented/notone.rst deleted file mode 100644 index 8af878b..0000000 --- a/docs/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/docs/source/lang/unimplemented/pulsein.rst b/docs/source/lang/unimplemented/pulsein.rst deleted file mode 100644 index 2b52428..0000000 --- a/docs/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/docs/source/lang/unimplemented/stringclass.rst b/docs/source/lang/unimplemented/stringclass.rst deleted file mode 100644 index b893e83..0000000 --- a/docs/source/lang/unimplemented/stringclass.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _lang-stringclass: - -String Class -============ - -.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/unimplemented/stringobject.rst b/docs/source/lang/unimplemented/stringobject.rst deleted file mode 100644 index e47ed7e..0000000 --- a/docs/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/docs/source/lang/unimplemented/tone.rst b/docs/source/lang/unimplemented/tone.rst deleted file mode 100644 index 13d581e..0000000 --- a/docs/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/docs/source/language-index.rst b/docs/source/language-index.rst deleted file mode 100644 index 6c20605..0000000 --- a/docs/source/language-index.rst +++ /dev/null @@ -1,54 +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): 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 pointers to low-level details, see the - :ref:`Language Recommended Reading - <language-recommended-reading>` and :ref:`libmaple` pages. - -.. _index-language-index-cpp: -.. _index-language-index-api: - -+----------------------------------+------------------------------------+ -| Maple API | C++ for Maple | -| | | -+==================================+====================================+ -| | | -| .. toctree:: | .. toctree:: | -| :maxdepth: 1 | :maxdepth: 1 | -| :glob: | :glob: | -| | | -| lang/api/* | lang/cpp/* | -| | | -+----------------------------------+------------------------------------+ - -.. Unimplemented or not part of current release: - -.. toctree:: - :hidden: - - lang/unimplemented/tone.rst - lang/unimplemented/notone.rst - lang/unimplemented/pulsein.rst - lang/unimplemented/stringclass.rst - lang/unimplemented/stringobject.rst diff --git a/docs/source/language.rst b/docs/source/language.rst deleted file mode 100644 index be085f2..0000000 --- a/docs/source/language.rst +++ /dev/null @@ -1,449 +0,0 @@ -.. highlight:: c++ - -.. _language: - -========================== - Maple 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. - -.. TODO [0.2.0?] Wiring tutorial - -C or C++ programmers may wish to skip to the -:ref:`arduino_c_for_c_hackers`. - -.. contents:: Contents - :local: - -.. admonition:: **Looking for Something Else?** - - - See the :ref:`libraries` for extra built-in libraries. - - - If you're looking for something from the C standard library (like - ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler - <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 pointers to low-level details, see - :ref:`libmaple` and this page's :ref:`Recommended Reading - <language-recommended-reading>`. - -.. _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 registers, you are encouraged to move on to the -:ref:`libmaple` documentation. - -A *sketch* is the IDE's notion of a project; it consists of one or -more files written in the Wiring language, which is mostly the same as -C++. The major difference between the two is that in Wiring, it's not -necessary to declare global functions before they are used. That is, -the following is valid Wiring, and ``f()`` returns ``5``:: - - int f() { - return g(); - } - - int g() { - return 5; - } - -All of the files in a sketch share the same (global) namespace. That -is, the behavior is as if all of a sketch's files were part of the -same translation unit, so they don't have to include one another in -order to access each other's definitions. The only other major -difference between Wiring and C++ is that Wiring doesn't support -dynamically allocated memory -- that is, ``new`` and ``delete`` won't -work. As of |today|, Maple only has 20 KB RAM, anyway, so it's -doubtful that static allocation is not what you want. - -The Wiring language also does not require you to define your own -``main`` method (in fact, we currently forbid you from doing so). -Instead, you are required to define two functions, ``setup`` and -``loop``, with type signatures :: - - void setup(void); - void loop(void); - -Once a sketch is uploaded to a Maple and begins to run, ``setup()`` is -called once, and then ``loop()`` is called repeatedly. The IDE -compilation process proceeds via a source-to-source translation from -the files in a sketch to C++. - -This translation process first concatenates the sketch files, then -parses the result to produce a list of all functions defined in the -global scope. (We borrow this stage from the Arduino IDE, which in -turn borrows it from Wiring. It uses regular expressions to parse -C++, which is, of course, `Bad and Wrong -<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 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:`libmaple Documentation <libmaple>` -* Your board's :ref:`Board Hardware Documentation <index-boards>` page -* ST Documentation: - * Reference Manual `RM0008 - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - (PDF). This is the most important reference work on the STM32 - line, and covers the low-level hardware capabilities and - interfaces in great detail. - * `Programming Manual - <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ - (PDF). This is an assembly language and register reference for - the STM32 line. -* ARM Documentation: - * `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 much of the the Cortex M3 - Architecture, including instruction timings. -* `newlib Documentation <http://sourceware.org/newlib/>`_ diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst deleted file mode 100644 index d9f30be..0000000 --- a/docs/source/libmaple.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. highlight:: sh - -.. _libmaple: - -``libmaple`` -============ - -LeafLabs' libmaple (`source code on GitHub -<https://github.com/leaflabs/libmaple>`_) is the library we have -developed for the `STM32 <http://www.st.com/stonline>`_ line of ARM -Cortex M3 microcontrollers. Its high-level interfaces are -:ref:`largely compatible <arduino-compatibility>` with the AVR -libraries written for the `Arduino <http://arduino.cc>`_ and `Wiring -<http://wiring.org.co/>`_ development boards. - -libmaple is split into two pieces: a lower level layer written in pure -C, which we call *libmaple proper* (in the `libmaple/ -<https://github.com/leaflabs/libmaple/tree/master/libmaple>`_ -directory of the source repository), and the Wiring-style C++ API -written on top of it, called *Wirish* (in `wirish/ -<https://github.com/leaflabs/libmaple/tree/master/wirish>`_). - -libmaple is bundled with the :ref:`Maple IDE <ide>`. However, we -develop it separately, and :ref:`release it standalone -<unix-toolchain>` for advanced users who might chafe at the "sketch" -programming model of the IDE. - -As always, :ref:`patches are welcome <libmaple-contributing>`. - -**Contents:** - -.. toctree:: - :maxdepth: 1 - - libmaple/overview - libmaple/apis - libmaple/contributing - libmaple/coding-standard - diff --git a/docs/source/libmaple/api/adc.rst b/docs/source/libmaple/api/adc.rst deleted file mode 100644 index 8817055..0000000 --- a/docs/source/libmaple/api/adc.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-adc: - -``adc.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: adc.h diff --git a/docs/source/libmaple/api/bitband.rst b/docs/source/libmaple/api/bitband.rst deleted file mode 100644 index fd57944..0000000 --- a/docs/source/libmaple/api/bitband.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-bitband: - -``bitband.h`` -============= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: bitband.h diff --git a/docs/source/libmaple/api/bkp.rst b/docs/source/libmaple/api/bkp.rst deleted file mode 100644 index 9a697c7..0000000 --- a/docs/source/libmaple/api/bkp.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-bkp: - -``bkp.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: bkp.h diff --git a/docs/source/libmaple/api/dac.rst b/docs/source/libmaple/api/dac.rst deleted file mode 100644 index 038753b..0000000 --- a/docs/source/libmaple/api/dac.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-dac: - -``dac.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: dac.h diff --git a/docs/source/libmaple/api/delay.rst b/docs/source/libmaple/api/delay.rst deleted file mode 100644 index a0d013a..0000000 --- a/docs/source/libmaple/api/delay.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-delay: - -``delay.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: delay.h diff --git a/docs/source/libmaple/api/dma.rst b/docs/source/libmaple/api/dma.rst deleted file mode 100644 index 1512d0c..0000000 --- a/docs/source/libmaple/api/dma.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-dma: - -``dma.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: dma.h diff --git a/docs/source/libmaple/api/exti.rst b/docs/source/libmaple/api/exti.rst deleted file mode 100644 index 2909aa7..0000000 --- a/docs/source/libmaple/api/exti.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-exti: - -``exti.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: exti.h diff --git a/docs/source/libmaple/api/flash.rst b/docs/source/libmaple/api/flash.rst deleted file mode 100644 index 6f2f9d3..0000000 --- a/docs/source/libmaple/api/flash.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-flash: - -``flash.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: flash.h diff --git a/docs/source/libmaple/api/fsmc.rst b/docs/source/libmaple/api/fsmc.rst deleted file mode 100644 index cecfc99..0000000 --- a/docs/source/libmaple/api/fsmc.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-fsmc: - -``fsmc.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: fsmc.h diff --git a/docs/source/libmaple/api/gpio.rst b/docs/source/libmaple/api/gpio.rst deleted file mode 100644 index 2cfec23..0000000 --- a/docs/source/libmaple/api/gpio.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-gpio: - -``gpio.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: gpio.h diff --git a/docs/source/libmaple/api/i2c.rst b/docs/source/libmaple/api/i2c.rst deleted file mode 100644 index 14dd304..0000000 --- a/docs/source/libmaple/api/i2c.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-i2c: - -``i2c.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: i2c.h diff --git a/docs/source/libmaple/api/iwdg.rst b/docs/source/libmaple/api/iwdg.rst deleted file mode 100644 index 3911ece..0000000 --- a/docs/source/libmaple/api/iwdg.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-iwdg: - -``iwdg.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: iwdg.h diff --git a/docs/source/libmaple/api/libmaple.rst b/docs/source/libmaple/api/libmaple.rst deleted file mode 100644 index d4f28f0..0000000 --- a/docs/source/libmaple/api/libmaple.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-libmaple: - -``libmaple.h`` -============== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: libmaple.h diff --git a/docs/source/libmaple/api/libmaple_types.rst b/docs/source/libmaple/api/libmaple_types.rst deleted file mode 100644 index bbea2c1..0000000 --- a/docs/source/libmaple/api/libmaple_types.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-libmaple_types: - -``libmaple_types.h`` -==================== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: libmaple_types.h diff --git a/docs/source/libmaple/api/nvic.rst b/docs/source/libmaple/api/nvic.rst deleted file mode 100644 index b94dc31..0000000 --- a/docs/source/libmaple/api/nvic.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-nvic: - -``nvic.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: nvic.h diff --git a/docs/source/libmaple/api/pwr.rst b/docs/source/libmaple/api/pwr.rst deleted file mode 100644 index 82e4864..0000000 --- a/docs/source/libmaple/api/pwr.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-pwr: - -``pwr.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: pwr.h diff --git a/docs/source/libmaple/api/rcc.rst b/docs/source/libmaple/api/rcc.rst deleted file mode 100644 index 81dc604..0000000 --- a/docs/source/libmaple/api/rcc.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-rcc: - -``rcc.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: rcc.h diff --git a/docs/source/libmaple/api/ring_buffer.rst b/docs/source/libmaple/api/ring_buffer.rst deleted file mode 100644 index a014fa4..0000000 --- a/docs/source/libmaple/api/ring_buffer.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-ring_buffer: - -``ring_buffer.h`` -================= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: ring_buffer.h diff --git a/docs/source/libmaple/api/scb.rst b/docs/source/libmaple/api/scb.rst deleted file mode 100644 index 78cc7eb..0000000 --- a/docs/source/libmaple/api/scb.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-scb: - -``scb.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: scb.h diff --git a/docs/source/libmaple/api/spi.rst b/docs/source/libmaple/api/spi.rst deleted file mode 100644 index b0c7e86..0000000 --- a/docs/source/libmaple/api/spi.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-spi: - -``spi.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: spi.h diff --git a/docs/source/libmaple/api/stm32.rst b/docs/source/libmaple/api/stm32.rst deleted file mode 100644 index 2784540..0000000 --- a/docs/source/libmaple/api/stm32.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-stm32: - -``stm32.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: stm32.h diff --git a/docs/source/libmaple/api/systick.rst b/docs/source/libmaple/api/systick.rst deleted file mode 100644 index fa959f2..0000000 --- a/docs/source/libmaple/api/systick.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. highlight:: c - -.. FIXME [0.1.0] move these to the right places once Breathe is fast -.. enough to use for libmaple proper - -.. _libmaple-systick_disable: - -.. _libmaple-systick_resume: - -.. _libmaple-systick: - -``systick.h`` -============= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: systick.h diff --git a/docs/source/libmaple/api/timer.rst b/docs/source/libmaple/api/timer.rst deleted file mode 100644 index 3acbf4f..0000000 --- a/docs/source/libmaple/api/timer.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-timer: - -``timer.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: timer.h diff --git a/docs/source/libmaple/api/usart.rst b/docs/source/libmaple/api/usart.rst deleted file mode 100644 index 26e6b9c..0000000 --- a/docs/source/libmaple/api/usart.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-usart: - -``usart.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: usart.h diff --git a/docs/source/libmaple/api/util.rst b/docs/source/libmaple/api/util.rst deleted file mode 100644 index 50ffe76..0000000 --- a/docs/source/libmaple/api/util.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-util: - -``util.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: util.h diff --git a/docs/source/libmaple/apis.rst b/docs/source/libmaple/apis.rst deleted file mode 100644 index f493406..0000000 --- a/docs/source/libmaple/apis.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _libmaple-apis: - -APIs -==== - -This is the master index for libmaple proper's APIs. - -**Contents** - -.. toctree:: - :maxdepth: 1 - :glob: - - api/* diff --git a/docs/source/libmaple/coding-standard.rst b/docs/source/libmaple/coding-standard.rst deleted file mode 100644 index 23d20f8..0000000 --- a/docs/source/libmaple/coding-standard.rst +++ /dev/null @@ -1,412 +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. - -Vim customizations to do the same thing would be nice! - -.. contents:: Contents - :local: - -License -------- - -.. highlight:: scheme - -Put an MIT license at the beginning of the file (look at any of our -source files for an example). Copyright should go either to you or to -LeafLabs, LLC. - -Emacs: if you don't like seeing the license, you should use elide-head -(which will hide it for you). You can use the following:: - - (require 'elide-head) - (setq programming-mode-hooks '(c-mode-hook c++-mode-hook)) - (add-to-list 'elide-head-headers-to-hide - '("The MIT License" . "DEALINGS IN\n [*] THE SOFTWARE")) - (add-to-list 'elide-head-headers-to-hide - '("The MIT License" . "DEALINGS IN THE\n...SOFTWARE")) - (dolist (hook programming-mode-hooks) - (add-hook hook (lambda () (elide-head)))) - -Whitespace ----------- - -- 4 space indents (set in ``.dir-locals.el``). - -- Unix newlines. Some exceptions are currently grandfathered in; these - will go away in time. - -- No tab characters (set in ``.dir-locals.el``). - -- No trailing whitespace. For help getting this (and no tab - characters) done automatically in Emacs, you can use - `code-fascism.el <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 generally - means that if there's ReST documentation for it under libmaple's - ``docs/source/``, it needs Doxygen comments, and that ReST should - use Breathe to pull that Doxygen comment out. (For more information - on this, see libmaple file ``docs/README``). - - There are some exceptions to this rule since Breathe isn't totally - mature yet and Sphinx's C++ domain is still in flux. In these - cases, document the code "manually" in ReST. - - This should be avoided if at all possible, since it creates a - maintenance burden of documenting things in two places at once, and - makes it easier for documentation to go stale. - - If you do have to document something manually, put a comment in the - source file informing future maintainers about it, so they'll pay - extra attention when making changes. - -- When adding peripheral support, it would be nice if you put - longer-form comments into the libmaple ``notes/`` directory, with a - comment in the corresponding .h file referring to it. See the - :ref:`dac.h <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. - -- **For libmaple proper**, the convention is to document any - user-facing function at the point where it is defined. In - particular, this means you should document an externally-linked - function defined in a .c file in that .c file, not in the header - file where it is declared to the user. - - **For Wirish**, the convention is to put the documentation in the - header file where the function is declared. - -General Formatting ------------------- - -.. highlight:: scheme - -- Keep it 80-column clean. - - Emacs users: this means that the largest column number is 79. You - should turn on column number mode to help you out:: - - (column-number-mode 1) - - You can get more help from `lineker-mode - <http://www.helsinki.fi/~sjpaavol/programs/lineker.el>`_. Just put - lineker.el somewhere in your load-path, and:: - - (require 'lineker) - (dolist (hook '(c-mode-hook c++-mode-hook)) - (add-hook hook (lambda () (lineker-mode 1)))) - -.. highlight:: cpp - -Language Features ------------------ - -In libmaple proper, aim for C99 compatibility. Some GCC extensions -are OK, but `don't get crazy <http://www.youtube.com/watch?v=jZkdcYlOn5M>`_. - -Explicitly approved GCC extensions: - - * `asm volatile <http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_ - - * `Nested functions <http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html>`_ - -In Wirish, generally be very conservative when using C++ features that -aren't part of C. We are forced to use C++ for Arduino compatibility -(and the general Arduino style of conflating objects and libraries), -but it's an angry beast, and we don't want to provoke it. **The -mantra is "C with classes"**. - -Explicitly approved C++ features: - - * Initializers that aren't constant; e.g. the ``gpio_dev*`` values - in a ``PIN_MAP``. - - * Default arguments: e.g., the timeout argument in - :ref:`lang-waitforbuttonpress`. - -Explicitly forbidden C++ features: - - * Templates - -Conditionally allowed C++ features: - - * Operator overloading: Never allowed when it's just for style. - Probably fine when you're implementing a class that models a - mathematical structure, and you'd like to implement - e.g. ``operator+()``. - diff --git a/docs/source/libmaple/contributing.rst b/docs/source/libmaple/contributing.rst deleted file mode 100644 index bb4d550..0000000 --- a/docs/source/libmaple/contributing.rst +++ /dev/null @@ -1,113 +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). - -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>`_. - -That said, we'd really prefer a pull request. If you'd like to learn -more about Git, we recommend the following resources: - -* `The Git Community Book <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. - -* `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. diff --git a/docs/source/libmaple/overview.rst b/docs/source/libmaple/overview.rst deleted file mode 100644 index d18bfe2..0000000 --- a/docs/source/libmaple/overview.rst +++ /dev/null @@ -1,336 +0,0 @@ -.. highlight:: c - -.. _libmaple-overview: - -Overview -======== - -This page is a general overview of libmaple proper. It provides a -general perspective of the library's goals and design. Examples are -given from libmaple's sources. - -.. contents:: Contents - :local: - -Design Goals ------------- - -The central goal of the libmaple project is to provide a pleasant, -consistent set of interfaces for dealing with the various peripherals -on the STM32 line. - -Let's start with the basics. If you're interested in low-level details -on the STM32, then you're going to spend a lot of quality time wading -through `ST RM0008 -<http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_. -That document is the single most important tool in your toolbox. It -is the authoritative documentation for the capabilities and register -interfaces of the STM32 line. - -Perhaps you haven't read it in detail, but maybe you've at least -thumbed through a few of the sections, trying to gain some -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. - -For the most part, Wirish does everything it can to hide this truth -from you. That's because when you really just want to get your robot -to fly, your LEDs to blink, or your `FM synthesizer -<https://github.com/Ixox/preen>`_ to, well, `synthesize -<http://xhosxe.free.fr/IxoxFMSynth.mp3>`_, you probably couldn't care -less about messing with registers. - -That's fine! In fact, it's our explicit goal for Wirish to be good -enough that most people never need to know libmaple proper even -exists. We want to make programming our boards as easy as possible, -after all. But the day may come when you want to add a library for an -as-yet unsupported peripheral, or you want to do something we didn't -anticipate, or you'd like to squeeze a little more speed out of a -critical section in your program. Or maybe you're just curious! - -If anything in the above paragraph describes you, then you'll find -that you need a way to translate your knowledge of RM0008 into -software. We imagine (if you're anything like us) you want to spend -the least amount of time you possibly can doing that -translation. Ideally, once you've finished your design, you want some -way to start reading and writing code right away, without having to -bushwhack your way through a thicket of clunky APIs. - -The central abstractions we've chosen to accomplish the above goals -are *register maps* and *devices*. Register maps are just structs -which encapsulate the layout of the IO-mapped memory regions -corresponding to a peripheral's registers. Devices encapsulate a -peripheral's register map as well as any other necessary information -needed to operate on it. Peripheral support routines generally -operate on devices rather than register maps. - -Devices -------- - -At the highest level, you'll be dealing with *devices*, where a -"device" is a general term for any particular piece of hardware you -might encounter. So, for example, an analog to digital converter is a -device. So is a USART. So is a GPIO port. In this section, we'll -consider some hypothetical "xxx" device. - -The first thing you need to know is that the header file for dealing -with xxx devices is, naturally enough, called ``xxx.h``. So if you -want to interface with the :ref:`ADCs <adc>`, just ``#include -"adc.h"``. - -Inside of ``xxx.h``, there will be a declaration for a ``struct -xxx_dev`` type. This type encapsulates all of the information we keep -track of for that xxx. So, for example, in ``adc.h``, there's a -``struct adc_dev``:: - - /** ADC device type. */ - typedef struct adc_dev { - adc_reg_map *regs; /**< Register map */ - rcc_clk_id clk_id; /**< RCC clock information */ - } adc_dev; - -The ADCs aren't particularly complicated. All we keep track of for an -ADC device is a pointer to its register map (which keeps track of all -of its registers' bits; see :ref:`below <libmaple-overview-regmaps>` -for more details), and an identifying piece of information which tells -the RCC (reset and clock control) interface how to turn the ADC on and -reset its registers to their default values. - -The timers on the STM32 line are more involved than the ADCs, so a -``timer_dev`` has to keep track of a bit more information:: - - /** Timer device type */ - typedef struct timer_dev { - timer_reg_map regs; /**< Register map */ - rcc_clk_id clk_id; /**< RCC clock information */ - timer_type type; /**< Timer's type */ - voidFuncPtr handlers[]; /**< User IRQ handlers */ - } timer_dev; - -However, as you can see, both ADC and timer devices are named -according to a single scheme, and store similar information. - -``xxx.h`` will also declare pointers to the actual devices you need to -deal with, called ``XXX1``, ``XXX2``, etc. (or just ``XXX``, if -there's only one) [#fgpio]_. For instance, on the Maple's -microcontroller (the STM32F103RBT6), there are two ADCs. -Consequently, in ``adc.h``, there are declarations for dealing with -ADC devices one and two:: - - extern const adc_dev *ADC1; - extern const adc_dev *ADC2; - -In general, each device needs to be initialized before it can be used. -libmaple provides this initialization routine for each peripheral -``xxx``; its name is ``xxx_init()``. These initialization routines -turn on the clock to a device, and restore its register values to -their default settings. Here are a few examples:: - - /* From dma.h */ - void dma_init(dma_dev *dev); - - /* From gpio.h */ - void gpio_init(gpio_dev *dev); - void gpio_init_all(void); - -Note that, sometimes, there will be an additional initialization -routine for all available peripherals of a certain kind. - -Many peripherals also need additional configuration before they can be -used. These functions are usually called something along the lines of -``xxx_enable()``, and often take additional arguments which specify a -particular configuration for the peripheral. Some examples:: - - /* From usart.h */ - void usart_enable(usart_dev *dev); - - /* From i2c.h */ - void i2c_master_enable(i2c_dev *dev, uint32 flags); - -After you've initialized, and potentially enabled, your peripheral, it -is now time to begin using it. The file ``xxx.h`` contains other -convenience functions for dealing with xxx devices. For instance, -here are a few from ``adc.h``:: - - void adc_set_sample_rate(const adc_dev *dev, adc_smp_rate smp_rate); - uint32 adc_read(const adc_dev *dev, uint8 channel); - -We aim to enable libmaple's users to interact with peripherals through -devices as much as possible, rather than having to break the -abstraction and consider individual registers. However, there will -always be a need for low-level access. To allow for that, libmaple -provides *register maps* as a consistent set of names and abstractions -for dealing with registers and their bits. - -.. _libmaple-overview-regmaps: - -Register Maps -------------- - -A *register map* is just a C struct which names and provides access to -a peripheral's registers. These registers are usually mapped to -contiguous regions of memory (though at times unusable or reserved -regions exist between a peripheral's registers). Here's an example -register map, from ``dac.h`` (``__io`` is just libmaple's way of -saying ``volatile`` when referring to register values):: - - /** DAC register map. */ - typedef struct dac_reg_map { - __io uint32 CR; /**< Control register */ - __io uint32 SWTRIGR; /**< Software trigger register */ - __io uint32 DHR12R1; /**< Channel 1 12-bit right-aligned data - holding register */ - __io uint32 DHR12L1; /**< Channel 1 12-bit left-aligned data - holding register */ - __io uint32 DHR8R1; /**< Channel 1 8-bit left-aligned data - holding register */ - __io uint32 DHR12R2; /**< Channel 2 12-bit right-aligned data - holding register */ - __io uint32 DHR12L2; /**< Channel 2 12-bit left-aligned data - holding register */ - __io uint32 DHR8R2; /**< Channel 2 8-bit left-aligned data - holding register */ - __io uint32 DHR12RD; /**< Dual DAC 12-bit right-aligned data - holding register */ - __io uint32 DHR12LD; /**< Dual DAC 12-bit left-aligned data - holding register */ - __io uint32 DHR8RD; /**< Dual DAC 8-bit left-aligned data holding - register */ - __io uint32 DOR1; /**< Channel 1 data output register */ - __io uint32 DOR2; /**< Channel 2 data output register */ - } dac_reg_map; - - -There are two things to notice here. First, if RM0008 names a -register ``DAC_FOO``, then ``dac_reg_map`` has a field named ``FOO``. -So, the Channel 1 12-bit right-aligned data register (RM0008: -DAC_DHR12R1) is the ``DHR12R1`` field in a ``dac_reg_map``. Second, -if RM0008 describes a register as "Foo bar register", the -documentation for the corresponding field has the same description. -This consistency makes it easy to search for a particular register, -and, if you see one used in a source file, to feel sure about what's -going on just based on its name. - -So let's say you've included ``xxx.h``, and you want to mess with some -particular register. What's the name of the ``xxx_reg_map`` variable -you want? That depends on if there's more than one xxx or not. If -there's only one xxx, then libmaple guarantees there will be a -``#define`` that looks like like this:: - - #define XXX_BASE ((struct xxx_reg_map*)0xDEADBEEF) - -That is, you're guaranteed there will be a pointer to the (only) -``xxx_reg_map`` you want, and it will be called -``XXX_BASE``. (``0xDEADBEEF`` is the register map's *base address*, or -the fixed location in memory where the register map begins). Here's a -concrete example from ``dac.h``:: - - #define DAC_BASE ((struct dac_reg_map*)0x40007400) - -How can you use these? This is perhaps best explained by example. - -* In order to write 2048 to the channel 1 12-bit left-aligned data - holding register (RM0008: DAC_DHR12L1), you could write:: - - DAC_BASE->DHR12L1 = 2048; - -* In order to read the DAC control register, you could write:: - - uint32 cr = DAC_BASE->CR; - -The microcontroller takes care of converting reads and writes from a -register's IO-mapped memory regions into reads and writes to the -corresponding hardware registers. - -That covers the case where there's a single xxx peripheral. If -there's more than one (say, if there are *n*), then ``xxx.h`` provides -the following:: - - #define XXX1_BASE ((struct xxx_reg_map*)0xDEADBEEF) - #define XXX2_BASE ((struct xxx_reg_map*)0xF00DF00D) - ... - #define XXXn_BASE ((struct xxx_reg_map*)0x13AF1AB5) - -Here are some examples from ``adc.h``:: - - #define ADC1_BASE ((struct adc_reg_map*)0x40012400) - #define ADC2_BASE ((struct adc_reg_map*)0x40012800) - -In order to read from the ADC1's regular data register (where the -results of ADC conversion are stored), you might write:: - - uint32 converted_result = ADC1_BASE->DR; - -Register Bit Definitions ------------------------- - -In ``xxx.h``, there will also be a variety of #defines for dealing -with interesting bits in the xxx registers, called *register bit -definitions*. These are named according to the scheme -``XXX_REG_FIELD``, where "``REG``" refers to the register, and -"``FIELD``" refers to the bit or bits in ``REG`` that are special. - -.. TODO image of the bit layout of a DMA_CCR register - -Again, this is probably best explained by example. Each Direct Memory -Access (DMA) controller's register map has a certain number of channel -configuration registers (RM0008: DMA_CCRx). In each of these channel -configuration registers, bit 14 is called the ``MEM2MEM`` bit, and -bits 13 and 12 are the priority level (``PL``) bits. Here are the -register bit definitions for those fields:: - - /* From dma.h */ - - #define DMA_CCR_MEM2MEM_BIT 14 - #define DMA_CCR_MEM2MEM BIT(DMA_CCR_MEM2MEM_BIT) - #define DMA_CCR_PL (0x3 << 12) - #define DMA_CCR_PL_LOW (0x0 << 12) - #define DMA_CCR_PL_MEDIUM (0x1 << 12) - #define DMA_CCR_PL_HIGH (0x2 << 12) - #define DMA_CCR_PL_VERY_HIGH (0x3 << 12) - -Thus, to check if the ``MEM2MEM`` bit is set in DMA controller 1's -channel configuration register 2 (RM0008: DMA_CCR2), you can write:: - - if (DMA1_BASE->CCR2 & DMA_CCR_MEM2MEM) { - /* MEM2MEM is set */ - } - -Certain register values occupy multiple bits. For example, the -priority level (PL) of a DMA channel is determined by bits 13 and 12 -of the corresponding channel configuration register. As shown above, -libmaple provides several register bit definitions for masking out the -individual PL bits and determining their meaning. For example, to -check the priority level of a DMA transfer, you can write:: - - switch (DMA1_BASE->CCR2 & DMA_CCR_PL) { - case DMA_CCR_PL_LOW: - /* handle low priority case */ - case DMA_CCR_PL_MEDIUM: - /* handle medium priority case */ - case DMA_CCR_PL_HIGH: - /* handle high priority case */ - case DMA_CCR_PL_VERY_HIGH: - /* handle very high priority case */ - } - -Of course, before doing that, you should check to make sure there's -not already a device-level function for performing the same task! - -What Next? ----------- - -After you've read this page, you can proceed to the :ref:`libmaple API -listing <libmaple-apis>`. From there, you can read documentation and -follow links to the current source code for those files on `libmaple's -GitHub page <https://github.com/leaflabs/libmaple>`_. - -.. rubric:: Footnotes - -.. [#fgpio] For consistency with RM0008, GPIO ports are given letters - instead of numbers (``GPIOA`` and ``GPIOB`` instead of - ``GPIO1`` and ``GPIO2``, etc.). diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst deleted file mode 100644 index 44a72f7..0000000 --- a/docs/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.1.0] Update with hard Wire implementation info - -We currently provide a soft (bit-banged) implementation of the -:ref:`Wire <libs-wire>` I2C library. A hardware version is planned -for Maple IDE release 0.1.0. diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst deleted file mode 100644 index 80288c6..0000000 --- a/docs/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/docs/source/libs/wire.rst b/docs/source/libs/wire.rst deleted file mode 100644 index 2c5bed9..0000000 --- a/docs/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/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst deleted file mode 100644 index 67171dd..0000000 --- a/docs/source/maple-ide-install.rst +++ /dev/null @@ -1,171 +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 [0.0.12] 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 32-bit Windows XP -.. * - `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 -^^^^^^^ -First, extract all the files in the ZIP file to a suitable location on -your system (like your Desktop folder). Next, you have to install -some drivers. Sorry! - -.. note:: Note that while these instructions work on Windows XP, - changes in Windows 7 mean that you won't be able to install the IDE - without disabling driver signing on your computer. We're working - on resolving this situation. For now, `users on the forum have - reported a workaround - <http://forums.leaflabs.com/topic.php?id=73#post-788>`_. - -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. Sun - Java 1.6 and OpenJDK 1.6 are known to work, and runtimes mostly - compatible with Sun Java 1.5+ should probably get the job done. - - To install Java, try using your distribution's software packaging - tool and search for "JRE" or "java". On Debian-based systems - (including Ubuntu) you can try to install the OpenJDK 1.6 JRE - with:: - - $ sudo aptitude install openjdk-6-jre - -Extract the tarball to an appropriate location (like your home -directory or desktop). - -Make sure you have a Java runtime (JRE) installed; if you can run -:command:`java` from the shell, you should be fine. - -Next, run the script :file:`install-udev-rules.sh` in the extracted -IDE directory. It will ask for root permissions (you will be prompted -with something along the lines of ``[sudo] password for -<username>:``). You now need to restart udev:: - - $ sudo restart udev - -This will grant members of the group ``plugdev`` read/write access to -Maple devices over USB. Make sure that you are in that group by -running ``$ sudo adduser <your username> plugdev`` (which will ensure -access to the Maple, but may report that you are already a member of -that group). (For more information on why this is part of the install -process, see the :ref:`Unix toolchain quickstart <toolchain-udev>`). - -To run the Maple IDE, run :command:`maple-ide` from the shell, or -double-click on it if your window system supports it. - -Feel free to put the IDE directory wherever you want. As long as you -leave its internal structure unchanged, things should be fine. - -.. _maple-ide-install-osx: - -OS X -^^^^ - -Double-click on the :file:`.dmg` file you downloaded to mount the disk -image. From the mounted image, drag and drop the Maple IDE icon into -your computer's Applications folder. - -To run the Maple IDE, double-click the :command:`Maple IDE` -application you dragged into your computer's :file:`Applications` -folder. - diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst deleted file mode 100644 index 976eecf..0000000 --- a/docs/source/maple-quickstart.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. highlight:: sh - -.. _maple-quickstart: - -======================== - Maple Quickstart Guide -======================== - -.. TODO [0.1.0] Update the images; we've changed "to FLASH" -> "to Flash" - -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": - -.. image:: /_static/img/blinky-to-flash.png - :align: center - :alt: Upload to FLASH - -.. note:: - - You have the option between RAM and FLASH programming: FLASH saves - the program into permanent memory so the program will be run every - time the Maple is reset, while RAM simply injects the compiled - program into the processor's memory. - - Programming to RAM is faster to upload and a buggy program can be - wiped away with a simple reset, while FLASH memory is larger and is - the only option for permanently uploading a program. - -.. image:: /_static/img/verify_button.png - :align: left - :alt: Verify button - -Now press the "Verify" button (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! --------------------- - -.. FIXME [Maple Native: add note about power select jumper] - -Now it's time to plug in your Maple. Use a USB Mini-B cable (mini, -not micro). - -On the Maple, make sure that the :ref:`power source jumper -<maple-powering>` is on the USB header first. We ship Maples with the -power source jumper configured that way, so you shouldn't have to do -anything. For reference, it should look like this (don't worry if a -jumper is hanging half off of the CHRG header): - -.. image:: /_static/img/plugged-in-maple.png - :align: center - :alt: Correctly plugged in Maple - -.. note:: - - On OS X, a network interface dialog will pop up every time you plug in - the Maple. - - .. image:: /_static/img/osx-unconfigured-popup.png - :align: center - :alt: Unconfigured modem popup - - If you click "Network Preferences..." and accept the default ("Not - Configured"), the dialog won't pop up and everything will work fine. - That is, from this window, click "Apply": - - .. image:: /_static/img/osx-network-prefs-unconfigured.png - :align: center - :scale: 75% - :alt: Click "Apply" - -The Maple should blink a short pattern on the blue status LED every -time it is plugged in, reset, or reprogrammed, just to let you know -it's there. If it ever starts throbbing in a slow, smooth pattern, -then you've got a problem: see the :ref:`troubleshooting -<troubleshooting>` page for help. - -If all systems are go, select the Maple's serial port in the Tools > -Serial Port menu. The Maple will appear as something like -:file:`COMx`, :file:`/dev/ttyACMx`, or :file:`/dev/tty.usbmodemxxxxx`, -depending on your platform, like so: - -Windows XP: - -.. image:: /_static/img/serial-port-win.png - :align: center - :alt: Board type and serial port for Windows XP - -Linux: - -.. image:: /_static/img/serial-port-ubuntu.png - :align: center - :alt: Board type and serial port for Linux - -OS X: - -.. image:: /_static/img/serial-port-mac.png - :align: center - :alt: Board type and serial port for the OS X - -Then press the "Upload" button to upload your program to the -Maple. - -.. image:: /_static/img/upload-button.png - :align: center - :alt: Click the "Upload" button - -You should see some text and a progress bar flash by in the status -window of the IDE, then some blinky patterns on the Maple, and then a -constant blinking on and off. Congratulations! You've successfully -uploaded your first program to the Maple. - -Next, go ahead and modify the file a little bit. If you change the -``delay(1000);`` lines to a different value, the speed of the blink -will change. The value is a time in milliseconds to pause before -continuing with the program, so by default, the LED will be on for 1 -second, then off for 1 second, etc. Any time you make any changes, go -through the same Verify and Upload process to upload the new version -of your program to your Maple. - -.. 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 -Maple back to the IDE over the USB connection. From the File menu, -select Examples > Stubs > HelloWorld (similarly to when you selected -the Blink program), and make sure the correct board and serial port -targets are selected from the Tools menu. - -Open the Serial Monitor window (on the far right of the toolbar). Then -go back to the code editing window and upload your program (Upload -will recompile your code automatically if there's been any change -since the last Verify). You should get text spit at you over the -serial monitor right after the program is uploaded. Shout back! We -can hear you! - -Go forth exuberantly! ---------------------- - -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! Tag us with #leaflabs on Twitter, -post in the `forum`_, post on `our wiki's Projects page -<http://wiki.leaflabs.com/index.php?title=Projects>`_, track us down -in the real world, whatever. We love projects! diff --git a/docs/source/prolog.rst b/docs/source/prolog.rst deleted file mode 100644 index 8606555..0000000 --- a/docs/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/docs/source/pwm.rst b/docs/source/pwm.rst deleted file mode 100644 index 34ad508..0000000 --- a/docs/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.arcfn.com/2009/07/secrets-of-arduino-pwm.html>`_ at Non-Lexical Vocables -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) diff --git a/docs/source/spi.rst b/docs/source/spi.rst deleted file mode 100644 index dd9f1f5..0000000 --- a/docs/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://www.arduino.cc/playground/Code/Spi>`_ - -* `Hardcore SPI on Arduino <http://klk64.com/arduino-spi/>`_ by kik64 - -* ST Documentation: - - * Reference Manual `RM0008 - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - (PDF), Chapter 25, "Serial Peripheral Interface" - diff --git a/docs/source/systick.rst b/docs/source/systick.rst deleted file mode 100644 index afc8d09..0000000 --- a/docs/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/docs/source/timers.rst b/docs/source/timers.rst deleted file mode 100644 index b6c0886..0000000 --- a/docs/source/timers.rst +++ /dev/null @@ -1,124 +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: - -.. TODO [0.0.12] Native links - -* :ref:`Maple <maple-timer-map>` -* :ref:`Maple RET6 Edition <maple-ret6-timer-map>` -* :ref:`Maple Mini <maple-mini-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_resume() <libmaple-systick_resume>`. However, be aware -that calling ``systick_disable()`` will stop the values coming from -:ref:`lang-micros` and :ref:`lang-millis` from increasing. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst deleted file mode 100644 index da6fb40..0000000 --- a/docs/source/troubleshooting.rst +++ /dev/null @@ -1,237 +0,0 @@ -.. highlight:: sh - -.. _troubleshooting: - -Troubleshooting -=============== - -This page documents common problems and their solutions. - -.. contents:: Contents - :local: - -=================== - Hardware problems -=================== - -The LED is throbbing and my program is stopped! ------------------------------------------------ - -The LED throbs when there has been a failed software :ref:`assertion -<lang-assert>` or some other error. - -There are a few issues with the bootloader which mean you might not be -able to upload your program when this happens. You can still -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. - -.. _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 into perpetual bootloader mode: - -#. Plug your Maple into the USB port. - -#. Hit the reset button on your Maple (it's the small button at the - bottom left, labeled RESET). Notice that it blinks quickly 6 - times, then blinks slowly a few more times. - -#. Hit reset again, and this time push and hold the other button - during the 6 fast blinks (the button is on the top right; it is - labeled BUT). You can release it once the slow blinks start. - diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst deleted file mode 100644 index b8382c4..0000000 --- a/docs/source/unix-toolchain.rst +++ /dev/null @@ -1,454 +0,0 @@ -.. highlight:: sh - -.. _unix-toolchain: - -=========================== - Unix Toolchain Quickstart -=========================== - -This is a tutorial for using the Maple with a standard Unix toolchain -(``make``, ``gcc``, etc.). It's not necessary to do this in order to -program the Maple; you can always :ref:`install the Maple IDE -<maple-ide-install>` instead. This document is intended for users who -are comfortable using C or C++ and would like to use :ref:`libmaple` -directly. - -You'll need a Maple board, a Mini-B USB cable, a functional computer, -and root (or Administrator) access to that computer. This guide -assumes you've had success with the IDE on your machine and that you -are fairly comfortable with the Unix command line. Some previous -experience with editing your shell startup script (.bashrc, .tcshrc, -etc.) and using `GCC <http://gcc.gnu.org/>`_ and `make -<http://www.gnu.org/software/make/>`_ is recommended. - -For generic installation and setup issues, see the :ref:`IDE -installation <maple-ide-install>` and :ref:`troubleshooting` pages. If -all else fails, try our `forum`_, or `contact us directly`_\ ! - -We currently have instructions for 32- and 64-bit Linux and OS X Snow -Leopard. If you're on another Unix platform, Windows, or an earlier -version of OS X, we're guessing that you can translate/port these -directions on your own. As a jumping off point, you might want to -begin with these `stripped down distributions -<http://static.leaflabs.com/pub/codesourcery/>`_ of the `CodeSourcery -GCC compiler tools <http://www.codesourcery.com/sgpp/features.html>`_ -(including Win32 versions). If you do have success on other platforms, -please post in the forums, so we can fold your tips into this -document! - -.. contents:: Contents - :local: - -.. _toolchain-linux-setup: - -Setup ------ - -Linux -^^^^^ - -These instructions are oriented towards Linux users using a -contemporary Debian-based distribution. - -**1. Collect and Install Tools** - -Firs, you'll need some tools:: - - $ sudo aptitude install build-essential git-core wget screen dfu-util \ - openocd python python-serial - -You'll want to install a bunch of developer "basics" like ``make``, -``tar``, etc. A good catch-all for these tools is the -``build-essential`` meta-package on most Debian platforms: installing -this fake package will pull in dozens of useful tools without bogging -your system down too much. - -`Git <http://git-scm.com/>`_ is a distributed code versioning system -we use to track changes in our source code; ``git-core`` is the -corresponding package. - -``wget`` is a simple tool to download files over http from the command -line; installing it is optional (you could pull in the required -downloads using a browser). - -``screen`` is a screen manager; in the context of Maple, we use it to -connect to serial port devices. - -``dfu-util`` is a tool from the `OpenMoko`_ project that we use to -upload programs to the Maple over USB. - -.. _OpenMoko: http://openmoko.com/ - -``openocd`` is a `JTAG -<http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ control -program used in conjunction with an ARM JTAG device to do in circuit -debugging (pause/resume program execution, upload and download code, -read out register status, etc). It's also optional. - -Lastly, our reset script (which sends control signals over the -USB-serial connection to restart and enter the bootloader) is written -in `Python <http://python.org>`_, and requires the `PySerial -<http://pyserial.sourceforge.net/>`_ library available in the -``python-serial`` package. This can also be installed with -`easy_install <http://peak.telecommunity.com/DevCenter/EasyInstall>`_. - -**2. Fetch libmaple and Compiler Toolchain** :: - - $ cd ~ - $ git clone git://github.com/leaflabs/libmaple.git libmaple - $ cd libmaple - $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz - $ tar xvzf gcc-arm-none-eabi-latest-linux32.tar.gz - $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up - -This step is fairly straightforward: do a git clone of the `libmaple -repository <https://github.com/leaflabs/libmaple>`_ to some directory, -then download and extract the ARM compiler toolchain. - -The :file:`arm/bin/` directory will need to be added to ``PATH``; you -can check that this worked by entering ``arm-none-`` and hitting tab -to auto-complete (your shell should show a bunch of results). -Regardless of where you put the toolchain, make sure to preserve its -internal directory layout, as the binaries make relative path calls -and references. - -After you're done, you'll probably want to update your shell startup -script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. - -.. _toolchain-udev: - -**3. Install udev Rules** - -From the libmaple directory, :: - - $ groups # make sure it includes plugdev; if not add, yourself to it - $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules - $ sudo restart udev - -As a security precaution on Linux, unknown USB devices can only be -accessed by root. This udev script identifies the Maple based on its -vendor and product IDs, mounts it to :file:`/dev/maple`, and grants -read/write permissions to the ``plugdev`` group. After restarting -``udev`` you'll need to fully unplug or power cycle any Maples -connected to the computer. - -**So far, so good?** - -Great! Test your setup by :ref:`compiling a sample program -<toolchain-test>`. - -.. _toolchain-osx-setup: - -OS X -^^^^ - -These instructions have been tested successfully on OS X 10.6.4. As -stated previously, this document assumes a general level of Unix -aptitude on the part of the reader; if you're uncomfortable using -Terminal (or if you don't know what that means), then you should -probably stick with using the `Maple IDE -<http://leaflabs.com/docs/maple-ide/>`_ to write programs. - -**1. Collect and Install Tools** - -You will need the following tools\ [#fpackman]_ to get started: - - 1. `XCode <http://developer.apple.com/technologies/xcode.html>`_: If - you're reading this, you've probably already got this. Provides - compilers and other basic tools of the trade. While XCode was once - free of charge, Apple has since begun charging for it; if you'd - rather not pay, you can probably get by with just a `make - <http://www.gnu.org/software/make/>`_ binary. - - 2. `Git <http://git-scm.com/>`_: 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. - - 3. ``dfu-util``: A tool from `OpenMoko`_ that we use to upload - programs to the Maple over USB. If you prefer to compile from - source, OpenMoko provides instructions for `building dfu-util - <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_. - - If you're in a hurry, you can steal a dfu-util binary from a program - called `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 copy - the OpenMoko application into your :file:`/Applications` folder (or - wherever you like). Let's pretend you saved the .app to the directory - - :file:`/Applications/OpenMoko Flasher.app` - - Then the ``dfu-util`` binary resides in - - :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` - - To get access to it from the command line, just make a symbolic link - to the binary from some place on your ``PATH``:: - - $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ - /somewhere/on/your/PATH/dfu-util - - .. note:: - Just copying the binary somewhere doesn't work, as it relies on - dynamically linked libraries found elsewhere in the .app - bundle. It's possible to pull just the relevant pieces out of the - .app, but you're on your own. - - To make sure this worked, try plugging in your Maple, making sure - it's in :ref:`perpetual bootloader mode - <troubleshooting-perpetual-bootloader>` (do this by pressing RESET, - then quickly pressing BUT and holding it for several seconds), then - running :: - - $ dfu-util -l - - If you see some lines that look like :: - - Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00" - Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000" - - then you're all set. - - 4. PySerial: our reset script (which sends control signals over the - USB-serial connection to restart and enter the bootloader) is written - in Python and requires the `PySerial - <http://pyserial.sourceforge.net/>`_ library. Download the `latest - version <http://pypi.python.org/pypi/pyserial>`_. After you download - and untar, install it with :: - - $ cd /path/to/pyserial-x.y - $ python setup.py build - $ sudo python setup.py install - - The package is also available via ``easy_install``, so if you're - comfortable using that, you could also install it with :: - - $ easy_install pyserial - -**2. Fetch libmaple and Compiler Toolchain** - -You first need to clone libmaple:: - - $ cd ~ - $ git clone git://github.com/leaflabs/libmaple.git libmaple - -Then you need to get the cross-compilers we use to build a -project. These are just modified versions of GCC; you can `download -them for OS X here -<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_. Assuming -you saved this file to - - :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz` - -you can then unpack the archive and let OS X know where the compilers -live with :: - - $ cd ~/Downloads - $ tar -xvzf gcc-blah-blah-macosx32.tar.gz - $ mv arm ~/libmaple/arm - $ export PATH=$PATH:~/libmaple/arm/bin - -After that's done, you'll probably want to update your shell startup -script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. - -**So far, so good?** - -Great! Go on to the next section, where you test everything out. - -.. _toolchain-test: - -Test compilation ----------------- - -Get back into the libmaple directory (this tutorial assumes you put it -in :file:`~/libmaple`) and test that you've installed all the compilation -tools correctly:: - - $ cd ~/libmaple - $ cp main.cpp.example main.cpp - $ make clean - $ make - -If it all works out, you should end up seeing something like this:: - - find build -iname *.o | xargs arm-none-eabi-size -t - text data bss dec hex filename - 482 4 24 510 1fe build/wirish/comm/HardwareSerial.o - 260 0 0 260 104 build/wirish/comm/HardwareSPI.o - 60 0 0 60 3c build/wirish/wirish.o - - [...] - - 2196 0 1 2197 895 build/libmaple/usb/usb_lib/usb_core.o - 1904 0 0 1904 770 build/libmaple/usb/usb_lib/usb_regs.o - 56 0 0 56 38 build/libmaple/usb/usb_lib/usb_init.o - 344 0 0 344 158 build/libmaple/usb/usb_hardware.o - 6637 0 58 6695 1a27 build/main.o - 21499 201 391 22091 564b (TOTALS) - - Final Size: - arm-none-eabi-size build/maple.out - text data bss dec hex filename - 21824 200 552 22576 5830 build/maple.out - Flash build - -The ``dec`` field at the end gives the total program size in -bytes. The long listing of object files above the ``Final Size`` helps -to identify bloated code. As you write larger projects, you may find -that they use too much space. If that happens, the file-by-file -listing will help you track down the culprits. - -.. _toolchain-upload: - -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>`. If you're on Linux, then before -executing ``make install``, you'll want to have the udev rules setup -:ref:`as described above <toolchain-udev>`. - -Plug in your Maple using the Mini-B USB cable; then run :: - - $ cd ~/libmaple - $ cp examples/test-session.cpp main.cpp - $ make clean - $ make - $ make install - -A number of things can go wrong at this stage. Simple debugging steps -include using :ref:`perpetual bootloader mode -<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 interface -------------------------------------- - -Now let's try out the interactive test session. The serial port -device file should look something like :file:`/dev/ttyACMXXX` on Linux -or :file:`/dev/tty.usbmodemXXX` on OS X, but ``XXX`` will vary -depending on your system. Try using one of these to find out which it -is:: - - # Linux - $ ls /dev/ttyACM* - - # OS X - $ ls /dev/tty.usbmodem* - -To open up a session, run :: - - $ screen /dev/ttyXXX - -If the interactive test program built and uploaded correctly, -``screen`` won't report any errors, and will present you an empty -terminal. Your board is now waiting for you to send it a command. -Type ``h`` to print a list of commands which demonstrate various -features; type any command's letter to run it. - -To exit the screen session, type :kbd:`C-a C-\\` (control-a, followed -by control-backslash) on Mac, or :kbd:`C-a k` (control-a k) on Linux, -and type ``y`` when prompted if you're sure. - -.. note:: - - Using ``screen`` sometimes messes up your terminal session on OS X. - If your shell starts acting funny after you exit ``screen``, you - should be able to fix it with :: - - $ reset && clear - - If that doesn't work, just close the Terminal window and open up a - new one. - -.. _toolchain-projects: - -Starting your own projects --------------------------- - -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. - -At a minimum, your include path should contain the directories -:file:`~/libmaple/libmaple` and :file:`~/libmaple/wirish/`. If you -want to use one of the officially supported :ref:`libraries -<libraries>`, those live under :file:`~/libmaple/libraries/`. The -main include file for the Wirish library is -:file:`~/libmaple/wirish/wirish.h`. - -Getting Updates ---------------- - -We update libmaple fairly frequently with bugfixes and other -improvements. In order get access to these in your local copy of -the repository, you should periodically update it with:: - - $ cd ~/libmaple - $ git pull - -We keep releases of libmaple and the Maple IDE in lockstep, so any -IDE updates will have corresponding library updates. Our `blog -<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: - -Debug with OpenOCD ------------------- - -TODO. For now see `this great guide -<http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se, and -the ``jtag`` Makefile target. There is also a `JTAG How-To -<http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ page on -our `wiki <http://wiki.leaflabs.com>`_ which you may find useful. - -.. _toolchain-exuberantly: - -Go forth exuberantly! ---------------------- - -Let us know what you come up with! Use #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! - -.. 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. Of course, your mileage - may vary. diff --git a/docs/source/usart.rst b/docs/source/usart.rst deleted file mode 100644 index e65821d..0000000 --- a/docs/source/usart.rst +++ /dev/null @@ -1,54 +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: - -Hardware/Circuit Design ------------------------ - -.. TODO [0.0.12] Add some more information here (like how you should -.. connect TX_a to RX_b and RX_a to TX_b). - -.. TODO [0.0.12/Maple Native] UART4 and UART5, Native links - -Each LeafLabs board has at least 3 separate USART devices. In the most -simple use case, the RX and TX pins are used to send data at a -predetermined 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>` - -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/stonline/products/literature/rm/13902.pdf>`_ - (PDF), Chapter 27. diff --git a/docs/source/usb.rst b/docs/source/usb.rst deleted file mode 100644 index a67d710..0000000 --- a/docs/source/usb.rst +++ /dev/null @@ -1,48 +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_021411.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>`_ -* ST documentation: - * Reference Manual `RM0008 - <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ - (PDF), Chapter 23, "Universal serial bus full-speed device - interface" - * `Programming Manual - <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ - (PDF; assembly language and register reference) |
