aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/adc.rst65
-rw-r--r--docs/source/arduino-cc-attribution.txt (renamed from docs/source/lang/api/cc-attribution.txt)6
-rw-r--r--docs/source/bootloader.rst7
-rw-r--r--docs/source/external-interrupts.rst119
-rw-r--r--docs/source/gpio.rst114
-rw-r--r--docs/source/hardware/maple-ret6.rst276
-rw-r--r--docs/source/hardware/maple.rst210
-rw-r--r--docs/source/i2c.rst40
-rw-r--r--docs/source/index.rst12
-rw-r--r--docs/source/jtag.rst26
-rw-r--r--docs/source/lang/api/abs.rst3
-rw-r--r--docs/source/lang/api/analogread.rst65
-rw-r--r--docs/source/lang/api/analogwrite.rst23
-rw-r--r--docs/source/lang/api/attachinterrupt.rst57
-rw-r--r--docs/source/lang/api/bit.rst12
-rw-r--r--docs/source/lang/api/bitclear.rst13
-rw-r--r--docs/source/lang/api/bitread.rst11
-rw-r--r--docs/source/lang/api/bitset.rst9
-rw-r--r--docs/source/lang/api/bitwrite.rst7
-rw-r--r--docs/source/lang/api/board-values.rst5
-rw-r--r--docs/source/lang/api/constants.rst2
-rw-r--r--docs/source/lang/api/constrain.rst5
-rw-r--r--docs/source/lang/api/cos.rst6
-rw-r--r--docs/source/lang/api/delay.rst6
-rw-r--r--docs/source/lang/api/delaymicroseconds.rst11
-rw-r--r--docs/source/lang/api/detachinterrupt.rst8
-rw-r--r--docs/source/lang/api/digitalread.rst39
-rw-r--r--docs/source/lang/api/digitalwrite.rst39
-rw-r--r--docs/source/lang/api/hardwaretimer.rst95
-rw-r--r--docs/source/lang/api/highbyte.rst6
-rw-r--r--docs/source/lang/api/loop.rst3
-rw-r--r--docs/source/lang/api/lowbyte.rst2
-rw-r--r--docs/source/lang/api/map.rst2
-rw-r--r--docs/source/lang/api/max.rst5
-rw-r--r--docs/source/lang/api/micros.rst2
-rw-r--r--docs/source/lang/api/millis.rst2
-rw-r--r--docs/source/lang/api/min.rst3
-rw-r--r--docs/source/lang/api/pinmode.rst8
-rw-r--r--docs/source/lang/api/pow.rst5
-rw-r--r--docs/source/lang/api/pwmwrite.rst14
-rw-r--r--docs/source/lang/api/random.rst6
-rw-r--r--docs/source/lang/api/randomseed.rst2
-rw-r--r--docs/source/lang/api/serial.rst50
-rw-r--r--docs/source/lang/api/setup.rst2
-rw-r--r--docs/source/lang/api/sin.rst3
-rw-r--r--docs/source/lang/api/sq.rst3
-rw-r--r--docs/source/lang/api/tan.rst3
-rw-r--r--docs/source/lang/api/volatile.rst8
-rw-r--r--docs/source/lang/cc-attribution.txt9
-rw-r--r--docs/source/lang/cpp/arithmetic.rst2
-rw-r--r--docs/source/lang/cpp/array.rst6
-rw-r--r--docs/source/lang/cpp/assignment.rst2
-rw-r--r--docs/source/lang/cpp/bitshift.rst3
-rw-r--r--docs/source/lang/cpp/bitwisemath.rst3
-rw-r--r--docs/source/lang/cpp/boolean.rst3
-rw-r--r--docs/source/lang/cpp/booleanvariables.rst6
-rw-r--r--docs/source/lang/cpp/break.rst5
-rw-r--r--docs/source/lang/cpp/byte.rst3
-rw-r--r--docs/source/lang/cpp/bytecast.rst8
-rw-r--r--docs/source/lang/cpp/char.rst10
-rw-r--r--docs/source/lang/cpp/charcast.rst6
-rw-r--r--docs/source/lang/cpp/comments.rst5
-rw-r--r--docs/source/lang/cpp/comparison.rst3
-rw-r--r--docs/source/lang/cpp/compoundarithmetic.rst3
-rw-r--r--docs/source/lang/cpp/compoundbitwise.rst1
-rw-r--r--docs/source/lang/cpp/const.rst6
-rw-r--r--docs/source/lang/cpp/continue.rst4
-rw-r--r--docs/source/lang/cpp/curly-braces.rst5
-rw-r--r--docs/source/lang/cpp/define.rst6
-rw-r--r--docs/source/lang/cpp/double.rst4
-rw-r--r--docs/source/lang/cpp/doublecast.rst2
-rw-r--r--docs/source/lang/cpp/dowhile.rst3
-rw-r--r--docs/source/lang/cpp/float.rst2
-rw-r--r--docs/source/lang/cpp/floatcast.rst2
-rw-r--r--docs/source/lang/cpp/for.rst4
-rw-r--r--docs/source/lang/cpp/goto.rst3
-rw-r--r--docs/source/lang/cpp/if.rst2
-rw-r--r--docs/source/lang/cpp/include.rst4
-rw-r--r--docs/source/lang/cpp/increment.rst2
-rw-r--r--docs/source/lang/cpp/intcast.rst5
-rw-r--r--docs/source/lang/cpp/longcast.rst2
-rw-r--r--docs/source/lang/cpp/longlong.rst2
-rw-r--r--docs/source/lang/cpp/modulo.rst2
-rw-r--r--docs/source/lang/cpp/pointer.rst2
-rw-r--r--docs/source/lang/cpp/return.rst3
-rw-r--r--docs/source/lang/cpp/scope.rst2
-rw-r--r--docs/source/lang/cpp/semicolon.rst5
-rw-r--r--docs/source/lang/cpp/sizeof.rst2
-rw-r--r--docs/source/lang/cpp/sqrt.rst3
-rw-r--r--docs/source/lang/cpp/static.rst3
-rw-r--r--docs/source/lang/cpp/string.rst3
-rw-r--r--docs/source/lang/cpp/switchcase.rst4
-rw-r--r--docs/source/lang/cpp/unsignedchar.rst5
-rw-r--r--docs/source/lang/cpp/unsignedint.rst2
-rw-r--r--docs/source/lang/cpp/unsignedlonglong.rst2
-rw-r--r--docs/source/lang/cpp/variables.rst3
-rw-r--r--docs/source/lang/cpp/void.rst4
-rw-r--r--docs/source/lang/cpp/while.rst2
-rw-r--r--docs/source/lang/unimplemented/notone.rst17
-rw-r--r--docs/source/lang/unimplemented/tone.rst27
-rw-r--r--docs/source/language-index.rst17
-rw-r--r--docs/source/language.rst65
-rw-r--r--docs/source/libmaple/api/systick.rst8
-rw-r--r--docs/source/libraries.rst176
-rw-r--r--docs/source/libs/servo.rst59
-rw-r--r--docs/source/libs/wire.rst104
-rw-r--r--docs/source/maple-quickstart.rst14
-rw-r--r--docs/source/pwm.rst31
-rw-r--r--docs/source/spi.rst10
-rw-r--r--docs/source/timers.rst206
-rw-r--r--docs/source/troubleshooting.rst4
-rw-r--r--docs/source/usart.rst19
-rw-r--r--docs/source/usb.rst54
113 files changed, 1301 insertions, 1113 deletions
diff --git a/docs/source/adc.rst b/docs/source/adc.rst
index b943808..af613cc 100644
--- a/docs/source/adc.rst
+++ b/docs/source/adc.rst
@@ -6,23 +6,12 @@
Analog-Digital Conversion is the process of reading a physical voltage
as a number. The Maple has a large number of pins which are capable of
-taking 12-bit ADC measurements, which means that voltages from ground
-to +3.3v are read as numbers from 0 to 4095; this corresponds to a
+taking 12-bit ADC measurements, which means that voltages from 0 to
+3.3V are read as numbers from 0 to 4095. This corresponds to a
theoretical sensitivity of just under 1 millivolt. In reality, a
-number of factors introduce noise and bias into this reading and a
+number of factors introduce noise and bias into this reading, and a
number of techniques must be used to get good precision and accuracy.
-.. compound::
-
- The header pins with ADC functionality (marked as "AIN" on the
- silkscreen) are:
-
- D0, D1, D2, D3, D10, D11, D12, D13, D15, D16, D17, D18, D19, D20, D27, D28
-
- Note that pins 3, 27, and 28 are not marked AIN on the silkscreen
- for Maple revisions through Rev 5, however, they **do work** as
- analog input pins.
-
.. contents:: Contents
:local:
@@ -31,13 +20,15 @@ number of techniques must be used to get good precision and accuracy.
Noise and Bias
--------------
+.. FIXME [0.0.10, Maple-specific]
+
The biggest issues with analog-digital conversion are noise and bias.
With the Maple, we have tried to isolate the ADC pins and traces from
-strong noise sources but there are always trade--offs between noise,
+strong noise sources, but there are always trade--offs between noise,
additional functionality, cost, and package size.
The 6 ADC pins in a bank (D15--D20) generally have the least
-noise and should be used for fine measurements. If the input voltage
+noise, and should be used for fine measurements. If the input voltage
changes relatively slowly, a number of samples can be taken in
succession and averaged together, or the same voltage can even be
sampled by multiple ADC pins at the same time.
@@ -47,34 +38,40 @@ voltages that the sample is being compared against. In the case of the
Maple, the high reference is |vcc| and the low reference is ground.
This means that noise or fluctuations on either |vcc| or ground will
affect the measurement. It also means that the voltage you are trying
-to sample must be between ground and 3.3V. In the case of a variable
-reading, it is best if the voltage varies over the entire range of
-0--3.3V; otherwise, only a fraction of the sensitivity is being
-leveraged. Resistor dividers and constant voltage diodes are basic
-tools which can help bring a given voltage signal into the appropriate
-range; opamps and other powered components can also be used.
+to sample must be between ground and 3.3V.
+
+.. _adc-range:
+
+In the case of a variable reading, it is best if the voltage varies
+over the entire range of 0--3.3V; otherwise, only a fraction of the
+sensitivity is being leveraged. Some basic tools to accomplish this
+are `resistor dividers
+<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
------------------
-.. doxygenfunction:: analogRead
-
-.. doxygenfunction:: pinMode
-
-.. doxygenenum:: WiringPinMode
+* :ref:`lang-analogread`
+* :ref:`lang-pinmode`
.. _adc-recommended-reading:
Recommended Reading
-------------------
-* `Wikipedia article on Analog-to-digital converter <http://en.wikipedia.org/wiki/Analog-to-digital_converter>`_
-
-* `Arduino Analog Input Tutorial <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
-
-* STMicro documentation:
+* `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 (pdf) <http://www.st.com/stonline/products/literature/an/16840.pdf>`_
- * `Application Note on ADC Oversampling (pdf) <http://www.st.com/stonline/products/literature/an/14183.pdf>`_
+ * `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/lang/api/cc-attribution.txt b/docs/source/arduino-cc-attribution.txt
index e100140..ad1c1e0 100644
--- a/docs/source/lang/api/cc-attribution.txt
+++ b/docs/source/arduino-cc-attribution.txt
@@ -1,9 +1,9 @@
-.. Included in all this directory's files in order to satisfy the
-.. Arduino CC Attribution-ShareAlike 3.0 License
+.. Included in all relevant 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
+ 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/bootloader.rst b/docs/source/bootloader.rst
index 85b2674..ec4fe73 100644
--- a/docs/source/bootloader.rst
+++ b/docs/source/bootloader.rst
@@ -1,8 +1,9 @@
.. highlight:: sh
-=====================
- Maple Bootloader(s)
-=====================
+.. _bootloader:
+
+Maple Bootloader(s)
+===================
The firmware which allows the Maple to be reprogrammed via a USB
connection. Every Maple board comes programmed with this by default,
diff --git a/docs/source/external-interrupts.rst b/docs/source/external-interrupts.rst
index b2cbbb1..ac065a4 100644
--- a/docs/source/external-interrupts.rst
+++ b/docs/source/external-interrupts.rst
@@ -6,73 +6,42 @@ External Interrupts
===================
External interrupts can be used to trigger routines to run in response
-to changes in voltage on a pin. Each GPIO pin on the Maple can be used
-to detect transitions such as when the voltage goes from low to high,
-or from high to low. This technique can be used to avoid unnecessary
-polling of the state of a pin.
+to changes in voltage on a pin. Each :ref:`GPIO pin <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 microcontroller. These can be used to tell the Maple
-when events happen, such as when a sensor has data ready to be read,
-or when a button has been pushed. When such an event happens, an
-interrupt is raised and the Maple can react to it with a preset
-*interrupt handler*.
-
-Every GPIO pin on the Maple can be used as an external interrupt,
-subject to certain constraints; there can be a maximum of 16 different
-external interrupts set up at a time on the Maple. This is because the
-external interrupt lines on the STM32 are multiplexed between GPIO
-ports. In effect, this means that every pin on the Maple maps to a
-certain EXTI line, and within that EXTI line, only one of the pins
-that maps to it can be used as an external interrupt at a time.
-
-The following table shows which pins can be used on which lines.
-
-.. list-table::
- :widths: 1 1
- :header-rows: 1
-
- * - EXTI Line
- - Maple pins
- * - EXTI0
- - 2, 15, 27
- * - EXTI1
- - 3, 16, 28
- * - EXTI2
- - 1, 17, 25
- * - EXTI3
- - 0, 18
- * - EXTI4
- - 10, 19
- * - EXTI5
- - 4, 13, 20
- * - EXTI6
- - 5, 12, 35
- * - EXTI7
- - 9, 11, 36
- * - EXTI8
- - 6, 14, 37
- * - EXTI9
- - 7, 25, 28
- * - EXTI10
- - 8, 26, 29
- * - EXTI11
- - 30
- * - EXTI12
- - 31
- * - EXTI13
- - 21, 32
- * - EXTI14
- - 22, 33
- * - EXTI15
- - 23, 34
+outside of the microcontroller. These can be used to tell Maple when
+events happen, such as when a sensor has data ready to be read, or
+when a button has been pushed. When such an event happens, an
+interrupt is raised, and the Maple can react to it with a preset
+*interrupt handler*, which is a function that gets called whenever the
+event occurs.
+
+.. _external-interrupts-exti-line:
+
+Every GPIO pin can generate an external interrupt, subject to certain
+constraints. There can be a maximum of 16 different external
+interrupts set up at a time. This is because the external interrupt
+lines on the STM32 are shared between GPIO ports. In effect, this
+means that every pin on the Maple connects to what is called an *EXTI
+line*, and within an EXTI line, only one of the pins that connects to
+it can be used to detect external interrupts at a time.
+
+The EXTI Line Pin Map for your board lists which pins connect to which
+EXTI lines:
+
+* :ref:`Maple <maple-exti-map>`
+* :ref:`Maple RET6 Edition <maple-ret6-exti-map>`
.. note::
@@ -80,40 +49,16 @@ The following table shows which pins can be used on which lines.
desired pin to an input mode (e.g ``INPUT`` or ``INPUT_FLOATING``,
``INPUT_PULLUP``, ``INPUT_PULLDOWN``).
-
Function Reference
------------------
- :ref:`attachInterrupt() <lang-attachinterrupt>`
- :ref:`detachInterrupt() <lang-detachinterrupt>`
-Code example
-------------
-
-Blink the LED on every transition::
-
- int pin = 13;
- volatile int state = LOW;
-
- void setup() {
- pinMode(pin, OUTPUT);
- pinMode(0, INPUT_FLOATING);
- attachInterrupt(0, blink, CHANGE);
- }
-
- void loop() {
- digitalWrite(pin, state);
- }
-
- void blink() {
- state = !state;
- }
-
-
Recommended Reading
-------------------
-* STMicro documentation for STM32F103RB microcontroller:
-
- * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf)
- * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)
+* 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".
diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst
index 0f9f4df..74be3d4 100644
--- a/docs/source/gpio.rst
+++ b/docs/source/gpio.rst
@@ -3,86 +3,54 @@
GPIO
====
-.. FIXME [Maple-specific values]
+Each LeafLabs board comes with ready-to-use General Purpose
+Input/Output (GPIO) pins, which are numbered starting from zero.
+These numbers are listed on your board's silkscreen, next to where the
+pin is broken out to a header. Many pins may additionally be used for
+special features or peripheral functions.
-The Maple features 38 ready-to-use general purpose input/output (GPIO)
-pins for digital input/output, numbered D0 through D37. These numbers
-correspond to the numeric values next to each header on the Maple
-silkscreen.
+.. contents:: Contents
+ :local:
-Many of these pins may additionally be used for special features or
-peripheral functions. This page documents those capabilities, by pin.
+.. _gpio-pin-maps:
-The current and voltage limitations have been copied over from the
-STM32 datasheet (see the :ref:`Recommended Reading
-<gpio-recommended-reading>` for a link). In particular, a number of
-GPIO pins are 5V tolerant (which means that applying 5 volts to a pin
-and reading it as input or allowing it to drain to ground will not
-damage that pin), while some are not.
+Pin Maps
+--------
-.. contents:: Contents
- :local:
+The hardware documentation for your board lists each pin's
+capabilities, by pin number:
+
+.. TODO [0.1.0] Uncomment Mini and Native GPIO links
+
+* :ref:`Maple <maple-gpios>`
+* :ref:`Maple RET6 Edition <maple-ret6-gpios>`
-.. _pin-mapping-mega-table:
-
-Pin Mapping Mega Table
-----------------------
-
-This table shows the available functionality on every GPIO pin, by
-peripheral type. The "STM32" column refers to the port and number that
-the header is connected to on the microcontroller. The "5V?" column
-documents whether or not the pin is 5 volt tolerant (see above).
-
-.. TODO silkscreen pictures which let you know what each abbreviation
-.. means, with links to the relevant documentation.
-
-.. csv-table::
- :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?"
-
- "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No"
- "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No"
- "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No"
- "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No"
- "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No"
- "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes"
- "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes"
- "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes"
- "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes"
- "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes"
- "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No"
- "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No"
- "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No"
- "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No"
- "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes"
- "D15", "PC0", "ADC10", "-", "-", "-", "-", "No"
- "D16", "PC1", "ADC11", "-", "-", "-", "-", "No"
- "D17", "PC2", "ADC12", "-", "-", "-", "-", "No"
- "D18", "PC3", "ADC13", "-", "-", "-", "-", "No"
- "D19", "PC4", "ADC14", "-", "-", "-", "-", "No"
- "D20", "PC5", "ADC15", "-", "-", "-", "-", "No"
- "D21", "PC13", "-", "-", "-", "-", "-", "No"
- "D22", "PC14", "-", "-", "-", "-", "-", "No"
- "D23", "PC15", "-", "-", "-", "-", "-", "No"
- "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes"
- "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes"
- "D26", "PC10", "-", "-", "-", "-", "-", "Yes"
- "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No"
- "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No"
- "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes"
- "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes"
- "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBAL", "USART3_CK", "SPI2_NSS", "Yes"
- "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes"
- "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes"
- "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes"
- "D35", "PC6", "-", "-", "-", "-", "-", "Yes"
- "D36", "PC7", "-", "-", "-", "-", "-", "Yes"
- "D37", "PC8", "-", "-", "-", "-", "-", "Yes"
+.. * :ref:`Maple Mini <maple-mini-gpios>`
+.. * :ref:`Maple Native <maple-native-gpios>`
+
+The current and voltage limitations were determined using the STM32
+datasheets. In particular, only some GPIO pins are **5V tolerant**,
+which means that applying 5 volts to a pin and reading it as input or
+allowing it to drain to ground will not damage that pin. Connecting a
+voltage higher than 3.3V to a non-5V tolerant pin may damage your
+board.
.. _gpio-modes:
GPIO Modes
----------
+Each of the GPIO pins on a Maple board may be configured using
+pinMode() to behave in a number of ways: as a digital output pin,
+or as an analog input pin, etc., depending on the particular pin.
+
+A ``WiringPinMode`` value specifies the complete set of possible
+configurations; not every pin can have all of these modes. For
+example, on the Maple, pin 15 may have mode ``INPUT_ANALOG``, but not
+``PWM``. See your :ref:`board's pin maps <gpio-pin-maps>` and its
+silkscreen for more information on what functionality is available on
+each pin.
+
.. doxygenenum:: WiringPinMode
Function Reference
@@ -105,7 +73,11 @@ Function Reference
Recommended Reading
-------------------
-STMicro documentation for STM32F103RB microcontroller:
+* ST Documentation for the STM32F103 series of microcontrollers:
- * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf)
* `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)
+
+ * `Programming Manual
+ <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_
+ (PDF; assembly language and register reference)
+
diff --git a/docs/source/hardware/maple-ret6.rst b/docs/source/hardware/maple-ret6.rst
new file mode 100644
index 0000000..06dcaff
--- /dev/null
+++ b/docs/source/hardware/maple-ret6.rst
@@ -0,0 +1,276 @@
+.. highlight:: sh
+
+.. _maple-ret6:
+
+Maple RET6 Edition
+==================
+
+.. contents:: Contents
+ :local:
+
+Technical Specifications
+------------------------
+
+ * MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor
+ * Clock Speed: **72 MHz**
+ * Operating Voltage: 3.3V
+ * Input Voltage (recommended): 3V-12V
+ * 39 Digital I/O Pins (:ref:`GPIO <gpio>`)
+ * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC <adc>`)
+ * 15 **PWM** pins at 16-bit resolution (:ref:`PWM <pwm>`)
+ * Dedicated **USB** port for programming and communications (:ref:`USB<usb>`)
+ * External **JTAG** interface (:ref:`JTAG <jtag>`)
+ * **512KB Flash** and **64KB SRAM**
+ * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs)
+ * Integrated **SPI** (:ref:`SPI <spi>`)
+ * Integrated **I2C** (:ref:`I2C <i2c>`)
+ * 12 Channels of Direct Memory Access (**DMA**)
+ * 3 **USART** and 2 **UART** devices (:ref:`USART <usart>`)
+ * Six 4-channel and two basic **timers** (:ref:`Timers <timers>`)
+ * Supplies up to 800mA @ 3.3v
+ * Support for low power and sleep modes (<500uA)
+ * Dimensions are 2.05″x2.1″
+
+.. _maple-ret6-powering:
+
+Powering the Maple RET6 Edition
+-------------------------------
+
+The Maple RET6 Edition's power source is determined by the header to
+the left of the "LeafLabs" label on the silkscreen. The RET6 Edition
+can be powered from the barrel jack connector, USB, or a LiPo battery.
+We ship the RET6 Edition with a jumper on the USB selector. In order
+to power it off of an alternative source, unplug the board, then move
+the jumper to the desired selector before reconnecting power.
+
+You can also power the Maple via the pin labeled "Vin" on the lower
+header. However, don't do this while simultaneously powering the
+board from another source, or you could damage the it.
+
+Using the Built-in Battery Charger
+----------------------------------
+
+The RET6 Edition has a built-in LiPo battery charger. In order to use
+it, put a jumper across the CHRG header on the power selection header
+and across the USB, or EXT selectors, depending on whether you're
+charging the battery via USB cable or barrel jack connector. The LED
+labeled CHRG will light up while the battery is being charged. When
+the battery is finished charging, the LED labeled DONE will also light
+up.
+
+.. _maple-ret6-gpios:
+
+GPIO Information
+----------------
+
+The RET6 Edition features 38 ready-to-use general purpose input/output
+(GPIO) pins for digital input/output, numbered ``D0`` through ``D37``.
+These numbers correspond to the numeric values next to each header on
+the Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are
+available through use in combination with the
+:ref:`lang-disabledebugports` function; see the :ref:`board-specific
+debug pin constants <lang-board-values-debug>` for more information.
+
+.. TODO [0.1.0] silkscreen pictures which expand abbreviations
+
+.. _maple-ret6-pin-map-master:
+
+Master Pin Map
+^^^^^^^^^^^^^^
+
+.. TODO [0.0.10] Update from base Maple information
+
+This table shows the available functionality on every GPIO pin, by
+peripheral type. The "STM32" column refers to the port and number that
+the header is connected to on the microcontroller. The "5V?" column
+documents whether or not the pin is 5 volt tolerant.
+
+.. csv-table::
+ :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?"
+
+ "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No"
+ "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No"
+ "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No"
+ "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No"
+ "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No"
+ "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes"
+ "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes"
+ "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes"
+ "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes"
+ "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes"
+ "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No"
+ "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No"
+ "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No"
+ "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No"
+ "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes"
+ "D15", "PC0", "ADC10", "-", "-", "-", "-", "No"
+ "D16", "PC1", "ADC11", "-", "-", "-", "-", "No"
+ "D17", "PC2", "ADC12", "-", "-", "-", "-", "No"
+ "D18", "PC3", "ADC13", "-", "-", "-", "-", "No"
+ "D19", "PC4", "ADC14", "-", "-", "-", "-", "No"
+ "D20", "PC5", "ADC15", "-", "-", "-", "-", "No"
+ "D21", "PC13", "-", "-", "-", "-", "-", "No"
+ "D22", "PC14", "-", "-", "-", "-", "-", "No"
+ "D23", "PC15", "-", "-", "-", "-", "-", "No"
+ "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes"
+ "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes"
+ "D26", "PC10", "-", "-", "-", "-", "-", "Yes"
+ "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No"
+ "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No"
+ "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes"
+ "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes"
+ "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes"
+ "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes"
+ "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes"
+ "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes"
+ "D35", "PC6", "-", "-", "-", "-", "-", "Yes"
+ "D36", "PC7", "-", "-", "-", "-", "-", "Yes"
+ "D37", "PC8", "-", "-", "-", "-", "-", "Yes"
+
+.. TODO [0.0.10] Another table for the JTAG pins
+
+Timer Pin Map
+^^^^^^^^^^^^^
+
+.. TODO [0.0.10] Add Timer 5,6,7,8 information
+
+The following table shows what pins are associated with a particular
+timer's capture/compare channels.
+
+.. csv-table::
+ :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4
+ :delim: |
+
+ 1 | D6 | D7 | D8 | -
+ 2 | D2 | D3 | D1 | D0
+ 3 | D12 | D11 | D27 | D28
+ 4 | D5 | D9 | D14 | D24
+
+.. _maple-ret6-exti-map:
+
+EXTI Line Pin Map
+^^^^^^^^^^^^^^^^^
+
+The following table shows which pins connect to which :ref:`EXTI lines
+<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
+ * - EXTI4
+ - 10, 19
+ * - EXTI5
+ - 4, 13, 20
+ * - EXTI6
+ - 5, 12, 35
+ * - EXTI7
+ - 9, 11, 36
+ * - EXTI8
+ - 6, 14, 37
+ * - EXTI9
+ - 7, 25, 28
+ * - EXTI10
+ - 8, 26, 29
+ * - EXTI11
+ - 30
+ * - EXTI12
+ - 31
+ * - EXTI13
+ - 21, 32
+ * - EXTI14
+ - 22, 33
+ * - EXTI15
+ - 23, 34
+
+.. _maple-ret6-usart-map:
+
+USART Pin Map
+^^^^^^^^^^^^^
+
+.. FIXME [0.0.10] UART4 and UART5 information
+
+The Maple RET6 Edition has three serial ports (also known as a UARTs
+or USARTs): ``Serial1``, ``Serial2``, and ``Serial3``. They
+communicate using the pins summarized in the following table:
+
+.. csv-table::
+ :header: Serial Port, TX, RX, CK, CTS, RTS
+ :delim: |
+
+ ``Serial1`` | 7 | 8 | 6 | - | -
+ ``Serial2`` | 1 | 0 | 10 | 2 | 3
+ ``Serial3`` | 29 | 30 | 31 | 32 | 33
+
+Board-Specific Values
+---------------------
+
+.. TODO [0.0.10]
+
+Stub.
+
+Hardware Design Files
+---------------------
+
+The hardware schematics and board layout files are available in the
+`Maple Github repository <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 5V-tolerant.
+
+Errata
+------
+
+This section lists known issues and warnings for the Maple RET6 Edition.
+
+* **DAC, UART4, UART5 GPIOs unavailable**: Pins related to the digital
+ to analog converter (DAC) and UARTs 4 and 5 are not broken out to
+ headers. The RET6 Edition's hardware layout is identical to that of
+ the Maple Rev 5, which wasn't designed for use with these
+ STM32F103RET6-only peripherals.
+
+Recommended Reading
+-------------------
+
+* STMicro documentation for STM32F103RE microcontroller:
+
+ * `Datasheet
+ <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00191185.pdf>`_ (PDF)
+ * `Reference Manual
+ <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (PDF)
+ * `Programming Manual
+ <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_
+ (PDF; assembly language and register reference)
diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst
index 1fa4f3f..44848a7 100644
--- a/docs/source/hardware/maple.rst
+++ b/docs/source/hardware/maple.rst
@@ -1,6 +1,6 @@
.. highlight:: sh
-.. _hardware-maple:
+.. _maple:
Maple
=====
@@ -16,15 +16,14 @@ Technical Specifications
* Operating Voltage: 3.3V
* Input Voltage (recommended): 3V-12V
* 39 Digital I/O Pins (:ref:`GPIO <gpio>`)
- * 16 Analog Input Pins
- * 12-bit **ADC** resolution (:ref:`ADC <adc>`)
+ * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC <adc>`)
* 15 **PWM** pins at 16-bit resolution (:ref:`PWM <pwm>`)
- * Dedicated **USB** port for programming and communications (:ref:`USB<usb>`)
- * External **JTAG** interface (:ref:`USB <jtag>`)
- * **128 Flash** and **20KB SRAM**
+ * Dedicated **USB** port for programming and communications (:ref:`USB <usb>`)
+ * External **JTAG** interface (:ref:`JTAG <jtag>`)
+ * **128KB Flash** and **20KB SRAM**
* 64 Channel nested vector interrupt handler (including external interrupt on GPIOs)
- * Integrated **SPI** (:ref:`SPI<spi>`)
- * Integrated **I2C** (:ref:`I2C<i2c>`)
+ * Integrated **SPI** (:ref:`SPI <spi>`)
+ * Integrated **I2C** (:ref:`I2C <i2c>`)
* 7 Channels of Direct Memory Access (**DMA**)
* 3 **USART** divices (:ref:`USART <usart>`)
* Four 4-channel **timers** (:ref:`Timers <timers>`)
@@ -32,7 +31,7 @@ Technical Specifications
* Support for low power and sleep modes (<500uA)
* Dimensions are 2.05″x2.1″
-.. _maple-hardware-identify-rev:
+.. _maple-identify-rev:
Identifying your Rev
--------------------
@@ -79,7 +78,7 @@ have a light red silkscreen and a single pixelated leaf as a logo.
:align: center
:alt: Maple Rev 1
-.. _hardware-maple-powering:
+.. _maple-powering:
Powering the Maple
------------------
@@ -106,17 +105,174 @@ connector. The LED labeled CHRG will light up while the battery is
being charged. When the battery is finished charging, the LED labeled
DONE will also light up.
+.. _maple-gpios:
+
+GPIO Information
+----------------
+
+The Maple features 38 ready-to-use general purpose input/output (GPIO)
+pins for digital input/output, numbered ``D0`` through ``D37``. These
+numbers correspond to the numeric values next to each header on the
+Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are
+available through use in combination with the
+:ref:`lang-disabledebugports` function; see the :ref:`board-specific
+debug pin constants <lang-board-values-debug>` for more information.
+
+.. TODO [0.1.0] silkscreen pictures which expand abbreviations
+
+.. _maple-pin-map-master:
+
+Master Pin Map
+^^^^^^^^^^^^^^
+
+This table shows the available functionality on every GPIO pin, by
+peripheral type. The "STM32" column refers to the port and number that
+the header is connected to on the microcontroller. The "5V?" column
+documents whether or not the pin is 5 volt tolerant.
+
+.. csv-table::
+ :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?"
+
+ "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No"
+ "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No"
+ "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No"
+ "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No"
+ "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No"
+ "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes"
+ "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes"
+ "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes"
+ "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes"
+ "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes"
+ "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No"
+ "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No"
+ "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No"
+ "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No"
+ "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes"
+ "D15", "PC0", "ADC10", "-", "-", "-", "-", "No"
+ "D16", "PC1", "ADC11", "-", "-", "-", "-", "No"
+ "D17", "PC2", "ADC12", "-", "-", "-", "-", "No"
+ "D18", "PC3", "ADC13", "-", "-", "-", "-", "No"
+ "D19", "PC4", "ADC14", "-", "-", "-", "-", "No"
+ "D20", "PC5", "ADC15", "-", "-", "-", "-", "No"
+ "D21", "PC13", "-", "-", "-", "-", "-", "No"
+ "D22", "PC14", "-", "-", "-", "-", "-", "No"
+ "D23", "PC15", "-", "-", "-", "-", "-", "No"
+ "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes"
+ "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes"
+ "D26", "PC10", "-", "-", "-", "-", "-", "Yes"
+ "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No"
+ "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No"
+ "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes"
+ "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes"
+ "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes"
+ "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes"
+ "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes"
+ "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes"
+ "D35", "PC6", "-", "-", "-", "-", "-", "Yes"
+ "D36", "PC7", "-", "-", "-", "-", "-", "Yes"
+ "D37", "PC8", "-", "-", "-", "-", "-", "Yes"
+
+.. TODO [0.0.10] JTAG pins
+
+Timer Pin Map
+^^^^^^^^^^^^^
+
+The following table shows what pins are associated with a particular
+timer's capture/compare channels.
+
+.. csv-table::
+ :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4
+ :delim: |
+
+ 1 | D6 | D7 | D8 | -
+ 2 | D2 | D3 | D1 | D0
+ 3 | D12 | D11 | D27 | D28
+ 4 | D5 | D9 | D14 | D24
+
+.. _maple-exti-map:
+
+EXTI Line Pin Map
+^^^^^^^^^^^^^^^^^
+
+The following table shows which pins connect to which :ref:`EXTI lines
+<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
+ * - EXTI4
+ - 10, 19
+ * - EXTI5
+ - 4, 13, 20
+ * - EXTI6
+ - 5, 12, 35
+ * - EXTI7
+ - 9, 11, 36
+ * - EXTI8
+ - 6, 14, 37
+ * - EXTI9
+ - 7, 25, 28
+ * - EXTI10
+ - 8, 26, 29
+ * - EXTI11
+ - 30
+ * - EXTI12
+ - 31
+ * - EXTI13
+ - 21, 32
+ * - EXTI14
+ - 22, 33
+ * - EXTI15
+ - 23, 34
+
+.. _maple-usart-map:
+
+USART Pin Map
+^^^^^^^^^^^^^
+
+.. FIXME [0.0.10] UART4, UART5
+
+The Maple has three serial ports (also known as a UARTs or USARTs):
+``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the
+pins summarized in the following table:
+
+.. csv-table::
+ :header: Serial Port, TX, RX, CK, CTS, RTS
+ :delim: |
+
+ ``Serial1`` | 7 | 8 | 6 | - | -
+ ``Serial2`` | 1 | 0 | 10 | 2 | 3
+ ``Serial3`` | 29 | 30 | 31 | 32 | 33
+
+Board-Specific Values
+---------------------
+
+.. TODO [0.0.10]
+
+Stub.
+
Hardware Design Files
---------------------
The hardware schematics and board layout files are available in the
-`Maple github repository <https://github.com/leaflabs/maple>`_. 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
+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 ::
@@ -128,14 +284,14 @@ at the command line with ::
Failure Modes
-------------
-The following known failure modes apply to all Maple versions. The
-failure modes aren't design errors, but are easy ways to break or
-damage your board permanently.
+The following are known failure modes. The failure modes aren't
+design errors, but are easy ways to break or damage your board
+permanently.
* **High voltage on non-tolerant pins**: not all header pins are 5V
compatible; so e.g. connecting certain serial devices in the wrong
- way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table
- <pin-mapping-mega-table>` details which pins are 5V-tolerant.
+ way could over-voltage the pins. The :ref:`pin-mapping master table
+ <maple-pin-map-master>` details which pins are 5V-tolerant.
Errata
------
@@ -145,16 +301,18 @@ Maple board.
Rev 5
^^^^^
-Known issues:
-* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on
- boards sold in during Fall 2010, the corresponding "AIN" is missing
+* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on Rev
+ 5s manufactured during Fall 2010, the corresponding "AIN" is missing
from its silkscreen. This mistake was fixed in later manufacturing
runs.
Rev 3
^^^^^
+* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the
+ corresponding "AIN" is missing from the Rev 3 silkscreen.
+
* **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010
have questionable RESET and BUT buttons.
@@ -231,9 +389,15 @@ Recommended Reading
* STMicro documentation for STM32F103RB microcontroller:
- * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf)
- * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)
- * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference)
+ * `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)
+ * `Programming Manual
+ <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_
+ (PDF; assembly language and register reference)
.. rubric:: Footnotes
diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst
index 15190a8..e3d68c0 100644
--- a/docs/source/i2c.rst
+++ b/docs/source/i2c.rst
@@ -14,10 +14,8 @@ Higher level functionality, such as reading a particular register
value, is achieved by writing to set the memory location then reading
to pull out the data.
-.. FIXME [Maple-specific values]
-
Note that the master/slave designation is on a message-by-message
-basis. The Maple can act as both a master (messages initiated by user
+basis. Maple can act as both a master (messages initiated by user
code) and slave device (responding to requests via configurable
interrupt handlers) at the same time.
@@ -27,15 +25,15 @@ interrupt handlers) at the same time.
Hardware/Circuit Design
-----------------------
-The Maple has two |i2c| ports. Port 1 (I2C1) has SDA on header D9 and
-SCL on D5; Port 2 (I2C2) has SDA on D30 and SCL on D29.
+.. FIXME [0.0.10 add links to board-specific values]
-The Maple reliably communicates with up to a 400kHz clock speed; this
-doesn't translate into a 400kbps data rate except in extreme cases
-because of addressing and protocol overhead. We have tested clock
-speeds up to a megahertz and have had mixed results; in theory it
-could be possible to achieve even higher rates, but signal quality
-degrades rapidly and the bus becomes unreliable.
+Maple boards have two |i2c| ports. Maples reliably communicate with
+up to a 400kHz clock speed; this doesn't translate into a 400kbps data
+rate except in extreme cases because of addressing and protocol
+overhead. We have tested clock speeds up to a megahertz and have had
+mixed results; in theory it could be possible to achieve even higher
+rates, but signal quality degrades rapidly, and the bus becomes
+unreliable.
Proper wiring and pull-up resistor selection are essential when
incorporating |i2c| into a circuit, especially with data rates above
@@ -56,22 +54,16 @@ Wiring-style library is planned for a future release.
SMBus
-----
-The STM32 microcontroller has hardware support for SMBus; we simply
-have not written software for it. The SMBAL line for I2C1 is on header
-D4 and for I2C2 is on D31.
+The STM32 microcontroller has hardware support for SMBus, but software
+for it is not yet implemented.
.. _i2c-recommended-reading:
Recommended Reading
-------------------
-* `i2c-bus.org <http://www.i2c-bus.org/>`_
-* `Wikipedia Article on i2c <http://en.wikipedia.org/wiki/I%C2%B2C>`_
-* `Arduino i2c/TWI reference <http://www.arduino.cc/playground/Learning/I2C>`_
-* 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)
- * `Application Note on Advanced I2C Usage
- <http://www.st.com/stonline/products/literature/an/15021.pdf>`_
- (pdf)
+* `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/index.rst b/docs/source/index.rst
index 9db5ff0..8c7ac84 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,15 +1,12 @@
.. _index:
-Maple Documentation Contents
+LeafLabs Documentation Index
============================
-.. FIXME [Maple-specific values] errata page links to Maple
-
Welcome! This is the Maple documentation index. If you just bought a
-Maple, you probably want to head to the :ref:`quickstart
+Maple board, you probably want to head to the :ref:`quickstart
<maple-quickstart>`. If you're having problems, check out the
-:ref:`troubleshooting <troubleshooting>` :ref:`known problems
-<maple-errata>` pages.
+:ref:`troubleshooting <troubleshooting>` page.
Have fun!
@@ -59,7 +56,7 @@ Have fun!
usb
usart
-.. _index-schematics:
+.. _index-boards:
**Board Hardware Documentation:**
@@ -67,6 +64,7 @@ Have fun!
:maxdepth: 1
hardware/maple.rst
+ hardware/maple-ret6.rst
.. TODO write/include these upon Mini and Native release
diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst
index cc6d34a..4151a53 100644
--- a/docs/source/jtag.rst
+++ b/docs/source/jtag.rst
@@ -6,7 +6,7 @@
JTAG
======
-.. FIXME update adapter schematic, add better information
+.. FIXME [0.1.0] Updated adapter schematic, better information
JTAG is an interface for low-level debugging of digital devices. It
gives instruction by instruction control over the microprocessor and
@@ -63,11 +63,21 @@ functions.
Recommended Reading
-------------------
-* `Wikipedia Article on Joint Test Action Group (JTAG) <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_
-* `STM32, GDB, OpenOCD How To <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_
-* STMicro documentation for STM32F103RB microcontroller:
+* `Wikipedia Article on Joint Test Action Group (JTAG)
+ <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_
- * `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)
-* `LeafLabs Wiki JTAG How To <http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_
-* `Forum thread on JTAG <http://forums.leaflabs.com/topic.php?id=536>`_
+* `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
index 0cc6c23..d9f1ca3 100644
--- a/docs/source/lang/api/abs.rst
+++ b/docs/source/lang/api/abs.rst
@@ -45,5 +45,4 @@ Arduino Compatibility
Maple's implementation of ``abs()`` is compatible with Arduino.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst
index 7099b69..6665a94 100644
--- a/docs/source/lang/api/analogread.rst
+++ b/docs/source/lang/api/analogread.rst
@@ -20,32 +20,33 @@ Library Documentation
Discussion
----------
-Reads the value from the specified analog pin. The Maple board
-contains a 16-channel, 12-bit analog to digital converter. This means
-that it will map input voltages between 0 and 3.3 volts into integer
-values between 0 and 4095. This yields a resolution between readings
-of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors
+Reads the value from the specified analog pin. The Maple boards
+contain 16-channel, 12-bit analog to digital converters. This means
+that a converter will map input voltages between 0 and 3.3 volts into
+integer values between 0 and 4095. However, a number of factors
interfere with getting full accuracy and precision. For more
information, see :ref:`adc`.
Before calling analogRead() on a pin, that pin must first be
-configured for analog input, using :ref:`lang-pinMode` (you only
-have to do this once, so it's usually done in :ref:`lang-setup`\ ).
+configured for analog input, using :ref:`lang-pinMode`. You only have
+to do this once, so it's usually done in :ref:`lang-setup`\ .
Parameter Discussion
--------------------
-.. FIXME generalize Maple-specific information
-
The pin parameter is the number of the analog input pin to read from.
-Header pins on the Maple with ADC functionality (marked as "AIN" on
-the silkscreen) are:
-
- 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28
-
-Note that pins 3, 27, and 28 are not marked AIN on the silkscreen
-for Maple revisions through Rev 5, however, they **do work** as
-analog input pins.
+The pins which support analog to digital conversion have ``AIN``
+listed underneath their number on your board's silkscreen. These pin
+numbers are available to your program in the :ref:`boardADCPins
+<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
----
@@ -55,7 +56,6 @@ returned by ``analogRead()`` will fluctuate due to a number of reasons
(like the values of the other analog inputs, how close your hand is to
the board, etc.) in a "random" way.
-
Example
-------
@@ -78,7 +78,6 @@ Example
// a serial monitor
}
-
Arduino Compatibility
---------------------
@@ -100,27 +99,21 @@ shift <lang-bitshift>` the value of a Maple readout by 2, like so::
// be aware that you're losing a lot of precision if you do this
int adc_reading = analogRead(pin) >> 2;
-.. FIXME Mention Native can do analogReference(), when it's time
+.. FIXME [0.1.0] Mention that Native can do analogReference()
On the Arduino, the input range and resolution can be changed using
-their implementation of `analogReference()
-<http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the
-way its hardware (as of Rev 5) was designed, it's not possible to
-implement analogReference on the Maple, so this function doesn't
-exist. If your inputs lie in a different voltage range than 0V--3.3V,
-you'll need to bring them into that range before using
-``analogRead()``. Some basic tools to accomplish this are `resistor
-dividers <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.
-
-See also
+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:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst
index 9147b96..e789305 100644
--- a/docs/source/lang/api/analogwrite.rst
+++ b/docs/source/lang/api/analogwrite.rst
@@ -65,12 +65,12 @@ This will convert values in the range 0-255 to values in the range
which control PWM output. See the :ref:`timers reference <timers>`
for more information.
-Another fix is to consult the :ref:`pin mapping mega table
-<pin-mapping-mega-table>` to find the timer which controls PWM on the
-pin you're using, then set that Timer's overflow to 255. Subsequent
-calls to analogWrite() should work as on the Arduino (with the same
-loss of precision). Note, however, that that affects the overflow for
-the **entire timer**, so other code relying on that timer (such as any
+Another fix is to consult your board's :ref:`pin maps <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-attachinterrupt>` the timer controls) will
likely need to be modified as well.
@@ -140,9 +140,9 @@ If your application definitely requires Arduino's PWM frequency, then
the steps are:
1. Figure out which :ref:`timer <lang-hardwaretimer>` controls PWM
- output on your pin (\ :ref:`this table <pwm-timer-table>` is your
- friend here). Let's say it's ``Timern``\ , where ``n`` is some
- number 1, 2, 3, or 4.
+ output on your pin (\ :ref:`your board's Timer Pin Map
+ <gpio-pin-maps>` is your friend here). Let's say it's ``Timern``\
+ , where ``n`` is some number 1, 2, 3, or 4.
2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's
period to approximately 2041 microseconds, which is a frequency of
@@ -154,7 +154,7 @@ timer. The important examples are :ref:`timer interrupts
<lang-hardwaretimer-attachinterrupt>` and :ref:`PWM
<timers-pwm-conflicts>`\ .
-See also
+See Also
--------
- :ref:`Maple PWM tutorial <pwm>`
@@ -169,5 +169,4 @@ See also
Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative)
integer with size 2 bytes can hold the values between 0 and 65,535.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst
index 7c5a6c7..39902ac 100644
--- a/docs/source/lang/api/attachinterrupt.rst
+++ b/docs/source/lang/api/attachinterrupt.rst
@@ -5,9 +5,8 @@
attachInterrupt()
=================
-Used to specify a function to call when an external interrupt (like an
-GPIO changing from LOW to HIGH, a button getting pressed, etc.)
-occurs.
+Used to specify a function to call when an :ref:`external interrupt
+<external-interrupts>` occurs.
.. contents:: Contents
:local:
@@ -15,9 +14,9 @@ occurs.
Library Documentation
---------------------
-.. FIXME once breathe knows how to get the correct attachInterupt
-.. (right now it's copying from HardwareTimer), replace with a
-.. doxygenfunction directive
+.. FIXME [doxygenfunction] once Breathe knows how to get the correct
+.. attachInterupt (right now it's copying from HardwareTimer), replace
+.. with a doxygenfunction directive
.. cpp:function:: void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode)
@@ -47,49 +46,29 @@ Discussion
Because the function will run in interrupt context, inside of it,
:ref:`lang-delay` won't work, and the value returned by
-:ref:`lang-millis` will not increment. Serial data received while
-in the function may be lost. You should declare as ``volatile`` any
+:ref:`lang-millis` will not increment. Serial data received while in
+the function may be lost. You should declare as ``volatile`` any
global variables that you modify within the attached function.
-There are a few constraints you should be aware of if you're using
-more than one interrupt at a time; the :ref:`external-interrupts` page
-has the details.
-
-Using Interrupts
-----------------
-
-Interrupts are useful for making things happen automatically in
-microcontroller programs, and can help solve timing problems. A
-good task for using an interrupt might be reading a rotary encoder,
-or monitoring user input.
-
-If you wanted to insure that a program always caught the pulses
-from a rotary encoder, never missing a pulse, it would make it very
-tricky to write a program to do anything else, because the program
-would need to constantly poll the sensor lines for the encoder, in
-order to catch pulses when they occurred. Other sensors have a
-similar interface dynamic too, such as trying to read a sound
-sensor that is trying to catch a click, or an infrared slot sensor
-(photo-interrupter) trying to catch a coin drop. In all of these
-situations, using an interrupt can free the microcontroller to get
-some other work done while not missing the doorbell.
+There are a few limits you should be aware of if you're using more
+than one interrupt at a time; the :ref:`External Interrupts
+<external-interrupts-exti-line>` page has more information.
Example
-------
-::
+ ::
- int maple_led_pin = 13;
volatile int state = LOW; // must declare volatile, since it's
- // modified within the blink handler
+ // modified within the blink() handler
void setup() {
- pinMode(maple_led_pin, OUTPUT);
+ pinMode(BOARD_LED_PIN, OUTPUT);
attachInterrupt(0, blink, CHANGE);
}
void loop() {
- digitalWrite(maple_led_pin, state);
+ digitalWrite(BOARD_LED_PIN, state);
}
void blink() {
@@ -106,10 +85,10 @@ additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5
number goes with which pin -- just tell ``attachInterrupt()`` the pin
you want.
-See also
+See Also
--------
-- :ref:`detachInterrupt <lang-detachinterrupt>`
-- :ref:`external-interrupts`
+- :ref:`lang-detachinterrupt`
+- :ref:`external-interrupts`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bit.rst b/docs/source/lang/api/bit.rst
index dd5c050..3df042c 100644
--- a/docs/source/lang/api/bit.rst
+++ b/docs/source/lang/api/bit.rst
@@ -12,33 +12,27 @@ Syntax
``bit(n)``
-
Parameters
----------
* **n** the bit to set.
-
Value
-----
The value of an integer with the given bit set.
-
Arduino Compatibility
---------------------
-The Maple implementation of bit is compatible with Arduino.
+The Maple implementation of ``bit()`` is compatible with Arduino.
-
-See also
+See Also
--------
-
- :ref:`lang-bitread`
- :ref:`lang-bitwrite`
- :ref:`lang-bitset`
- :ref:`lang-bitclear`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitclear.rst b/docs/source/lang/api/bitclear.rst
index 941f912..f487059 100644
--- a/docs/source/lang/api/bitclear.rst
+++ b/docs/source/lang/api/bitclear.rst
@@ -10,7 +10,6 @@ Syntax
``bitClear(x, n)``
-
Parameters
----------
@@ -19,20 +18,17 @@ Parameters
* **n** which bit to clear, starting at 0 for the least-significant
(rightmost) bit
-
Returns
-------
-None.
-
+Nothing.
Arduino Compatibility
---------------------
-This implementation is compatible with that of Arduino.
+The Maple implementation of ``bitClear()`` is compatible with Arduino.
-
-See also
+See Also
--------
- :ref:`bit <lang-bit>`\ ()
@@ -40,5 +36,4 @@ See also
- :ref:`bitWrite <lang-bitwrite>`\ ()
- :ref:`bitSet <lang-bitset>`\ ()
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitread.rst b/docs/source/lang/api/bitread.rst
index 46b4478..fd9fbbe 100644
--- a/docs/source/lang/api/bitread.rst
+++ b/docs/source/lang/api/bitread.rst
@@ -5,13 +5,11 @@ bitRead()
(Macro) Gets the value of a bit in a number.
-
Syntax
------
``bitRead(x, n)``
-
Parameters
----------
@@ -20,27 +18,22 @@ Parameters
* **n** which bit to read, starting at 0 for the least-significant
(rightmost) bit
-
Value
-----
The value of the bit (0 or 1).
-
Arduino Compatibility
---------------------
The Maple implementation of ``bitRead`` is compatible with Arduino.
-
-See also
+See Also
--------
-
- :ref:`lang-bit`
- :ref:`lang-bitwrite`
- :ref:`lang-bitset`
- :ref:`lang-bitclear`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitset.rst b/docs/source/lang/api/bitset.rst
index ccd76de..83ab5f8 100644
--- a/docs/source/lang/api/bitset.rst
+++ b/docs/source/lang/api/bitset.rst
@@ -5,13 +5,11 @@ bitSet()
(Macro) Sets (writes a 1 to) a bit of a numeric variable.
-
Syntax
------
``bitSet(x, n)``
-
Parameters
----------
@@ -20,19 +18,16 @@ Parameters
* **n** which bit to set, starting at 0 for the least-significant
(rightmost) bit
-
Value
-----
None.
-
Arduino Compatibility
---------------------
The Maple implementation of bitSet is compatible with Arduino.
-
See Also
--------
@@ -41,6 +36,4 @@ See Also
- :ref:`lang-bitwrite`
- :ref:`lang-bitclear`
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/bitwrite.rst b/docs/source/lang/api/bitwrite.rst
index b3feff2..6106545 100644
--- a/docs/source/lang/api/bitwrite.rst
+++ b/docs/source/lang/api/bitwrite.rst
@@ -32,9 +32,9 @@ Nothing.
Arduino Compatibility
---------------------
-Maple's version of ``bitWrite()`` is compatible with Arduino.
+Maple's implementation of ``bitWrite()`` is compatible with Arduino.
-See also
+See Also
--------
- :ref:`bit() <lang-bit>`
@@ -42,5 +42,4 @@ See also
- :ref:`bitSet() <lang-bitSet>`
- :ref:`bitClear() <lang-bitClear>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst
index e274163..05e3837 100644
--- a/docs/source/lang/api/board-values.rst
+++ b/docs/source/lang/api/board-values.rst
@@ -12,6 +12,9 @@ it easier to share your code with other people who have different
boards. Some example usages are given :ref:`below
<lang-board-values-examples>`.
+The actual values for each board are given in the :ref:`Board Hardware
+Documentation <index-boards>`.
+
.. contents:: Contents
:local:
@@ -111,8 +114,6 @@ 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.
-.. TODO [0.1.0] links to board-specific hardware information
-
- ``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
diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst
index c5a7c0c..00c1a5c 100644
--- a/docs/source/lang/api/constants.rst
+++ b/docs/source/lang/api/constants.rst
@@ -320,4 +320,4 @@ See Also
- :ref:`double <lang-double>`
- :ref:`Board-Specific Values <lang-board-values>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/constrain.rst b/docs/source/lang/api/constrain.rst
index d19b61c..28af1e3 100644
--- a/docs/source/lang/api/constrain.rst
+++ b/docs/source/lang/api/constrain.rst
@@ -59,11 +59,10 @@ Arduino Compatibility
Maple's implementation of ``constrain()`` is compatible with Arduino.
-See also
+See Also
--------
- :ref:`min() <lang-min>`
- :ref:`max() <lang-max>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/cos.rst b/docs/source/lang/api/cos.rst
index 3fbb0af..c340f09 100644
--- a/docs/source/lang/api/cos.rst
+++ b/docs/source/lang/api/cos.rst
@@ -19,14 +19,12 @@ 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
+See Also
--------
-
- :ref:`sin() <lang-sin>`
- :ref:`tan() <lang-tan>`
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/delay.rst b/docs/source/lang/api/delay.rst
index 90ca268..9ef06a0 100644
--- a/docs/source/lang/api/delay.rst
+++ b/docs/source/lang/api/delay.rst
@@ -57,10 +57,9 @@ Example
.. _lang-delay-seealso:
-See also
+See Also
--------
-
- :ref:`millis() <lang-millis>`
- :ref:`micros() <lang-micros>`
- :ref:`delayMicroseconds() <lang-delayMicroseconds>`
@@ -68,5 +67,4 @@ See also
<http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ example (works
unmodified on Maple)
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/delaymicroseconds.rst b/docs/source/lang/api/delaymicroseconds.rst
index 24a8286..7078660 100644
--- a/docs/source/lang/api/delaymicroseconds.rst
+++ b/docs/source/lang/api/delaymicroseconds.rst
@@ -48,9 +48,9 @@ Arduino Compatibility
---------------------
While we have made every effort we could to ensure that the timing of
-delayMicroseconds is as accurate as possible, we cannot guarantee it
-will behave as the Arduino implementation down to the microsecond,
-especially for smaller values of ``us``.
+``delayMicroseconds()`` is as accurate as possible, we cannot
+guarantee it will behave as the Arduino implementation down to the
+microsecond, especially for smaller values of ``us``.
See Also
--------
@@ -59,7 +59,4 @@ See Also
- :ref:`micros <lang-micros>`
- :ref:`delay <lang-delay>`
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/detachinterrupt.rst b/docs/source/lang/api/detachinterrupt.rst
index 41642a7..82ce974 100644
--- a/docs/source/lang/api/detachinterrupt.rst
+++ b/docs/source/lang/api/detachinterrupt.rst
@@ -9,9 +9,8 @@ Used to disable an interrupt specified with
Library Documentation
---------------------
-.. FIXME once breathe knows how to get the correct detachInterupt
-.. (right now it's copying from HardwareTimer), replace with a
-.. doxygenfunction directive
+.. FIXME [Breathe] once we can get the correct detachInterupt(),
+.. replace with doxygenfunction.
.. cpp:function:: void detachInterrupt(uint8 pin)
@@ -39,5 +38,6 @@ See Also
--------
- :ref:`attachInterrupt() <lang-attachInterrupt>`
+- :ref:`external-interrupts`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/digitalread.rst b/docs/source/lang/api/digitalread.rst
index 3502587..ccf4a4c 100644
--- a/docs/source/lang/api/digitalread.rst
+++ b/docs/source/lang/api/digitalread.rst
@@ -8,51 +8,44 @@ 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 when the button is pressed::
-
- int ledPin = 13; // LED connected to Maple pin 13
- int buttonPin = 38; // BUT connected to Maple pin 38
+The following example turns the LED on or off when the button is pressed::
void setup() {
- pinMode(ledPin, OUTPUT);
- pinMode(buttonPin, INPUT);
+ pinMode(BOARD_LED_PIN, OUTPUT);
+ pinMode(BOARD_BUTTON_PIN, INPUT);
}
void loop() {
- int val = digitalRead(buttonPin); // reads the input pin
- digitalWrite(ledPin, val);
+ int val = digitalRead(BOARD_BUTTON_PIN); // reads the input pin
+ togglePin(BOARD_LED_PIN, val);
}
-Note
-----
-
-If the pin isn't connected to anything, ``digitalRead()`` can return
-either HIGH or LOW (and this can change in a way that seems random).
-
Arduino Compatibility
---------------------
The Maple version of ``digitalRead()`` is compatible with Arduino.
-
See Also
--------
-- :ref:`pinMode <lang-pinMode>`
-- :ref:`digitalWrite <lang-digitalWrite>`
-
-
-
-
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
+- :ref:`lang-isButtonPressed`
+- :ref:`lang-pinmode`
+- :ref:`lang-digitalWrite`
+- :ref:`lang-togglepin`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/digitalwrite.rst b/docs/source/lang/api/digitalwrite.rst
index 6124d5f..376cbc3 100644
--- a/docs/source/lang/api/digitalwrite.rst
+++ b/docs/source/lang/api/digitalwrite.rst
@@ -21,42 +21,26 @@ 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``.
-.. TODO make the following paragraphs true, but refer the reader to
-.. INPUT_PULLUP and INPUT_PULLDOWN:
-
-If the pin is configured as an ``INPUT``, writing a ``HIGH`` value
-with ``digitalWrite()`` will enable an internal pullup resistor.
-Writing ``LOW`` will disable the pullup. The pullup resistor is enough
-to light an LED dimly, so if LEDs appear to work, but very dimly, this
-is a likely cause. The remedy is to set the pin to an output with the
-:ref:`pinMode() <lang-pinmode>` function.
-
-.. note:: Pin 13 is harder to use as an input than the other pins
- because it has an LED and resistor soldered to it in series. If you
- enable its internal pull-up resistor, it will likely hang at around
- 1.1V instead of the expected 3.3V because the onboard LED and
- series resistor pull the voltage level down. If you must use pin 13
- as a digital input, use an external pull-down resistor.
+Because it is soldered to an LED and resistor in series, your board's
+:ref:`BOARD_LED_PIN <lang-board-values-led>` will respond slightly
+more slowly as an output than the other pins.
Example
-------
The following example sets pin 13 to ``HIGH``, makes a one-second-long
delay, sets the pin back to ``LOW``, and delays again, causing a
-blinking pattern::
-
-
- int ledPin = 13; // LED connected to digital pin 13
+blinking pattern (you could also use :ref:`lang-toggleled`)::
void setup() {
- pinMode(ledPin, OUTPUT); // sets the digital pin as output
+ pinMode(BOARD_LED_PIN, OUTPUT); // sets the digital pin as output
}
void loop() {
- digitalWrite(ledPin, HIGH); // sets the LED on
- delay(1000); // waits for a second
- digitalWrite(ledPin, LOW); // sets the LED off
- delay(1000); // waits for a second
+ digitalWrite(BOARD_LED_PIN, HIGH); // sets the LED on
+ delay(1000); // waits for a second
+ digitalWrite(BOARD_LED_PIN, LOW); // sets the LED off
+ delay(1000); // waits for a second
}
See Also
@@ -64,5 +48,8 @@ See Also
- :ref:`pinMode <lang-pinmode>`
- :ref:`digitalRead <lang-digitalread>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
+- :ref:`lang-toggleled`
+- :ref:`lang-togglepin`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst
index 3f086ca..526beb6 100644
--- a/docs/source/lang/api/hardwaretimer.rst
+++ b/docs/source/lang/api/hardwaretimer.rst
@@ -10,8 +10,7 @@ built-in timer peripherals. More information on these peripherals
(including code examples) is available in the :ref:`timers reference
<timers>`.
-.. FIXME update HardwareTimer documentation after redoing it in terms
-.. of the new timer interface.
+.. FIXME [0.0.10] Updated HardwareTimer documentation, with deprecation
.. warning:: This class has been deprecated. It is not available in
the current build.
@@ -27,8 +26,7 @@ documented below on one of the predefined ``HardwareTimer`` instances.
For example, to set the prescale factor on timer 1 to 5, call
``Timer1.setPrescaleFactor(5)``.
-.. TODO add code examples that people can copy and paste in case
-.. they're unfamiliar with namespace syntax
+.. TODO add tutorial-style examples
.. cpp:class:: HardwareTimer
@@ -92,9 +90,8 @@ For example, to set the prescale factor on timer 1 to 5, call
Set the given channel of this timer to the given :ref:`mode
<lang-hardwaretimer-modes>`. The parameter ``channel`` is one of
1, 2, 3, and 4, and corresponds to the compare channel you would
- like to set. Refer to the full :ref:`pin mapping table
- <pin-mapping-mega-table>` to match up timer channels and pin
- numbers.
+ like to set. Refer to your board's :ref:`master pin map
+ <gpio-pin-maps>` to match up timer channels and pin numbers.
.. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode)
@@ -377,3 +374,87 @@ different.
Other Functions
^^^^^^^^^^^^^^^
.. doxygenfunction:: getTimer
+
+Examples
+^^^^^^^^
+
+**LED blink**::
+
+ #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles
+
+ void handler_led(void);
+
+ void setup()
+ {
+ // Set up the LED to blink
+ pinMode(BOARD_LED_PIN, OUTPUT);
+
+ // Setup Timer
+ Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE);
+ Timer2.setPeriod(LED_RATE); // in microseconds
+ Timer2.setCompare1(1); // overflow might be small
+ Timer2.attachCompare1Interrupt(handler_led);
+ }
+
+ void loop() {
+ // Nothing! It's all in the interrupts
+ }
+
+ void handler_led(void) {
+ toggleLED();
+ }
+
+**Racing Counters**::
+
+ void handler_count1(void);
+ void handler_count2(void);
+
+ int count1 = 0;
+ int count2 = 0;
+
+ void setup()
+ {
+ // Set up BUT for input
+ pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP);
+
+ // Setup Counting Timers
+ Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE);
+ Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE);
+ Timer3.pause();
+ Timer4.pause();
+ Timer3.setCount(0);
+ Timer4.setCount(0);
+ Timer3.setOverflow(30000);
+ Timer4.setOverflow(30000);
+ Timer3.setCompare1(1000); // somewhere in the middle
+ Timer4.setCompare1(1000);
+ Timer3.attachCompare1Interrupt(handler1);
+ Timer4.attachCompare1Interrupt(handler2);
+ Timer3.resume();
+ Timer4.resume();
+ }
+
+ void loop() {
+ // Display the running counts
+ SerialUSB.print("Count 1: ");
+ SerialUSB.print(count1);
+ SerialUSB.print("\t\tCount 2: ");
+ SerialUSB.println(count2);
+
+ // Run... while BUT is held, pause Count2
+ for(int i = 0; i<1000; i++) {
+ if(digitalRead(BOARD_BUTTON_PIN)) {
+ Timer4.pause();
+ } else {
+ Timer4.resume();
+ }
+ delay(1);
+ }
+ }
+
+ void handler1(void) {
+ count1++;
+ }
+ void handler2(void) {
+ count2++;
+ }
diff --git a/docs/source/lang/api/highbyte.rst b/docs/source/lang/api/highbyte.rst
index 50a1fa6..4cb6f9b 100644
--- a/docs/source/lang/api/highbyte.rst
+++ b/docs/source/lang/api/highbyte.rst
@@ -52,8 +52,4 @@ See Also
- :ref:`lowByte() <lang-lowbyte>`
-
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/loop.rst b/docs/source/lang/api/loop.rst
index d8f6183..c2a5097 100644
--- a/docs/source/lang/api/loop.rst
+++ b/docs/source/lang/api/loop.rst
@@ -15,7 +15,6 @@ Example
::
-
int buttonPin = 38;
// setup initializes serial and the button pin
@@ -42,4 +41,4 @@ See Also
- :ref:`setup() <lang-setup>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/lowbyte.rst b/docs/source/lang/api/lowbyte.rst
index 58e622f..c513711 100644
--- a/docs/source/lang/api/lowbyte.rst
+++ b/docs/source/lang/api/lowbyte.rst
@@ -22,4 +22,4 @@ Returns
The low byte's value (this will be between 0 and 255).
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/map.rst b/docs/source/lang/api/map.rst
index 79122b3..69661a0 100644
--- a/docs/source/lang/api/map.rst
+++ b/docs/source/lang/api/map.rst
@@ -65,4 +65,4 @@ See Also
- :ref:`constrain() <lang-constrain>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/max.rst b/docs/source/lang/api/max.rst
index d38eebe..d356f08 100644
--- a/docs/source/lang/api/max.rst
+++ b/docs/source/lang/api/max.rst
@@ -53,7 +53,7 @@ functions inside the parentheses. It may lead to incorrect results::
Arduino Compatibility
---------------------
-The Maple version of ``max()`` is compatible with Arduino.
+The Maple implementation of ``max()`` is compatible with Arduino.
See Also
--------
@@ -61,5 +61,4 @@ See Also
- :ref:`min() <lang-min>`
- :ref:`constrain() <lang-constrain>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/micros.rst b/docs/source/lang/api/micros.rst
index f12976b..de85303 100644
--- a/docs/source/lang/api/micros.rst
+++ b/docs/source/lang/api/micros.rst
@@ -43,4 +43,4 @@ See Also
- :ref:`delay() <lang-delay>`
- :ref:`delayMicroseconds() <lang-delaymicroseconds>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/millis.rst b/docs/source/lang/api/millis.rst
index 0288c56..db0531c 100644
--- a/docs/source/lang/api/millis.rst
+++ b/docs/source/lang/api/millis.rst
@@ -49,4 +49,4 @@ See Also
- :ref:`delay <lang-delay>`
- :ref:`delayMicroseconds <lang-delaymicroseconds>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/min.rst b/docs/source/lang/api/min.rst
index 1245f6f..3307105 100644
--- a/docs/source/lang/api/min.rst
+++ b/docs/source/lang/api/min.rst
@@ -62,5 +62,4 @@ See Also
- :ref:`max() <lang-max>`
- :ref:`constrain() <lang-constrain>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/pinmode.rst b/docs/source/lang/api/pinmode.rst
index 03cbcfa..8cee3e5 100644
--- a/docs/source/lang/api/pinmode.rst
+++ b/docs/source/lang/api/pinmode.rst
@@ -60,13 +60,13 @@ set up a pin for these purposes before a call to, e.g.,
:ref:`lang-analogRead`. In practice, this should only add a few lines
to your :ref:`lang-setup` function.
-.. TODO verify following before putting it in:
+.. TODO [0.1.0] verify following before putting it in:
.. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and
.. ``PWM_OPEN_DRAIN`` modes represent functionality not currently
.. available on Arduino boards.
-See also
+See Also
--------
- :ref:`lang-constants`
@@ -74,6 +74,4 @@ See also
- :ref:`lang-digitalread`
- Maple :ref:`GPIO <gpio>` reference page
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/pow.rst b/docs/source/lang/api/pow.rst
index 4280400..219a866 100644
--- a/docs/source/lang/api/pow.rst
+++ b/docs/source/lang/api/pow.rst
@@ -10,8 +10,6 @@ Library Documentation
.. doxygenfunction:: pow
-.. TODO LATER some examples
-
See Also
--------
@@ -19,5 +17,4 @@ See Also
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst
index cea602b..5cc112e 100644
--- a/docs/source/lang/api/pwmwrite.rst
+++ b/docs/source/lang/api/pwmwrite.rst
@@ -11,10 +11,13 @@ pwmWrite(), the pin will output a steady square wave with the given
duty cycle. You can change the duty cycle later by calling pwmWrite()
again with the same pin and a different duty.
-.. FIXME board-specific information
-
-On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8,
-9, 11, 12, 14, 24, 27, and 28.
+The pins which support PWM have ``PWM`` listed underneath their number
+on your board's silkscreen. These pin numbers are available to your
+program in the :ref:`boardPWMPins <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
@@ -54,4 +57,5 @@ potentiometer::
See Also
--------
-- :ref:`Maple PWM tutorial <pwm>`
+- :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
index dd8871d..9875ee6 100644
--- a/docs/source/lang/api/random.rst
+++ b/docs/source/lang/api/random.rst
@@ -10,9 +10,7 @@ The ``random()`` function generates pseudo-random numbers.
Library Documentation
---------------------
-.. FIXME keep tracking Sphinx/Breathe's ability to reference
-.. overloaded functions so we can use doxygenfunction instead of
-.. manually documenting.
+.. FIXME [Breathe] use doxygenfunction when possible
.. cpp:function:: random(long max)
@@ -70,4 +68,4 @@ See Also
- :ref:`randomSeed() <lang-randomseed>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/randomseed.rst b/docs/source/lang/api/randomseed.rst
index d0a15b7..ca7b75f 100644
--- a/docs/source/lang/api/randomseed.rst
+++ b/docs/source/lang/api/randomseed.rst
@@ -57,4 +57,4 @@ See Also
- :ref:`random() <lang-random>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/serial.rst b/docs/source/lang/api/serial.rst
index 417063d..0821f43 100644
--- a/docs/source/lang/api/serial.rst
+++ b/docs/source/lang/api/serial.rst
@@ -12,49 +12,20 @@ devices.
Introduction
------------
-.. FIXME [Maple-specific values]
-.. FIXME [0.0.10] Serial4, Serial5 updates for high-density devices
+.. FIXME [0.0.10] UART4, UART5
-The Maple has three serial ports (also known as a UARTs or USARTs):
-``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the
-pins summarized in the following table:
-
-.. list-table::
- :header-rows: 1
-
- * - Serial port
- - TX, RX, CK
- - CTS, RTS (if present)
-
- * - ``Serial1``
- - 7, 8, 6
- -
-
- * - ``Serial2``
- - 1, 0, 10
- - 2, 3
-
- * - ``Serial3``
- - 29, 30, 31
- - 32, 33
-
-Thus, if you use a particular serial port, you cannot also use its
-communication pins for other purposes at the same time.
-
-If you want to communicate with the Maple using the provided USB port,
-use :ref:`SerialUSB <lang-serialusb>` instead.
-
-To use them to communicate with an external TTL serial device, connect
-the TX pin to your device's RX pin, the RX to your device's TX pin,
-and the ground of your Maple to your device's ground.
+To use a serial port to communicate with an external serial device,
+connect the TX pin to your device's RX pin, the RX to your device's TX
+pin, and your Maple board's ground to your device's ground.
.. warning:: Don't connect these pins directly to an RS232 serial
port; they operate at +/- 12V and can damage your board.
-
Library Documentation
---------------------
+.. FIXME [0.1.0] Tutorial-style usage introduction
+
All of the ``Serial[1,2,3]`` objects are instances of the
``HardwareSerial`` class, which is documented in this section. (This
means that you can use any of these functions on any of ``Serial1``,
@@ -209,9 +180,10 @@ Arduino Compatibility Note
--------------------------
Unlike the Arduino, none of the Maple's serial ports is connected to
-the USB port on the Maple board (for that, use :ref:`SerialUSB
-<lang-serialusb>`). Thus, to use these pins to communicate with your
-personal computer, you will need an additional USB-to-serial adapter.
+the USB port on the Maple board. If you want to communicate using the
+built-in USB port, use :ref:`SerialUSB <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
@@ -226,4 +198,4 @@ personal computer, you will need an additional USB-to-serial adapter.
.. - `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_
.. - `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/setup.rst b/docs/source/lang/api/setup.rst
index 837ddd6..1e8e3b8 100644
--- a/docs/source/lang/api/setup.rst
+++ b/docs/source/lang/api/setup.rst
@@ -26,4 +26,4 @@ Example
// ...
}
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/sin.rst b/docs/source/lang/api/sin.rst
index 398b8f3..3e28c0b 100644
--- a/docs/source/lang/api/sin.rst
+++ b/docs/source/lang/api/sin.rst
@@ -28,5 +28,4 @@ See Also
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/sq.rst b/docs/source/lang/api/sq.rst
index bd32648..96724d3 100644
--- a/docs/source/lang/api/sq.rst
+++ b/docs/source/lang/api/sq.rst
@@ -42,5 +42,4 @@ Arduino Compatibility
Maple's implementation of ``sq()`` is compatible with Arduino.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/tan.rst b/docs/source/lang/api/tan.rst
index 4bbe0db..b1aed31 100644
--- a/docs/source/lang/api/tan.rst
+++ b/docs/source/lang/api/tan.rst
@@ -22,10 +22,9 @@ Note that the Maple implementation comes from `newlib
See Also
--------
-
- :ref:`sin <lang-sin>`
- :ref:`cos <lang-cos>`
- :ref:`float <lang-float>`
- :ref:`double <lang-double>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/api/volatile.rst b/docs/source/lang/api/volatile.rst
index 276bb6a..1b72897 100644
--- a/docs/source/lang/api/volatile.rst
+++ b/docs/source/lang/api/volatile.rst
@@ -24,8 +24,8 @@ for efficiency).
A variable should be declared ``volatile`` whenever its value can be
changed by something beyond the control of the code section in which
it appears, such as an :ref:`external interrupt
-<external-interrupts>`. On the Maple, the only place that this is
-likely to occur is in sections of code associated with interrupts.
+<external-interrupts>`. (The only place that this is likely to occur
+in most programs is inside of code called by interrupts).
Example
-------
@@ -55,11 +55,11 @@ Example
}
}
-See also
+See Also
--------
- :ref:`External Interrupts <external-interrupts>`
- :ref:`lang-attachinterrupt`
- :ref:`lang-detachinterrupt`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cc-attribution.txt b/docs/source/lang/cc-attribution.txt
index e100140..11302b2 100644
--- a/docs/source/lang/cc-attribution.txt
+++ b/docs/source/lang/cc-attribution.txt
@@ -3,7 +3,8 @@
.. 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/>`_.
+ 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
index 26e2811..cef3954 100644
--- a/docs/source/lang/cpp/arithmetic.rst
+++ b/docs/source/lang/cpp/arithmetic.rst
@@ -121,4 +121,4 @@ See Also
- :ref:`sizeof <lang-sizeof>`\ ()
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/array.rst b/docs/source/lang/cpp/array.rst
index 30a818f..39d4d91 100644
--- a/docs/source/lang/cpp/array.rst
+++ b/docs/source/lang/cpp/array.rst
@@ -113,11 +113,9 @@ Arduino Compatibility
Arrays on Maple are identical those on Arduino.
-See also
+See Also
--------
- :ref:`Storing arrays in FLASH memory <arm-gcc-attribute-flash>`
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/assignment.rst b/docs/source/lang/cpp/assignment.rst
index f9430b4..6379298 100644
--- a/docs/source/lang/cpp/assignment.rst
+++ b/docs/source/lang/cpp/assignment.rst
@@ -57,4 +57,4 @@ See Also
<http://icu-project.org/docs/papers/cpp_report/the_anatomy_of_the_assignment_operator.html>`_
for more information.
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/bitshift.rst b/docs/source/lang/cpp/bitshift.rst
index e1c8de0..47413f2 100644
--- a/docs/source/lang/cpp/bitshift.rst
+++ b/docs/source/lang/cpp/bitshift.rst
@@ -140,5 +140,4 @@ See Also
- :ref:`lang-bitwrite`
- :ref:`lang-bitclear`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/bitwisemath.rst b/docs/source/lang/cpp/bitwisemath.rst
index 28fe6bf..59794ba 100644
--- a/docs/source/lang/cpp/bitwisemath.rst
+++ b/docs/source/lang/cpp/bitwisemath.rst
@@ -182,5 +182,4 @@ See Also
- :ref:`Compound bitwise operations <lang-compoundbitwise>` (``&=``,
``|=``, ``^=``).
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/boolean.rst b/docs/source/lang/cpp/boolean.rst
index 8d6aa5c..f09345e 100644
--- a/docs/source/lang/cpp/boolean.rst
+++ b/docs/source/lang/cpp/boolean.rst
@@ -87,5 +87,4 @@ See Also
``|=``, ``^=``).
- :ref:`if statement <lang-if>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/booleanvariables.rst b/docs/source/lang/cpp/booleanvariables.rst
index 6051b8c..0d76a12 100644
--- a/docs/source/lang/cpp/booleanvariables.rst
+++ b/docs/source/lang/cpp/booleanvariables.rst
@@ -42,13 +42,11 @@ Example
}
}
-See also
+See Also
--------
-
- :ref:`Boolean constants <lang-constants-bool>`
- :ref:`Boolean operators <lang-boolean>`
- :ref:`Variables <lang-variables>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/break.rst b/docs/source/lang/cpp/break.rst
index ce8ac17..f367b99 100644
--- a/docs/source/lang/cpp/break.rst
+++ b/docs/source/lang/cpp/break.rst
@@ -29,7 +29,4 @@ Example
delay(50);
}
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/byte.rst b/docs/source/lang/cpp/byte.rst
index 45c9d5f..4634594 100644
--- a/docs/source/lang/cpp/byte.rst
+++ b/docs/source/lang/cpp/byte.rst
@@ -30,5 +30,4 @@ See Also
- :ref:`byte() <lang-bytecast>` (casting a value to a byte)
- :ref:`Variables <lang-variables>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/bytecast.rst b/docs/source/lang/cpp/bytecast.rst
index b3f0de2..24c3b9e 100644
--- a/docs/source/lang/cpp/bytecast.rst
+++ b/docs/source/lang/cpp/bytecast.rst
@@ -24,13 +24,11 @@ Syntax
``byte(x)``
-
Parameters
----------
**x**: a value of any integer type
-
Returns
-------
@@ -38,13 +36,9 @@ The value, converted to a ``byte``. Note, however, that if the value
is larger than the maximum value you can store in a byte (255), then
the results might be strange and unexpected.
-
See Also
--------
- :ref:`lang-byte`
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/char.rst b/docs/source/lang/cpp/char.rst
index b8747f3..686c0d1 100644
--- a/docs/source/lang/cpp/char.rst
+++ b/docs/source/lang/cpp/char.rst
@@ -10,7 +10,6 @@ value from -128 to 127). Character literals are written in single
quotes, like this: ``'A'`` (for multiple characters - strings - use
double quotes: ``"ABC"``).
-
Just like everything else on a computer, characters are stored as
numbers. You can see the specific encoding in the `ASCII chart
<http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters>`_\
@@ -25,26 +24,21 @@ The ``char`` datatype is a signed type, meaning that it encodes
numbers from -128 to 127. For an unsigned type, which stores values
from 0 to 255, just use the type ``unsigned char`` (two words).
-
Example
-------
::
- // the following two lines are equivalent, using the ASCII
+ // The following two lines are equivalent, using the ASCII
// character encoding:
char c = 'A';
char c = 65;
-
-See also
+See Also
--------
-
- :ref:`lang-int`
- :ref:`lang-array` (a string is just an array of ``char``\ s)
- :ref:`Serial.println() <lang-serial-println>`
-
-
.. include:: cc-attribution.txt
diff --git a/docs/source/lang/cpp/charcast.rst b/docs/source/lang/cpp/charcast.rst
index a480dec..640ad85 100644
--- a/docs/source/lang/cpp/charcast.rst
+++ b/docs/source/lang/cpp/charcast.rst
@@ -12,13 +12,11 @@ Syntax
``char(x)``
-
Parameters
----------
**x**: a value of any type
-
Returns
-------
@@ -26,11 +24,9 @@ The value, converted to a ``char``. Note, however, that if the value
is outside the range of a ``char`` (-128 to 127), then the results
might be strange and unexpected.
-
See Also
--------
- :ref:`char <lang-char>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/comments.rst b/docs/source/lang/cpp/comments.rst
index c5f118a..1428dc3 100644
--- a/docs/source/lang/cpp/comments.rst
+++ b/docs/source/lang/cpp/comments.rst
@@ -61,7 +61,4 @@ just ignores them. This can be especially useful when trying to locate
a problem, or when a program refuses to compile and the compiler error
is cryptic or unhelpful.
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/comparison.rst b/docs/source/lang/cpp/comparison.rst
index b24355f..9cd0a9f 100644
--- a/docs/source/lang/cpp/comparison.rst
+++ b/docs/source/lang/cpp/comparison.rst
@@ -83,5 +83,4 @@ Comparison operators, along with :ref:`boolean operators
appears within a conditional doesn't mean it's automatically wrong.
Be careful to know what you mean.)
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/compoundarithmetic.rst b/docs/source/lang/cpp/compoundarithmetic.rst
index 420f1db..d70a43c 100644
--- a/docs/source/lang/cpp/compoundarithmetic.rst
+++ b/docs/source/lang/cpp/compoundarithmetic.rst
@@ -40,5 +40,4 @@ See Also
- :ref:`Arithmetic operators <lang-arithmetic>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/compoundbitwise.rst b/docs/source/lang/cpp/compoundbitwise.rst
index 8231130..4efe5df 100644
--- a/docs/source/lang/cpp/compoundbitwise.rst
+++ b/docs/source/lang/cpp/compoundbitwise.rst
@@ -226,5 +226,4 @@ 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
index 52de85f..ad0c580 100644
--- a/docs/source/lang/cpp/const.rst
+++ b/docs/source/lang/cpp/const.rst
@@ -21,7 +21,7 @@ method for defining constants than ``#define``.
Example
-------
-::
+ ::
// this defines a variable called "pi", which cannot be changed:
const float pi = 3.14;
@@ -33,7 +33,6 @@ Example
pi = 7; // illegal - you can't write to (modify) a constant
-
**#define** or **const**
------------------------
@@ -48,5 +47,4 @@ See Also
- :ref:`#define <lang-define>`
- :ref:`volatile <lang-volatile>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/continue.rst b/docs/source/lang/cpp/continue.rst
index 13d1815..2a694f6 100644
--- a/docs/source/lang/cpp/continue.rst
+++ b/docs/source/lang/cpp/continue.rst
@@ -27,6 +27,4 @@ Example
delay(50);
}
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/curly-braces.rst b/docs/source/lang/cpp/curly-braces.rst
index a4bd3dc..df2fe2a 100644
--- a/docs/source/lang/cpp/curly-braces.rst
+++ b/docs/source/lang/cpp/curly-braces.rst
@@ -99,11 +99,8 @@ reference page for more information)::
.. rubric:: Footnotes
-.. TODO remove this once IDE 0.1.0 released
-
.. [#fbug] At present this feature is slightly buggy as the IDE will
often find (incorrectly) a brace in text that has been commented
out.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/define.rst b/docs/source/lang/cpp/define.rst
index 677390d..bdf7283 100644
--- a/docs/source/lang/cpp/define.rst
+++ b/docs/source/lang/cpp/define.rst
@@ -13,7 +13,6 @@ defined value at compile time.
This can have some unwanted side effects. In general, the :ref:`const
<lang-const>` keyword is preferred for defining constants.
-
Syntax
------
@@ -42,7 +41,7 @@ is, **don't do this, either**::
Example
-------
-::
+ ::
#define LED_PIN 13
// The compiler will replace any mention of LED_PIN with
@@ -52,5 +51,4 @@ See Also
--------
- :ref:`const <lang-const>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/double.rst b/docs/source/lang/cpp/double.rst
index 1527778..59422eb 100644
--- a/docs/source/lang/cpp/double.rst
+++ b/docs/source/lang/cpp/double.rst
@@ -43,6 +43,4 @@ See Also
- :ref:`float <lang-float>`
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/doublecast.rst b/docs/source/lang/cpp/doublecast.rst
index 16a9907..d3f32ce 100644
--- a/docs/source/lang/cpp/doublecast.rst
+++ b/docs/source/lang/cpp/doublecast.rst
@@ -24,4 +24,4 @@ See Also
- :ref:`float <lang-float>`
- :ref:`float() <lang-floatcast>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/dowhile.rst b/docs/source/lang/cpp/dowhile.rst
index fe92226..d229122 100644
--- a/docs/source/lang/cpp/dowhile.rst
+++ b/docs/source/lang/cpp/dowhile.rst
@@ -23,5 +23,4 @@ Example::
x = readSensors(); // check the sensors
} while (x < 100);
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/float.rst b/docs/source/lang/cpp/float.rst
index 6937c8c..5195fac 100644
--- a/docs/source/lang/cpp/float.rst
+++ b/docs/source/lang/cpp/float.rst
@@ -47,4 +47,4 @@ See Also
- :ref:`double <lang-double>`
- :ref:`Variables <lang-variables>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/floatcast.rst b/docs/source/lang/cpp/floatcast.rst
index 4766478..af92543 100644
--- a/docs/source/lang/cpp/floatcast.rst
+++ b/docs/source/lang/cpp/floatcast.rst
@@ -25,4 +25,4 @@ See Also
- :ref:`double <lang-double>`
- :ref:`double() <lang-doublecast>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/for.rst b/docs/source/lang/cpp/for.rst
index 71c5aca..78ea562 100644
--- a/docs/source/lang/cpp/for.rst
+++ b/docs/source/lang/cpp/for.rst
@@ -123,7 +123,7 @@ questions (answers are in footnote [#fanswers]_\ ):
2. Why does it stop at 64?
-See also
+See Also
--------
- :ref:`while <lang-while>` loops
@@ -139,4 +139,4 @@ See also
false, and the loop stops.
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/goto.rst b/docs/source/lang/cpp/goto.rst
index ff2f248..2c0b3b0 100644
--- a/docs/source/lang/cpp/goto.rst
+++ b/docs/source/lang/cpp/goto.rst
@@ -126,5 +126,4 @@ See Also
- Knuth, Donald. `Structured Programming with go to Statements <http://pplab.snu.ac.kr/courses/adv_pl05/papers/p261-knuth.pdf>`_ (PDF)
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/if.rst b/docs/source/lang/cpp/if.rst
index bef89e2..d57b9f1 100644
--- a/docs/source/lang/cpp/if.rst
+++ b/docs/source/lang/cpp/if.rst
@@ -118,4 +118,4 @@ See Also
- :ref:`boolean operators <lang-boolean>`
- :ref:`comparison operators <lang-comparison>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/include.rst b/docs/source/lang/cpp/include.rst
index 74fe7af..163509d 100644
--- a/docs/source/lang/cpp/include.rst
+++ b/docs/source/lang/cpp/include.rst
@@ -67,6 +67,4 @@ root <http://en.wikipedia.org/wiki/Cube_root>`_ of a number::
SerialUSB.println(cubeRootOf3);
}
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/increment.rst b/docs/source/lang/cpp/increment.rst
index 6dffa80..c423d1a 100644
--- a/docs/source/lang/cpp/increment.rst
+++ b/docs/source/lang/cpp/increment.rst
@@ -34,4 +34,4 @@ See Also
- :ref:`lang-compoundarithmetic`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/intcast.rst b/docs/source/lang/cpp/intcast.rst
index 386fe14..da838c7 100644
--- a/docs/source/lang/cpp/intcast.rst
+++ b/docs/source/lang/cpp/intcast.rst
@@ -23,7 +23,4 @@ See Also
- :ref:`int <lang-int>`
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/longcast.rst b/docs/source/lang/cpp/longcast.rst
index f588fc6..493ad67 100644
--- a/docs/source/lang/cpp/longcast.rst
+++ b/docs/source/lang/cpp/longcast.rst
@@ -24,4 +24,4 @@ See Also
- :ref:`long <lang-long>`
- :ref:`long long <lang-longlong>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/longlong.rst b/docs/source/lang/cpp/longlong.rst
index 0ba56ed..d942cb4 100644
--- a/docs/source/lang/cpp/longlong.rst
+++ b/docs/source/lang/cpp/longlong.rst
@@ -53,4 +53,4 @@ See Also
- :ref:`Integer Constants <lang-constants-integers>`
- :ref:`Variables <lang-variables>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/modulo.rst b/docs/source/lang/cpp/modulo.rst
index 289fba0..013d07e 100644
--- a/docs/source/lang/cpp/modulo.rst
+++ b/docs/source/lang/cpp/modulo.rst
@@ -67,4 +67,4 @@ See Also
- :ref:`Arithmetic <lang-arithmetic>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/pointer.rst b/docs/source/lang/cpp/pointer.rst
index 0a42270..ff4ec32 100644
--- a/docs/source/lang/cpp/pointer.rst
+++ b/docs/source/lang/cpp/pointer.rst
@@ -28,4 +28,4 @@ See Also
- http://xkcd.com/138/
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/return.rst b/docs/source/lang/cpp/return.rst
index b4ef5fd..d9aecbe 100644
--- a/docs/source/lang/cpp/return.rst
+++ b/docs/source/lang/cpp/return.rst
@@ -57,5 +57,4 @@ See Also
- :ref:`comments <lang-comments>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/scope.rst b/docs/source/lang/cpp/scope.rst
index 7b65bab..a270428 100644
--- a/docs/source/lang/cpp/scope.rst
+++ b/docs/source/lang/cpp/scope.rst
@@ -117,4 +117,4 @@ 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:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/semicolon.rst b/docs/source/lang/cpp/semicolon.rst
index 8164616..05e6218 100644
--- a/docs/source/lang/cpp/semicolon.rst
+++ b/docs/source/lang/cpp/semicolon.rst
@@ -19,7 +19,4 @@ compiler error comes up, one of the first things to check is a
missing semicolon, in the immediate vicinity, preceding the line at
which the compiler complained.
-
-
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/sizeof.rst b/docs/source/lang/cpp/sizeof.rst
index eae509c..ec2dea6 100644
--- a/docs/source/lang/cpp/sizeof.rst
+++ b/docs/source/lang/cpp/sizeof.rst
@@ -60,5 +60,5 @@ would look something like this::
standard guarantees, however, is that a ``char`` occupies at
*least* 8 bits.
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/sqrt.rst b/docs/source/lang/cpp/sqrt.rst
index 956a754..fbabf82 100644
--- a/docs/source/lang/cpp/sqrt.rst
+++ b/docs/source/lang/cpp/sqrt.rst
@@ -21,5 +21,4 @@ See Also
- :ref:`pow <lang-pow>`
- :ref:`sq <lang-sq>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/static.rst b/docs/source/lang/cpp/static.rst
index 5d1802e..8c52ba0 100644
--- a/docs/source/lang/cpp/static.rst
+++ b/docs/source/lang/cpp/static.rst
@@ -53,5 +53,4 @@ then incremented, so it starts out at one. Subsequent calls to
it was declared ``static``. Thus, ``numSensorReadings`` is a count of
the number of times that ``readSensors()`` has been called.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/string.rst b/docs/source/lang/cpp/string.rst
index 0a270da..84917c1 100644
--- a/docs/source/lang/cpp/string.rst
+++ b/docs/source/lang/cpp/string.rst
@@ -124,5 +124,4 @@ See Also
- :ref:`__attribute__ <arm-gcc-attribute-flash>`
- :ref:`Variables <lang-variables>`
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/switchcase.rst b/docs/source/lang/cpp/switchcase.rst
index b484bc5..e31ccf3 100644
--- a/docs/source/lang/cpp/switchcase.rst
+++ b/docs/source/lang/cpp/switchcase.rst
@@ -110,9 +110,9 @@ value as the variable to compare. In this case, you can write down
all of the values the ``enum`` takes as ``case`` statements, and be
sure you've covered all the possibilities.
-See also:
+See Also:
---------
- :ref:`if/else <lang-if>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/unsignedchar.rst b/docs/source/lang/cpp/unsignedchar.rst
index 5b946ed..45fedeb 100644
--- a/docs/source/lang/cpp/unsignedchar.rst
+++ b/docs/source/lang/cpp/unsignedchar.rst
@@ -16,18 +16,17 @@ won't store negative numbers; it is also subject to the same
Example
-------
-::
+ ::
unsigned char c = 240;
See Also
--------
-
- :ref:`byte <lang-byte>`
- :ref:`int <lang-int>`
- :ref:`array <lang-array>`
- :ref:`SerialUSB.println() <lang-serialusb-println>`
- :ref:`Serial.println() <lang-serial-println>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/unsignedint.rst b/docs/source/lang/cpp/unsignedint.rst
index ad3e2f2..b7d9716 100644
--- a/docs/source/lang/cpp/unsignedint.rst
+++ b/docs/source/lang/cpp/unsignedint.rst
@@ -56,4 +56,4 @@ See Also
- :ref:`Integer Constants <lang-constants-integers>`
- :ref:`Variables <lang-variables>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/unsignedlonglong.rst b/docs/source/lang/cpp/unsignedlonglong.rst
index 910b7e4..a1143f0 100644
--- a/docs/source/lang/cpp/unsignedlonglong.rst
+++ b/docs/source/lang/cpp/unsignedlonglong.rst
@@ -40,4 +40,4 @@ See Also
- :ref:`Integer Constants <lang-constants-integers>`
- :ref:`Variables <lang-variables>`
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst
index 336d5ab..9ffdd1d 100644
--- a/docs/source/lang/cpp/variables.rst
+++ b/docs/source/lang/cpp/variables.rst
@@ -165,6 +165,5 @@ See Also
(usually) stored
<http://en.wikipedia.org/wiki/Two%27s_complement>`_ on computers.
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/void.rst b/docs/source/lang/cpp/void.rst
index 88c9c64..7af0acd 100644
--- a/docs/source/lang/cpp/void.rst
+++ b/docs/source/lang/cpp/void.rst
@@ -28,6 +28,4 @@ Example
// ...
}
-.. TODO doc page on function declaration?
-
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/cpp/while.rst b/docs/source/lang/cpp/while.rst
index 9047d05..e66e0aa 100644
--- a/docs/source/lang/cpp/while.rst
+++ b/docs/source/lang/cpp/while.rst
@@ -35,4 +35,4 @@ Example
var++;
}
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/lang/unimplemented/notone.rst b/docs/source/lang/unimplemented/notone.rst
index 485c9c5..8af878b 100644
--- a/docs/source/lang/unimplemented/notone.rst
+++ b/docs/source/lang/unimplemented/notone.rst
@@ -10,41 +10,28 @@ 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
-
-
+Nothing.
-See also
+See Also
--------
-
- `tone <http://arduino.cc/en/Reference/Tone>`_ ()
-
-
.. include:: /lang/cc-attribution.txt
diff --git a/docs/source/lang/unimplemented/tone.rst b/docs/source/lang/unimplemented/tone.rst
index f83bf6b..13d581e 100644
--- a/docs/source/lang/unimplemented/tone.rst
+++ b/docs/source/lang/unimplemented/tone.rst
@@ -12,70 +12,47 @@ 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
+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:: /lang/cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt
diff --git a/docs/source/language-index.rst b/docs/source/language-index.rst
index a064b3e..225a9ae 100644
--- a/docs/source/language-index.rst
+++ b/docs/source/language-index.rst
@@ -10,8 +10,21 @@ API references for documented libmaple functionality. The "C++ for
Maple" pages are intended as a minimal reference/refresher for
programmers familiar with the Arduino language.
-**Looking for something else?** The low-level :ref:`libmaple library
-interfaces <libmaple>` are documented separately.
+.. admonition:: **Looking for Something Else?**
+
+ - See the :ref:`libraries` for extra built-in libraries for dealing
+ with different kinds of hardware.
+
+ - If you're looking for something from the C standard library (like
+ ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler
+ <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>`.
.. _index-language-index-cpp:
.. _index-language-index-api:
diff --git a/docs/source/language.rst b/docs/source/language.rst
index 111a1f1..3ecbe43 100644
--- a/docs/source/language.rst
+++ b/docs/source/language.rst
@@ -10,8 +10,7 @@ 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 Wiring tutorial -- just describe setup()/loop(), then link to
-.. some of the the bajillion external tutorials
+.. TODO [0.2.0?] Wiring tutorial
C or C++ programmers curious about the differences between the Wiring
language and C++ may wish to skip to the
@@ -20,31 +19,29 @@ language and C++ may wish to skip to the
.. contents:: Contents
:local:
-.. _language-lang-docs:
-
-Maple Language Reference
-------------------------
+.. admonition:: **Looking for Something Else?**
-The following table summarizes the available core language features.
-A more exhaustive index is available at the :ref:`language-index`.
+ - See the :ref:`libraries` for extra built-in libraries for dealing
+ with different kinds of hardware.
-.. FIXME mention Maple Native supports malloc(), free(), operator
-.. new(), and operator delete(), when that is a true thing to say.
+ - If you're looking for something from the C standard library (like
+ ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler
+ <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.
-**Looking for something else?**
+ - If you're looking for pointers to low-level details, see this page's
+ :ref:`Recommended Reading <language-recommended-reading>`.
-- See the :ref:`libraries` for extra built-in libraries for dealing
- with different kinds of hardware.
+.. _language-lang-docs:
-- If you're looking for something from the C standard library (like
- ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler
- <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.
+Maple Language Reference
+------------------------
-- If you're looking for low-level details, see the :ref:`libmaple
- <libmaple>` reference page.
+The following table summarizes the most important core language
+features. An exhaustive index is available at the
+:ref:`language-index`.
+--------------------------------------------+----------------------------------------------+---------------------------------------------------+
| Structure | Variables | Functions |
@@ -458,14 +455,26 @@ Which could plausibly be turned into the final source file ::
while (true) loop();
}
+.. _language-recommended-reading:
+
Recommended Reading
-------------------
-* `newlib Documentation <http://sourceware.org/newlib/>`_
-
* :ref:`libmaple Documentation <libmaple>`
-
-* ST documentation:
-
- * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf)
- * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference)
+* 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/api/systick.rst b/docs/source/libmaple/api/systick.rst
index 5ec906c..a02b8e4 100644
--- a/docs/source/libmaple/api/systick.rst
+++ b/docs/source/libmaple/api/systick.rst
@@ -1,6 +1,14 @@
.. highlight:: c
+
+
.. _libmaple-systick:
+.. FIXME [0.0.10] move these to the right places:
+
+.. _libmaple-systick_disable:
+
+.. _libmaple-systick_resume:
+
``systick.h``
=============
diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst
index 7623963..2bc8b11 100644
--- a/docs/source/libraries.rst
+++ b/docs/source/libraries.rst
@@ -10,13 +10,13 @@
.. Note: if you port an Arduino library and document it here, be sure
.. to update compatibility.rst to reflect that fact.
-This page briefly summarizes the Arduino libraries that have been
-ported to Maple. You can use a library from within a sketch by going
-to Sketch > Import Library... from within the IDE, then choosing the
-library you want.
+This page lists the extra libraries that are part of the :ref:`Maple
+IDE <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 are noted
-in the description of the library.
+Any incompatibilities between the Maple and Arduino versions of a
+library are noted in the library's documentation.
.. contents:: Contents
:local:
@@ -25,70 +25,47 @@ in the description of the library.
:hidden:
libs/servo.rst
+ libs/wire.rst
-.. _libraries-servo:
-
-Servo
------
-
-The Servo library is provided for convenient control of RC
-servomotors. For more information, see the :ref:`Servo <libs-servo>`
-reference.
+.. admonition:: **Looking for Something Else?**
-**Compatibility Note**
+ - See the :ref:`language` for information on the core functions
+ used for programming a Maple board.
-The Servo class provides a public interface identical to the Arduino
-version's documented functionality (as of Arduino 0021), so in most
-cases, this library will be a drop-in replacement.
+ - If you're looking for something from the C standard library (like
+ ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler
+ <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.
-However, there are some differences, essentially at the level of
-implementation details.
+ - If you're looking for low-level hardware support libraries, see
+ the :ref:`libmaple Reference`.
-The major difference is that while the Arduino implementation drives
-the servos with "bit-banged" :ref:`PWM <pwm>`, the Maple
-implementation uses :ref:`timers <timers>` to drive the PWM directly.
-
-Consequently, **the Maple implementation only allows Servo instances
-to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**.
-
-To determine if a pin supports PWM (15 Maple pins do), you can either
-check if "PWM" appears next to its number on the Maple silkscreen, or
-consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation.
-
-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]_.
+.. _libraries-servo:
-Because of this, we recommend connecting multiple servomotors to pins
-which share a timer, in order to keep as many timers free for other
-purposes as possible. Consult the :ref:`table provided in the timers
-reference <timers-pin-channel-map>` to match up pins and timer
-channels.
+Servo
+-----
-Another difference: 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 true on success, and
-false on failure (and this is its documented behavior).
+The :ref:`Servo <libs-servo>` library is provided for convenient
+control of RC servomotors.
.. _libraries-liquid-crystal:
LiquidCrystal
-------------
-.. TODO 0.0.10 make our own LiquidCrystal docs
+.. TODO [0.1.0] LiquidCrystal docs under libs/liquidcrystal.rst
The LiquidCrystal library allows Maple to control LCD screens. For
more information, see the `Arduino LiquidCrystal documentation
<http://www.arduino.cc/en/Reference/LiquidCrystal>`_.
-**Compatibility Note**
+**Arduino Compatibility**
At this time, no incompatibilities between the Maple and Arduino
-versions are known. Any observed differences should be considered
+versions are known (although the Maple version should perform
+significantly faster). Any observed differences should be considered
bugs, and reported on the forums.
.. _libraries-wire:
@@ -96,99 +73,8 @@ bugs, and reported on the forums.
Wire
----
-We provide a soft (bit-banged) implementation of the `Wire I2C library
-<http://arduino.cc/en/Reference/WireBegin>`_.
-
-**Compatibility Note**
-
-This implementation is synchronous, and thus supports only a subset of
-the full Wire interface (however, the functionality which is supported
-is fully compatible with Arduino). For now, please use the function
-reference which follows when developing projects using our
-implementation.
-
-Please note that the current implementation only supports master mode
-using a bit-banged (software) protocol. Future enhancements will use
-the hardware i2c peripheral on the stm32 as well as the DMA for
-performance. Support for slave, smBUS, and multimaster modes are also
-slated for inclusion in the enhanced Wire port.
-
-.. TODO 0.0.10 Wire docs in the cpp domain in own page under /libs/
-
-Wire Function Reference
-^^^^^^^^^^^^^^^^^^^^^^^
-
-``Wire.begin()``
- Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL
- (this is compatible with the pin settings on the Arduino Mega).
-
-``Wire.begin(sda, scl)``
- Like ``Wire.begin()``, but with the given pins as SDA and
- SCL.
-
-``Wire.beginTransmission(slave_address)``
- Set up a transmission to a slave device with the given (7-bit)
- address. Bytes subsequently queued for transmission (using
- ``Wire.send``) will be sent to ``slave_address`` when ``void
- Wire.endTransmission()`` is called.
-
-``void Wire.send(byte)``
- Queues the given byte (``uint8`` or ``int``) to the slave address
- previously specified by a call to ``Wire.beginTransmission``. At
- most 32 bytes may be queued in a single transmission.
-
-``Wire.send(string)``
- Queues a given string (``char*``) for transmission. The characters
- of the string are individually queued for transmission as
- bytes. At most 32 bytes may be queued in a single transmission.
-
-``Wire.send(buffer, length)``
- Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with
- ``length`` elements, for transmission. At most 32 bytes may be
- queued in a single transmission.
-
-``Wire.endTransmission()``
- Ends a transmission (begun by ``Wire.beginTransmission(uint8)``),
- and actually sends the bytes queued by calls to Wire.send.
-
- The return value is one of the following status codes:
-
- * ``SUCCESS``: All bytes were transmitted successfully.
-
- * ``EDATA``: More than 32 bytes were queued for transmission. No
- bytes are actually sent when this happens.
-
- * ``ENACKADDR``: Did not receive ACK on transmit of address. No
- bytes are actually sent when this happens.
-
- * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some
- bytes may have been sent when this happens; however, the
- transmission is aborted after the first byte of data which is
- not ACKed by the slave device.
-
- * ``EOTHER``: Other error occurred.
-
-``Wire.requestFrom(address, num_bytes)``
- Requests ``num_bytes`` bytes from 7-bit slave address
- address. Returns the actual number of bytes read. These bytes may
- subsequently be read one at a time using ``Wire.receive()``.
-
- Note: if ``num_bytes`` exceeds the size of the transmit/receive
- buffer (currently 32), it will be truncated to 32.
-
-``Wire.receive()``
- Get and return the next byte read during the previous call to
- ``Wire.requestFrom(uint8, int)``. You can check how many bytes are
- left to read using ``uint8 Wire.available()``.
-
-``Wire.available()``
- Returns the number of bytes which are still available for reading
- (with ``Wire.receive()``) from the last call to
- ``Wire.requestFrom(uint8, int)``.
-
-.. rubric:: Footnotes
+.. FIXME [0.1.0] Update with hard Wire implementation info
-.. [#fard-servo] The Arduino implementation also captures timer
- channels in groups as more Servo objects are attached, but the
- details of which channels have their periods reset when are
- slightly different.
+We currently provide a soft (bit-banged) implementation of the
+:ref:`Wire <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
index 475f7dd..891f151 100644
--- a/docs/source/libs/servo.rst
+++ b/docs/source/libs/servo.rst
@@ -2,9 +2,8 @@
.. _libs-servo:
-=======
- Servo
-=======
+Servo
+=====
.. FIXME [0.0.10] this is out of date
@@ -16,7 +15,8 @@ You can use this library in the :ref:`IDE <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 ``$LIB_MAPLE_HOME/libraries/Servo/``.
+library is located in the ``/libraries/Servo/`` :ref:`libmaple`
+directory.
Servo Class Reference
---------------------
@@ -108,3 +108,54 @@ servomotor attached to pin 9, you could write ::
microseconds. This will be clamped to lie in the [``min``,
``max``\ ] pulse width range set during :ref:`attach()
<libs-servo-attach>`.
+
+Arduino Compatibility
+---------------------
+
+The Servo class provides a public interface identical to the Arduino
+version's documented functionality (as of Arduino 0021), so in most
+cases, this library will be a drop-in replacement.
+
+However, there are some differences, essentially at the level of
+implementation details.
+
+The major difference is that while the Arduino implementation drives
+the servos with "bit-banged" :ref:`PWM <pwm>`, the Maple
+implementation uses :ref:`timers <timers>` to drive the PWM directly.
+
+Consequently, **the Maple implementation only allows Servo instances
+to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**.
+
+To determine if a pin supports PWM (15 Maple pins do), you can either
+check if "PWM" appears next to its number on the Maple silkscreen, or
+consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation.
+
+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.
+
+Another difference: 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).
+
+We currently provide a soft (bit-banged) implementation of the
+:ref:`Wire <libs-wire>` I2C library.
+
+.. rubric:: Footnotes
+
+.. [#fard-servo] The Arduino implementation also captures timer
+ channels in groups as more Servo objects are attached, but the
+ details of which channels have their periods reset when are
+ slightly different.
diff --git a/docs/source/libs/wire.rst b/docs/source/libs/wire.rst
new file mode 100644
index 0000000..2c5bed9
--- /dev/null
+++ b/docs/source/libs/wire.rst
@@ -0,0 +1,104 @@
+.. highlight:: cpp
+
+.. _libs-wire:
+
+Wire
+====
+
+.. TODO [0.1.0] Format this correctly, using Breathe
+
+This page documents the Wire library for the :ref:`i2c` protocol. You
+can use this library in the :ref:`Maple IDE <ide>` by choosing the
+Wire item under the Sketch > Import Library... menu.
+
+If you are using the :ref:`Unix toolchain <unix-toolchain>`, the
+library is located in the ``/libraries/Wire/`` :ref:`libmaple`
+directory.
+
+Wire Function Reference
+-----------------------
+
+``Wire.begin()``
+ Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL
+ (this is compatible with the pin settings on the Arduino Mega).
+
+``Wire.begin(sda, scl)``
+ Like ``Wire.begin()``, but with the given pins as SDA and
+ SCL.
+
+``Wire.beginTransmission(slave_address)``
+ Set up a transmission to a slave device with the given (7-bit)
+ address. Bytes subsequently queued for transmission (using
+ ``Wire.send``) will be sent to ``slave_address`` when ``void
+ Wire.endTransmission()`` is called.
+
+``void Wire.send(byte)``
+ Queues the given byte (``uint8`` or ``int``) to the slave address
+ previously specified by a call to ``Wire.beginTransmission``. At
+ most 32 bytes may be queued in a single transmission.
+
+``Wire.send(string)``
+ Queues a given string (``char*``) for transmission. The characters
+ of the string are individually queued for transmission as
+ bytes. At most 32 bytes may be queued in a single transmission.
+
+``Wire.send(buffer, length)``
+ Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with
+ ``length`` elements, for transmission. At most 32 bytes may be
+ queued in a single transmission.
+
+``Wire.endTransmission()``
+ Ends a transmission (begun by ``Wire.beginTransmission(uint8)``),
+ and actually sends the bytes queued by calls to Wire.send.
+
+ The return value is one of the following status codes:
+
+ * ``SUCCESS``: All bytes were transmitted successfully.
+
+ * ``EDATA``: More than 32 bytes were queued for transmission. No
+ bytes are actually sent when this happens.
+
+ * ``ENACKADDR``: Did not receive ACK on transmit of address. No
+ bytes are actually sent when this happens.
+
+ * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some
+ bytes may have been sent when this happens; however, the
+ transmission is aborted after the first byte of data which is
+ not ACKed by the slave device.
+
+ * ``EOTHER``: Other error occurred.
+
+``Wire.requestFrom(address, num_bytes)``
+ Requests ``num_bytes`` bytes from 7-bit slave address
+ address. Returns the actual number of bytes read. These bytes may
+ subsequently be read one at a time using ``Wire.receive()``.
+
+ Note: if ``num_bytes`` exceeds the size of the transmit/receive
+ buffer (currently 32), it will be truncated to 32.
+
+``Wire.receive()``
+ Get and return the next byte read during the previous call to
+ ``Wire.requestFrom(uint8, int)``. You can check how many bytes are
+ left to read using ``uint8 Wire.available()``.
+
+``Wire.available()``
+ Returns the number of bytes which are still available for reading
+ (with ``Wire.receive()``) from the last call to
+ ``Wire.requestFrom(uint8, int)``.
+
+Arduino Compatibility
+---------------------
+
+.. FIXME [0.1.0] Replace this section when i2c Wire wrapper is done
+
+This implementation is synchronous, and thus supports only a subset of
+the full Wire interface (however, the functionality which is supported
+is fully compatible with Arduino). For now, please use the function
+reference which follows when developing projects using our
+implementation.
+
+Please note that the current implementation only supports master mode
+using a bit-banged (software) protocol. For now, use of the hardware
+:ref:`i2c` peripheral is only available through :ref:`libmaple-i2c`.
+
+
diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst
index 899f720..c7596ce 100644
--- a/docs/source/maple-quickstart.rst
+++ b/docs/source/maple-quickstart.rst
@@ -6,7 +6,7 @@
Maple Quickstart Guide
========================
-.. TODO update the images since we changed "to FLASH" -> "to Flash"
+.. TODO [0.1.0] Update the images; we've changed "to FLASH" -> "to Flash"
You'll need a `Maple board <http://leaflabs.com/store/>`_, a `Mini-B
USB cable <http://www.google.com/products?q=mini-b+usb+cable>`_, a
@@ -73,12 +73,14 @@ window, and then a confirmation message will appear:
Upload that program!
--------------------
+.. FIXME [0.1.0 Maple-specific image; add one for Native]
+
Now it's time to plug in your Maple. Use a Mini-B cable, making sure
-that the :ref:`power source jumper <hardware-maple-powering>` is on
-the USB header first. We ship the Maple with the power source jumper
-configured that way, so you shouldn't have to do anything. For
-reference, it should look like this (don't worry if a jumper is
-hanging half off of the CHRG header):
+that the :ref:`power source jumper <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
diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst
index 1144d55..ac67689 100644
--- a/docs/source/pwm.rst
+++ b/docs/source/pwm.rst
@@ -19,29 +19,14 @@ filtering) generate audio waveforms.
Overview
--------
-The Maple has a large number of 16-bit PWM outputs, each connected to
-one of 4 timers. Some configuration, such as the clock rate or
-prescaling, must be common to the entire timer; see the :ref:`timer
-documentation <timers>` for more information.
-
-Note that unlike the Arduino, the Maple does not have PWM
-functionality on pin D10; all other pins are :ref:`compatible
-<arduino-compatibility>`.
-
-The following table shows which timer can generate which PWM
-outputs. See the :ref:`pin mapping table <pin-mapping-mega-table>` to
-track down exactly which timer *channel* corresponds to each pin.
-
-.. _pwm-timer-table:
-
-.. csv-table::
- :header: Timer, PWM Headers
- :delim: |
-
- Timer1 | D6,D7,D8
- Timer2 | D0,D1,D2,D3
- Timer3 | D11,D12,D27,D28
- Timer4 | D5,D9,D14,D24
+.. FIXME [0.1.0] More information about how timer channels drive PWM
+
+Each PWM output is driven by an output channel connected to one of 4
+timers. Some configuration, such as the clock rate or prescaling,
+must be common to the entire timer; see the :ref:`timer documentation
+<timers>` for more information. See your board's :ref:`pin mapping
+tables <gpio-pin-mapping-tables>` to track down the correspondence
+between timer channels and GPIO pins.
Background
----------
diff --git a/docs/source/spi.rst b/docs/source/spi.rst
index ba43eef..2da4bf8 100644
--- a/docs/source/spi.rst
+++ b/docs/source/spi.rst
@@ -20,11 +20,15 @@ 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
-* 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)
+* 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/timers.rst b/docs/source/timers.rst
index 56dd686..cb30081 100644
--- a/docs/source/timers.rst
+++ b/docs/source/timers.rst
@@ -5,6 +5,8 @@
Timers
======
+.. FIXME [0.0.10] links to systick.h in a few places on this page
+
There are four general purpose timers in the Maple microcontroller
that can be configured to generate periodic or delayed events with
minimal work done by the microcontroller. For example, the :ref:`PWM
@@ -43,164 +45,66 @@ event" interrupt is generated. You can configure the Maple to notify
you when this takes place, by registering an interrupt handler, which
is a function that will be called when the update event occurs.
-libmaple Reference
+Function Reference
------------------
-The libmaple API for interacting with timers is documented at the
-:ref:`HardwareTimer reference <lang-hardwaretimer>`.
+* :ref:`HardwareTimer <lang-hardwaretimer>`
Caveats
-------
+Working with timers and interrupts can be tricky; they are a somewhat
+"advanced" topic. The following subsections explain some common
+problems associated with using timers and timer interrupts.
+
+In general: start simple, test with :ref:`ASSERT() <language-assert>`,
+and don't try to do too much in your interrupt handlers! Make sure
+that what you're trying to do in a handler isn't going to block other
+interrupts from firing, if those other interrupts are important for
+your program.
+
.. _timers-pwm-conflicts:
-**PWM Conflicts:** Because PWM functionality on a given pin depends on
+PWM Conflicts
+^^^^^^^^^^^^^
+
+Because PWM functionality on a given pin depends on
the configuration of the timer and channel, you must chose your
channels carefully if you want to use both timer interrupts and PWM in
-the same program. Refer to the following table to match up timer
-channels and Maple header pin numbers:
-
-.. _timers-pin-channel-map:
-
-.. csv-table::
- :header: Timer, Ch. 1 pin, Ch. 2 pin, Ch. 3 pin, Ch. 4 pin
-
- ``Timer1``, 6, 7, 8, --
- ``Timer2``, 2, 3, 1, 0
- ``Timer3``, 12, 11, 27, 28
- ``Timer4``, 5, 9, 14, 24
-
-**Overhead:** there is some overhead associated with function and
-interrupt calls (loading and unloading the stack, preparing state,
-etc.) and this overhead can fudge your timing. Imperfect code
-branching also means that, e.g., channel 1 interrupts may get called a
-couple clock cycles sooner than a channel 4 interrupt, all other
-configuration being the same.
-
-.. compound::
-
- **Jitter:** other interrupts (USB, Serial, SysTick, or other
- timers) can and will get called before or during the timer
- interrupt routines, causing pseudorandom delays and other
- frustrations.
-
- Disabling the USB port (by calling ``SerialUSB.end()``, or just
- running off a battery) helps a lot, but then you lose the
- auto-reset and communications functionality. This will require
- that you put your Maple into :ref:`perpetual bootloader mode
- <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>`).
-
- Disabling SysTick with ``systick_disable()`` helps as well.
- However, calling this function will break the ``micros()`` and
- ``millis()`` functions.
-
-**General:** working with timers and interrupts can be tricky and hard
-to debug; they are a somewhat "advanced" topic. Start simple, test
-with :ref:`ASSERT() <language-assert>`, and don't try to do too much
-in your interrupt handlers! Make sure that what you're trying to do in
-a handler isn't going to block other interrupts from firing (e.g. USB,
-Serial, SysTick) if those other interrupts are important for your
-program.
-
-SysTick Peripheral
-------------------
-
-The SysTick peripheral allows another, simple way to perform periodic
-or delayed events. This separate timer does not conflict with any
-other peripherals, but the associated 1kHz interrupt can jitter the
-general purpose timer interrupts; this is clearly seen when running
-VGA code, where the timing jitters are transformed into visual jags in
-the image. The SysTick peripheral can be disabled by calling
-``systick_disable()``, and re-enabled using ``systick_resume()``.
-
-Code Examples
--------------
-
-LED blink
-^^^^^^^^^
-
-::
-
- #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles
-
- void handler_led(void);
-
- void setup()
- {
- // Set up the LED to blink
- pinMode(BOARD_LED_PIN, OUTPUT);
-
- // Setup Timer
- Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE);
- Timer2.setPeriod(LED_RATE); // in microseconds
- Timer2.setCompare1(1); // overflow might be small
- Timer2.attachCompare1Interrupt(handler_led);
- }
-
- void loop() {
- // Nothing! It's all in the interrupts
- }
-
- void handler_led(void) {
- toggleLED();
- }
-
-Racing Counters
-^^^^^^^^^^^^^^^
-
-::
-
- void handler_count1(void);
- void handler_count2(void);
-
- int count1 = 0;
- int count2 = 0;
-
- void setup()
- {
- // Set up BUT for input
- pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP);
-
- // Setup Counting Timers
- Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE);
- Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE);
- Timer3.pause();
- Timer4.pause();
- Timer3.setCount(0);
- Timer4.setCount(0);
- Timer3.setOverflow(30000);
- Timer4.setOverflow(30000);
- Timer3.setCompare1(1000); // somewhere in the middle
- Timer4.setCompare1(1000);
- Timer3.attachCompare1Interrupt(handler1);
- Timer4.attachCompare1Interrupt(handler2);
- Timer3.resume();
- Timer4.resume();
- }
-
- void loop() {
- // Display the running counts
- SerialUSB.print("Count 1: ");
- SerialUSB.print(count1);
- SerialUSB.print("\t\tCount 2: ");
- SerialUSB.println(count2);
-
- // Run... while BUT is held, pause Count2
- for(int i = 0; i<1000; i++) {
- if(digitalRead(BOARD_BUTTON_PIN)) {
- Timer4.pause();
- } else {
- Timer4.resume();
- }
- delay(1);
- }
- }
-
- void handler1(void) {
- count1++;
- }
- void handler2(void) {
- count2++;
- }
+the same program. Refer to your board's :ref:`Timer Pin Map
+<gpio-pin-maps>` to match up timer channels and pin numbers.
+
+Overhead
+^^^^^^^^
+
+There is some overhead associated with function and interrupt calls
+(loading and unloading the stack, preparing state, etc.) and this
+overhead can fudge your timing. Imperfect code branching also means
+that, e.g., channel 1 interrupts may get called a couple clock cycles
+sooner than a channel 4 interrupt, all other configuration being the
+same.
+
+Jitter
+^^^^^^
+
+Other interrupts can and will get called before or during the timer
+interrupt routines, causing pseudorandom delays and other
+frustrations.
+
+Disabling the :ref:`USB <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 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
index 2151171..f49580c 100644
--- a/docs/source/troubleshooting.rst
+++ b/docs/source/troubleshooting.rst
@@ -100,8 +100,6 @@ a board selected. The work-around is to restart the IDE. Mysterious!
A classic! Make sure you have selected a board from the pulldown menu.
-.. TODO: remove when Python version is released
-
``undefined reference to setup()/loop()``
-----------------------------------------
@@ -133,8 +131,6 @@ There is an intermittent bug with the temporary directory build system
that on occasion will lose many of the ``#include``\ d libmaple
files. If you recompile everything, it should be fine.
-.. TODO remove when the Python version is released
-
.. _troubleshooting-upload:
========================
diff --git a/docs/source/usart.rst b/docs/source/usart.rst
index 3beb3fc..9506cc8 100644
--- a/docs/source/usart.rst
+++ b/docs/source/usart.rst
@@ -4,23 +4,34 @@
USART
=======
-.. contents::
+.. contents:: Contents
:local:
Hardware/Circuit Design
-----------------------
+.. FIXME [0.0.10] UART4 and UART5
+.. FIXME [0.1.0] Maple Native and Mini info and links
+
The Maple has 3 separate USART devices. In the most simple use case,
the RX and TX pins are used to send data at a predetermined baudrate
with the line voltage level relative to ground. Their usage is
documented in the :ref:`Serial Ports <lang-serial>` language reference
-page.
+page. Which pins correspond to the USART TX and RX pins are given on
+your board's silkscreen, and also in the board-specific USART pin maps
+available here:
+
+* :ref:`Maple <maple-usart-map>`
+* :ref:`Maple RET6 Edition <maple-ret6-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 Maple USART ports with an FT232R-based
-USB-serial converter at up to 115200 baud; higher speeds should
+We have successfully used the USART ports with an FT232R-based
+USB-serial converter at up to 115200 baud. Higher speeds should
certainly be possible.
Recommended Reading
diff --git a/docs/source/usb.rst b/docs/source/usb.rst
index f040034..a67d710 100644
--- a/docs/source/usb.rst
+++ b/docs/source/usb.rst
@@ -2,34 +2,32 @@
.. _usb:
-=====
- USB
-=====
+USB
+===
-The Maple STM32 microprocessor includes a dedicated USB peripheral
-which can be configured to act as a general USB slave device with
-transfer rates up to 12Mbps (it unfortunately can't be configured as a
-host or on-the-go device). By default, the peripheral is configured
-for two uses: first, to receive sketch/program uploads from the IDE,
-and second, to emulate a regular serial port for use as a terminal
-(text read/write).
+The STM32 microprocessors include a dedicated USB peripheral which can
+be configured to act as a general USB slave device with transfer rates
+up to 12Mbps. (It unfortunately can't be configured as a host or
+on-the-go device). By default, the peripheral is configured for two
+uses: first, to receive sketch/program uploads from the :ref:`IDE
+<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 as part of the auto-reset feature of the
-IDE to program the board on Maple Rev 3 and Rev 5: a :ref:`magic
-sequence of control line toggles and transmitted data
-<bootloader-rev3>` causes the Maple to reset itself and enter
-bootloader mode. As an unfortunate consequence, the auto-reset will
-not work if the IDE can not access the serial port, either due to a
-conflict with another program (serial monitor) or because the
-interface has been disabled from the Maple side (through
-:ref:`SerialUSB.end() <lang-serialusb-end>`). A solution to the
-second problem is the use of :ref:`perpetual bootloader mode
-<troubleshooting-perpetual-bootloader>`.
+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
-------------------
@@ -40,9 +38,11 @@ Recommended Reading
* `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>`_
-* 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)
- * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (pdf; assembly
- language and register reference)
+* 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)