Finalized 0.0.9 documentation.

20 files changed, 789 insertions, 199 deletions

diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst
index c614aca..35c6fbc 100644
--- a/docs/source/lang/api/analogread.rst
+++ b/docs/source/lang/api/analogread.rst
@@ -32,11 +32,6 @@ Before calling analogRead() on a pin, that pin must first be
 configured for analog input, using :ref:`lang-pinMode` (you only
 have to do this once, so it's usually done in :ref:`lang-setup`\ ).
 
-It takes about 0.8 microseconds (.0000008 seconds) to read an analog
-input, so the maximum sample rate using this function is approximately
-1.3 million samples per second\ [#fsamp]_.
-
-
 Parameter Discussion
 --------------------
 
@@ -115,40 +110,10 @@ Some basic tools to accomplish this are `resistor dividers
 . However, opamps and other powered components can also be used if
 greater precision is required.
 
-Finally, On the Arduino, it takes significantly longer to read analog
-input: about 100 microseconds (0.0001 s), so the maximum reading rate
-is 10,000 times a second.
-
-
 See also
 --------
 
 - :ref:`ADC note <adc>`
 - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
 
-
-.. rubric:: Footnotes
-
-.. [#fsamp] This is based on the current configuration of a 55.5 cycle
-   sample time, at 72 MHz. However, the minimum sample time *possible*
-   is 1.5 cycles, leading to a theoretical maximum of approximately 48
-   million samples per second (of course, doing anything with the
-   readings also consumes cycles, so this maximum can't be reached in
-   practice).
-
-   See the `STM32 Reference Manual <full-manual>`_, §§11.12.4--5
-   (pp. 225--226), for more information on the low-level bit twiddling
-   currently necessary to change the sample time.  For examples of how
-   the ADCs are configured in libmaple, see `adc.h
-   <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.h>`_
-   and `adc.c
-   <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.c>`_\
-   .  Be aware that changing the sample time has important
-   consequences related to the impedance of the device connected to
-   the input pin.  If you want to make changes, as a minimum, you
-   should first read ST's application notes on `ADC modes
-   <stm32-adc-modes>`_ and `ADC oversampling
-   <stm32-adc-oversampling>`_.
-
-
 .. include:: cc-attribution.txt
diff --git a/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst
index 01820ef..9147b96 100644
--- a/docs/source/lang/api/analogwrite.rst
+++ b/docs/source/lang/api/analogwrite.rst
@@ -11,19 +11,18 @@ analogWrite()
 .. note::
 
    On the Maple, calling analogWrite() is the same as calling
-   :ref:`lang-pwmwrite`\ ; see that function's documentation for more
-   information.
+   :ref:`lang-pwmwrite`\ ; we recommend using that function directly
+   instead.
 
    This is because PWM is not true analog output (i.e., is not the
    output of a `DAC
    <http://en.wikipedia.org/wiki/Digital-to-analog_converter>`_\ ), so
-   the function is badly named.  For instance, **analogWrite() has
+   the function is badly named.  For instance, analogWrite() **has
    absolutely nothing to do with** :ref:`lang-analogread`\ , which is
    potentially confusing.
 
-   The alias of analogWrite() to pwmWrite() is provided (sigh) for the
-   sake of compatibility with Arduino, but we recommend using
-   :ref:`lang-pwmwrite` when writing new software, for clarity.
+   The alias of analogWrite() to pwmWrite() is provided for the sake
+   of compatibility with Arduino only.
 
 .. contents:: Contents
    :local:
@@ -97,23 +96,21 @@ Difference 3: No PWM on pin 10
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8,
-9, 11, 12, and 14, or twelve pins in total.  That is at least as
-*many* PWM pins as any Arduino board, but there are differences in
-*which* pins support it.
+9, 11, 12, 14, 24, 27, and 28 or fifteen pins in total.  That's *more*
+PWM-capable pins as any Arduino board, but there are differences in
+*which* pins support PWM.
 
 * On **most Arduino boards** (those with the ATmega168 or ATmega328;
   this includes the **Arduino Uno**), this function works on pins 3,
   5, 6, 9, 10, and 11, or six pins total.  Note that these boards
   support PWM on pin 10, while Maple does not.
 
-* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins
-  total.  Note that this board supports PWM on pins 4, 10, and 13,
-  while the Maple does not.  Maple supports PWM on pins 0, 1, and 14,
-  which the Mega does not, making the total number of pins supporting
-  PWM equal on these boards.
+* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve
+  pins total.  Note that this board supports PWM on pins 4, 10, and
+  13, while the Maple does not.
 
-* **Older Arduino boards** with an ATmega8 only support analogWrite() on
-  pins 9, 10, and 11.  Maple does not support PWM on pin 10.
+* **Older Arduino boards** with an ATmega8 only support analogWrite()
+  on pins 9, 10, and 11.  Maple does not support PWM on pin 10.
 
 In all cases, Arduino boards support PWM on pin 10, unlike Maple.  We
 did our best to make PWM as pin-compatible as possible; however,
@@ -125,7 +122,8 @@ work on any Arduino board and on Maple.  The "safe" pins, which work
 on most recent Arduino boards, the Arduino Mega and the Maple, are
 pins 3, 5, 6, 9, and 11.  Thus, if you want your project to be as
 portable as possible between Maple and Arduino, we recommend using the
-"safest" pins first, then the "safe" pins, as necessary.
+"safest" pins first, then the "safe" pins, then any other pins, as
+necessary.
 
 Difference 4: PWM frequency
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -138,17 +136,23 @@ Hz, or 1.1 KHz.  This is because the PWM frequency is the frequency of
 the timer which controls PWM output on the particular pin (\
 :ref:`the PWM tutorial has the details <pwm>`\ ).
 
-If your application absolutely requires Arduino's PWM frequency (it
-probably doesn't), then the steps are:
+If your application definitely requires Arduino's PWM frequency, then
+the steps are:
 
-1. Figure out which timer controls PWM output on your pin (\ :ref:`this table <pwm-timer-table>` is your friend here).  Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4.
+1. Figure out which :ref:`timer <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.
 
-2. Call ``Timern.setPeriod(2041)``\ .  This will set the timer's period to approximately 2041 microseconds, which is a frequency of approximately 490 Hz.
+2. Call ``Timern.setPeriod(2041)``\ .  This will set the timer's
+   period to approximately 2041 microseconds, which is a frequency of
+   approximately 490 Hz.
 
 Be aware that this will change the period for the **entire timer**\ ,
 and will affect anything else in your program that depends on that
-timer.  One example is :ref:`interrupts <timers-attachinterrupt>`\ .
-You've been :ref:`warned <timers-pwm-conflicts>`\ .
+timer.  The important examples are :ref:`timer interrupts
+<lang-hardwaretimer-attachinterrupt>` and :ref:`PWM
+<timers-pwm-conflicts>`\ .
 
 See also
 --------
diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst
index bc5c894..4426293 100644
--- a/docs/source/lang/api/constants.rst
+++ b/docs/source/lang/api/constants.rst
@@ -288,6 +288,29 @@ exponent indicators.  Some examples are given in the following table:
      - 67.0×10\ :sup:`-12`
      - ``0.000000000067``
 
+.. _lang-constants-board:
+
+Board-Specific Constants
+------------------------
+
+This section documents constants whose value might change across
+different LeafLabs boards.  You can use these constants to help ensure
+that your code will be portable across different boards.
+
+.. TODO replace "upcoming" when Mini, Native come out
+
+.. _lang-constants-led:
+
+- ``BOARD_LED_PIN``: the number of the pin which connects to the
+  built-in LED.  On the Maple, this is pin 13, but it's not guaranteed
+  to be the same in upcoming boards like the Maple Mini.
+
+.. _lang-constants-but:
+
+- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the
+  built-in button (labeled "BUT").  On the Maple, this is pin 38, but
+  it's not guaranteed to be the same in other boards.
+
 See Also
 --------
 
diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst
new file mode 100644
index 0000000..c71b2c3
--- /dev/null
+++ b/docs/source/lang/api/hardwarespi.rst
@@ -0,0 +1,152 @@
+.. highlight:: cpp
+
+.. _lang-hardwarespi:
+
+HardwareSPI
+===========
+
+This class is used for creating objects to manage the Maple's built-in
+SPI ports.  The Maple has two SPI ports.  The relevant pins
+corresponding to each port's logic signals are documented in the
+following table (and on the Maple silkscreen):
+
+.. _lang-hardwarespi-pinout:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Port number
+     - NSS
+     - MOSI
+     - MISO
+     - SCK
+
+   * - 1
+     - 10
+     - 11
+     - 12
+     - 13
+
+   * - 2
+     - 31
+     - 32
+     - 33
+     - 34
+
+If you use a SPI port, you cannot simultaneously use its associated
+pins for other purposes.
+
+Library Documentation
+---------------------
+
+HardwareSPI Class Reference
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use the SPI interface by including a declaration ``HardwareSPI
+Spi(number);`` at the start of the sketch or program.  The ``number``
+must be either 1 or 2 and specifies which port to use.  Once this is
+done, you can call any of the methods documented here using
+``Spi.method(arguments)``; for example, ``Spi.send(0x13)`` would send
+the value ``0x13`` into the port buffer to be transmitted as soon as
+possible.
+
+.. cpp:class:: HardwareSPI
+
+   Class for interacting with SPI.
+
+.. cpp:function:: HardwareSPI::HardwareSPI(uint32 spi_num)
+
+   Construct an object for managing a SPI peripheral.  ``spi_num``
+   must be 1 or 2; see the :ref:`table above
+   <lang-hardwarespi-pinout>` for pinout information.
+
+.. cpp:function:: void HardwareSPI::begin(SPIFrequency freq, uint32 endianness, uint32 mode)
+
+   Configure the baudrate of the given SPI port and set up the header
+   pins appropriately.
+
+   Parameters:
+
+   - ``freq``: one of the ``SPIFrequency`` values, given :ref:`below
+     <lang-hardwarespi-spifrequency>`.
+
+   - ``endianness``: either ``LSBFIRST`` (little-endian) or
+     ``MSBFIRST`` (big-endian).
+
+   - ``mode``: one of 0, 1, 2, or 3, and specifies which SPI mode is
+     used.  The mode number determines a combination of polarity and
+     phase according to the following table:
+
+     .. list-table::
+        :header-rows: 1
+
+        * - Mode
+          - Polarity
+          - Phase
+
+        * - 0
+          - 0
+          - 0
+
+        * - 1
+          - 0
+          - 1
+
+        * - 2
+          - 1
+          - 0
+
+        * - 3
+          - 1
+          - 1
+
+     For more information on polarity and phase, see the
+     :ref:`external references, below <lang-hardwarespi-seealso>`.
+
+.. cpp:function:: void HardwareSPI::begin()
+
+   A convenience ``begin()``, equivalent to ``begin(SPI_1_125MHZ,
+   MSBFIRST, 0)``.
+
+.. cpp:function:: uint8 HardwareSpi::send(uint8 *data, uint32 length)
+
+   Writes ``data`` into the port buffer to be transmitted as soon as
+   possible, where ``length`` is the number of bytes to send from
+   ``data``.  Returns the last byte shifted back from slave.
+
+.. cpp:function:: uint8 HardwareSpi::send(uint8 data)
+
+   Writes the single byte ``data`` into the port buffer to be
+   transmitted as soon as possible.  Returns the data byte shifted
+   back from the slave.
+
+.. cpp:function:: uint8 HardwareSpi::recv()
+
+   Reads a byte from the peripheral.  Returns the next byte in the
+   buffer.
+
+SPI Speeds
+^^^^^^^^^^
+
+.. _lang-hardwarespi-spifrequency:
+
+The possible SPI speeds are configured using the ``SPIFrequency`` enum:
+
+.. doxygenenum:: SPIFrequency
+
+.. _lang-hardwarespi-seealso:
+
+See Also
+--------
+
+* `Wikipedia Article on Serial Peripheral Interface Bus (SPI)
+  <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)
+
+
diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst
new file mode 100644
index 0000000..258471b
--- /dev/null
+++ b/docs/source/lang/api/hardwaretimer.rst
@@ -0,0 +1,368 @@
+.. highlight:: cpp
+
+.. _lang-hardwaretimer:
+
+HardwareTimer
+=============
+
+This class defines the public API for interfacing with the STM32's
+built-in timer peripherals.  More information on these peripherals
+(including code examples) is available in the :ref:`timers reference
+<timers>`.
+
+Library Documentation
+---------------------
+
+HardwareTimer Class Reference
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To interact with a particular timer, call one of the methods
+documented below on one of the predefined ``HardwareTimer`` instances.
+For example, to set the prescale factor on timer 1 to 5, call
+``Timer1.setPrescaleFactor(5)``.
+
+.. cpp:class:: HardwareTimer
+
+   Class for interacting with a timer.  There are four predefined
+   instances available on the Maple: ``Timer1``, ``Timer2``,
+   ``Timer3``, and ``Timer4``.
+
+.. _lang-hardwaretimer-attachinterrupt:
+
+.. cpp:function:: void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler)
+
+   Attach an interrupt handler to the given ``channel``.  This
+   interrupt handler will be called when the timer's counter reaches
+   the given channel :ref:`compare <lang-hardwaretimer-setcompare>`
+   value.
+
+   ``handler`` should be a function which takes no arguments and has
+   :ref:`void <lang-void>` value; i.e. it should have signature ::
+
+       void handler(void);
+
+   You can later detach the interrupt using :ref:`detachInterrupt()
+   <lang-hardwaretimer-detachinterrupt>`.
+
+   .. note:: The function (often called an *interrupt service
+             routine*, or ISR) should attempt to return as quickly as
+             possible.  :ref:`Blinking the LED <lang-toggleled>`, some
+             logic, :ref:`PWM <pwm>` updates, and :ref:`Serial
+             <lang-serial>` writes are fine; writing to
+             :ref:`SerialUSB <lang-serialusb>` or :ref:`waiting
+             <lang-waitforbuttonpress>` for user input can take a long
+             time and prevent other interrupts from firing on time.
+
+             Tip: if you have a :ref:`delay() <lang-delay>` in your
+             ISR, you're probably doing it wrong.
+
+.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler)
+
+   Equivalent to :ref:`attachInterrupt
+   <lang-hardwaretimer-attachinterrupt>`\ ``(1, handler)``.
+
+.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler)
+
+   Equivalent to :ref:`attachInterrupt
+   <lang-hardwaretimer-attachinterrupt>`\ ``(2, handler)``.
+
+.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler)
+
+   Equivalent to :ref:`attachInterrupt
+   <lang-hardwaretimer-attachinterrupt>`\ ``(3, handler)``.
+
+.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler)
+
+   Equivalent to :ref:`attachInterrupt
+   <lang-hardwaretimer-attachinterrupt>`\ ``(4, handler)``.
+
+.. _lang-hardwaretimer-setchannelmode:
+
+.. cpp:function:: void HardwareTimer::setChannelMode(int channel, TimerMode mode)
+
+   Set the given channel of this timer to the given :ref:`mode
+   <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.
+
+.. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode)
+
+   Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
+   ``(1, mode)``.
+
+.. cpp:function:: void HardwareTimer::setChannel2Mode(TimerMode mode)
+
+   Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
+   ``(2, mode)``.
+
+.. cpp:function:: void HardwareTimer::setChannel3Mode(TimerMode mode)
+
+   Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
+   ``(3, mode)``.
+
+.. cpp:function:: void HardwareTimer::setChannel4Mode(TimerMode mode)
+
+   Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\
+   ``(4, mode)``.
+
+.. _lang-hardwaretimer-getcompare:
+
+.. cpp:function:: uint16 HardwareTimer::getCompare(int channel)
+
+   Gets the compare value for the given ``channel``, from 1 to 4.  See
+   :ref:`setCompare() <lang-hardwaretimer-setcompare>`.
+
+.. cpp:function:: uint16 HardwareTimer::getCompare1()
+
+   Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
+   ``(1, mode)``.
+
+.. cpp:function:: uint16 HardwareTimer::getCompare2()
+
+   Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
+   ``(2, mode)``.
+
+.. cpp:function:: uint16 HardwareTimer::getCompare3()
+
+   Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
+   ``(3, mode)``.
+
+.. cpp:function:: uint16 HardwareTimer::getCompare4()
+
+   Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\
+   ``(4, mode)``.
+
+.. _lang-hardwaretimer-setcompare:
+
+.. cpp:function:: void HardwareTimer::setCompare(int channel, uint16 compare)
+
+   Sets the compare value for the given ``channel`` to ``compare``.
+   If ``compare`` is greater than this timer's overflow value, it will
+   be truncated to the overflow value.  The default compare value is
+   65,535 (the largest unsigned 16-bit integer value).
+
+   When the counter reaches this value the interrupt for this channel
+   will fire if the given ``channel`` :ref:`mode
+   <lang-hardwaretimer-setchannelmode>` is ``TIMER_OUTPUTCOMPARE`` and
+   an interrupt is :ref:`attached
+   <lang-hardwaretimer-attachinterrupt>`.
+
+   By default, this only changes the relative offsets between events
+   on a single timer ("phase"); they don't control the frequency with
+   which they occur. However, a common trick is to increment the
+   compare value manually in the interrupt handler so that the event
+   will fire again after the increment period. There can be a
+   different increment value for each channel, so this trick allows
+   events to be programmed at 4 different rates on a single
+   timer. Note that function call overheads mean that the smallest
+   increment rate is at least a few microseconds.
+
+.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare)
+
+   Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
+   ``(1, compare)``.
+
+.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare)
+
+   Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
+   ``(2, compare)``.
+
+.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare)
+
+   Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
+   ``(3, compare)``.
+
+.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare)
+
+   Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\
+   ``(4, compare)``.
+
+.. cpp:function:: uint16 HardwareTimer::getCount()
+
+   Gets the current timer count.  Due to function call overhead, the
+   return value will be increasingly accurate with smaller prescale
+   values.  Also see :ref:`setCount() <lang-hardwaretimer-setcount>`.
+
+.. _lang-hardwaretimer-setcount:
+
+.. cpp:function:: void HardwareTimer::setCount(uint16 val)
+
+    Set the timer's current count to ``val``.
+
+    Note that there is some function call overhead associated with
+    calling this method, so using it is not a robust way to get
+    multiple timers to share a count value.
+
+    If ``val`` exceeds the timer's :ref:`overflow value
+    <lang-hardwaretimer-getoverflow>`, it is truncated to the overflow
+    value.
+
+
+.. _lang-hardwaretimer-detachinterrupt:
+
+.. cpp:function:: void HardwareTimer::detachInterrupt(int channel)
+
+   Remove the interrupt handler attached to the given ``channel``, if
+   any.  The handler will no longer be called by this timer.
+
+.. cpp:function:: void HardwareTimer::detachCompare1Interrupt()
+
+   Equivalent to :ref:`detachInterrupt
+   <lang-hardwaretimer-detachinterrupt>`\ ``(1)``.
+
+.. cpp:function:: void HardwareTimer::detachCompare2Interrupt()
+
+   Equivalent to :ref:`detachInterrupt
+   <lang-hardwaretimer-detachinterrupt>`\ ``(2)``.
+
+.. cpp:function:: void HardwareTimer::detachCompare3Interrupt()
+
+   Equivalent to :ref:`detachInterrupt
+   <lang-hardwaretimer-detachinterrupt>`\ ``(3)``.
+
+.. cpp:function:: void HardwareTimer::detachCompare4Interrupt()
+
+   Equivalent to :ref:`detachInterrupt
+   <lang-hardwaretimer-detachinterrupt>`\ ``(4)``.
+
+.. _lang-hardwaretimer-generateupdate:
+
+.. cpp:function:: void HardwareTimer::generateUpdate()
+
+   Re-initializes the counter (to 0 in upcounting mode, which is the
+   default), and generates an update of the prescale and overflow
+   registers.
+
+.. _lang-hardwaretimer-getoverflow:
+
+.. cpp:function:: uint16 HardwareTimer::getOverflow()
+
+   Gets the timer's overflow value.  See :ref:`setOverflow()
+   <lang-hardwaretimer-setoverflow>`.
+
+.. _lang-hardwaretimer-setoverflow:
+
+.. cpp:function:: void HardwareTimer::setOverflow(uint16 val)
+
+    Sets the timer overflow (or "reload") value to ``val``.
+
+    When the timer's counter reaches this, value it resets to
+    zero. Its default value is 65535 (the largest unsigned 16-bit
+    integer); setting the overflow to anything lower will cause
+    interrupts to be called more frequently (see :ref:`setPeriod()
+    <lang-hardwaretimer-setperiod>` function for a shortcut).
+
+    After the next :ref:`timer update
+    <lang-hardwaretimer-generateupdate>`, this number will be the
+    maximum value for the timer's channel compare values.
+
+.. _lang-hardwaretimer-pause:
+
+.. cpp:function:: void HardwareTimer::pause()
+
+   Stop the timer's counter, without affecting its configuration.
+
+   The timer will no longer count or fire interrupts after this
+   function is called, until it is resumed.  This function is useful
+   during timer setup periods, in order to prevent interrupts from
+   firing before the timer is fully configured.
+
+   Note that there is some function call overhead associated with this
+   method, so using it in concert with :ref:`resume()
+   <lang-hardwaretimer-resume>` is not a robust way to align multiple
+   timers to the same count value.
+
+.. _lang-hardwaretimer-setperiod:
+
+.. cpp:function:: uint16 HardwareTimer::setPeriod(uint32 microseconds)
+
+   Configure the :ref:`prescaler
+   <lang-hardwaretimer-getprescalefactor>` and :ref:`overflow
+   <lang-hardwaretimer-getoverflow>` values to generate a timer reload
+   with a period as close to the given number of ``microseconds`` as
+   possible.
+
+   The return value is the new overflow value, which may be used to
+   set channel compare values.  However, if a clock that fires an
+   interrupt every given number of microseconds is all that is
+   desired, and the relative "phases" are unimportant, channel compare
+   values may all be set to 1.
+
+.. _lang-hardwaretimer-getprescalefactor:
+
+.. cpp:function:: uint16 HardwareTimer::getPrescaleFactor()
+
+    Returns the timer's prescale factor.  See
+    :ref:`setPrescaleFactor() <lang-hardwaretimer-setprescalefactor>`.
+
+.. _lang-hardwaretimer-setprescalefactor:
+
+.. cpp:function:: void HardwareTimer::setPrescaleFactor(uint16 factor)
+
+    Set the timer's prescale factor to ``factor``.
+
+    The prescaler acts as a clock divider to slow down the rate at
+    which the counter increments.
+
+    For example, the system clock rate is 72MHz, so the counter will
+    reach 65535 in (13.89 nanoseconds) × (65535 counts) = (910.22
+    microseconds), or about a thousand times a second. If the
+    prescaler equals 1098, then the clock rate is effectively 72MHz /
+    1098 = 65.56KHz, and the counter will reach 65536 in (15.25
+    microseconds) × (65536 counts) = (0.999 seconds), or about once
+    per second.
+
+    The :ref:`setPeriod() <lang-hardwaretimer-setperiod>` method may
+    also be used as a convenient alternative.
+
+.. cpp:function:: void HardwareTimer::resume()
+
+    Resume a paused timer, without affecting its configuration.
+
+    The timer will resume counting and firing interrupts as
+    appropriate.
+
+    Note that there is some function call overhead associated with
+    using this method, so using it in concert with :ref:`pause()
+    <lang-hardwaretimer-pause>` is not a robust way to align multiple
+    timers to the same count value.
+
+.. cpp:function:: timer_dev_num HardwareTimer::getTimerNum()
+
+   Returns the :ref:`timer device number
+   <lang-hardwaretimer-timer-dev-num>` associated with the timer.  For
+   example, ``Timer1.getTimerNum()`` would return ``TIMER1``.
+
+   In most cases, you should not need to use this function.  If you do
+   use it, be careful; the constant ``TIMER1`` is *not equal* to the
+   number 1; similarly, ``TIMER2`` is *not* the number 2, etc.  Be
+   sure to refer to the timer device number by name.
+
+.. _lang-hardwaretimer-modes:
+
+Timer Modes
+^^^^^^^^^^^
+.. doxygenenum:: TimerMode
+
+.. _lang-hardwaretimer-timer-dev-num:
+
+Timer Device Numbers
+^^^^^^^^^^^^^^^^^^^^
+
+These provide a lower-level interface for interacting with timers.
+They are mostly useful in context with the :ref:`getTimer()
+<lang-hardwaretimer-gettimer>` function.  **Be careful** when using
+these not to confuse e.g. ``TIMER1`` with the number 1; they are
+different.
+
+.. doxygenenum:: timer_dev_num
+
+.. _lang-hardwaretimer-convenience:
+
+.. _lang-hardwaretimer-gettimer:
+
+Other Functions
+^^^^^^^^^^^^^^^
+.. doxygenfunction:: getTimer
diff --git a/docs/source/lang/api/interrupts.rst b/docs/source/lang/api/interrupts.rst
new file mode 100644
index 0000000..58fd2cc
--- /dev/null
+++ b/docs/source/lang/api/interrupts.rst
@@ -0,0 +1,47 @@
+.. highlight:: cpp
+
+.. _lang-interrupts:
+
+interrupts()
+============
+
+Re-enables interrupts (after they've been disabled by
+:ref:`noInterrupts() <lang-nointerrupts>`).  Interrupts allow certain
+important tasks to happen in the background, and certain interrupts
+are enabled by default.
+
+Some functions will not work while interrupts are disabled, and both
+incoming and outgoing communication may be ignored. Interrupts can
+slightly disrupt the timing of code, however, and may be disabled for
+particularly critical sections of code.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: interrupts
+
+Example
+-------
+
+::
+
+    void setup() {}
+
+    void loop() {
+      noInterrupts();
+      // critical, time-sensitive code here
+      interrupts();
+      // other code here
+    }
+
+See Also
+--------
+
+- :ref:`noInterrupts() <lang-nointerrupts>`
+- :ref:`attachInterrupt() <lang-attachinterrupt>`
+- :ref:`detachInterrupt() <lang-detachinterrupt>`
+- :ref:`Timers reference <timers>`
+- :ref:`Timer API <lang-hardwaretimer>`
+- :ref:`External interrupts <external-interrupts>`
+
+.. include:: /lang/cc-attribution.txt
diff --git a/docs/source/lang/api/isbuttonpressed.rst b/docs/source/lang/api/isbuttonpressed.rst
new file mode 100644
index 0000000..dbff0c9
--- /dev/null
+++ b/docs/source/lang/api/isbuttonpressed.rst
@@ -0,0 +1,17 @@
+.. _lang-isbuttonpressed:
+
+isButtonPressed()
+=================
+
+Check whether the board's built-in button (labeled BUT on the
+silkscreen) is pressed.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: isButtonPressed
+
+See Also
+--------
+
+- :ref:`lang-waitforbuttonpress`
diff --git a/docs/source/lang/api/nointerrupts.rst b/docs/source/lang/api/nointerrupts.rst
new file mode 100644
index 0000000..68f0498
--- /dev/null
+++ b/docs/source/lang/api/nointerrupts.rst
@@ -0,0 +1,47 @@
+.. highlight:: cpp
+
+.. _lang-nointerrupts:
+
+noInterrupts()
+==============
+
+Description
+-----------
+
+Disables interrupts.  Interrupts allow certain important tasks to
+happen in the background and are enabled by default. Some functions
+will not work while interrupts are disabled, and incoming
+communication may be ignored. Interrupts can slightly disrupt the
+timing of code, however, and may be disabled for particularly critical
+sections of code.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: noInterrupts
+
+Example
+-------
+
+::
+
+    void setup() {}
+
+    void loop() {
+      noInterrupts();
+      // critical, time-sensitive code here
+      interrupts();
+      // other code here
+    }
+
+See Also
+--------
+
+- :ref:`interrupts() <lang-interrupts>`
+- :ref:`attachInterrupt() <lang-attachinterrupt>`
+- :ref:`detachInterrupt() <lang-detachinterrupt>`
+- :ref:`Timers reference <timers>`
+- :ref:`Timer API <lang-hardwaretimer>`
+- :ref:`External interrupts <external-interrupts>`
+
+.. include:: /lang/cc-attribution.txt
diff --git a/docs/source/lang/api/pinmode.rst b/docs/source/lang/api/pinmode.rst
index b9095da..03cbcfa 100644
--- a/docs/source/lang/api/pinmode.rst
+++ b/docs/source/lang/api/pinmode.rst
@@ -13,6 +13,8 @@ Library Documentation
 
 .. doxygenfunction:: pinMode
 
+.. _lang-pinmode-wiringpinmode:
+
 .. doxygenenum:: WiringPinMode
 
 Discussion
diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst
index 7a1d51f..2c858ab 100644
--- a/docs/source/lang/api/pwmwrite.rst
+++ b/docs/source/lang/api/pwmwrite.rst
@@ -11,6 +11,13 @@ pwmWrite(), the pin will output a steady square wave with the given
 duty cycle.  You can change the duty cycle later by calling pwmWrite()
 again with the same pin and a different duty.
 
+On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8,
+9, 11, 12, 14, 24, 27, and 28.
+
+The Arduino function :ref:`analogWrite() <lang-analogwrite>` is an
+alias for ``pwmWrite()``, but it is badly named, and its use is
+discouraged.
+
 .. contents:: Contents
    :local:
 
@@ -25,12 +32,11 @@ Example
 Sets the output to the LED proportional to the value read from the
 potentiometer::
 
-    int ledPin = 13;      // LED connected to pin 13 (Maple)
     int analogPin = 3;    // potentiometer connected to analog pin 3
     int val = 0;          // variable to store the read value
 
     void setup() {
-      pinMode(ledPin, OUTPUT);   // sets the LED pin as output
+      pinMode(BOARD_LED_PIN, OUTPUT);   // sets the LED pin as output
 
       pinMode(analogPin, PWM);   // sets the potentiometer pin as PWM
                                  // output
@@ -39,8 +45,9 @@ potentiometer::
     void loop() {
       val = analogRead(analogPin);   // read the input pin
 
-      analogWrite(ledPin, val / 16);  // analogRead values go from 0 to 4095,
-                                      // analogWrite values from 0 to 65535
+      analogWrite(BOARD_LED_PIN, val / 16);  // analogRead values go from 0
+                                             // to 4095, analogWrite values
+                                             // from 0 to 65535
     }
 
 See Also
diff --git a/docs/source/lang/api/serialusb.rst b/docs/source/lang/api/serialusb.rst
index af3a7e0..e1d12bf 100644
--- a/docs/source/lang/api/serialusb.rst
+++ b/docs/source/lang/api/serialusb.rst
@@ -52,7 +52,9 @@ world!")``.
 .. cpp:class:: USBSerial
 
    Emulated serial-over-USB class.  ``SerialUSB`` is the predefined
-   instance.
+   (singleton) instance.
+
+.. _lang-serialusb-begin:
 
 .. cpp:function:: USBSerial::begin()
 
@@ -65,7 +67,12 @@ world!")``.
 
 .. cpp:function:: USBSerial::end()
 
-   Disables the USB peripheral.
+   Disables the USB peripheral.  Note that using this function will
+   terminate all USB communications between the Maple and the USB
+   host; in particular, it implies that you won't be able to upload
+   any new programs without resetting the board or using
+   :ref:`perpetual bootloader mode
+   <troubleshooting-perpetual-bootloader>`.
 
 .. cpp:function:: unsigned int USBSerial::available()
 
diff --git a/docs/source/lang/api/toggleled.rst b/docs/source/lang/api/toggleled.rst
new file mode 100644
index 0000000..0cc20c2
--- /dev/null
+++ b/docs/source/lang/api/toggleled.rst
@@ -0,0 +1,17 @@
+.. _lang-toggleled:
+
+toggleLED()
+===========
+
+Switches the LED from off to on, or on to off.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: toggleLED
+
+See Also
+--------
+
+- :ref:`BOARD_LED_PIN <lang-constants-led>`
+- :ref:`togglePin() <lang-togglepin>`
diff --git a/docs/source/lang/api/togglepin.rst b/docs/source/lang/api/togglepin.rst
new file mode 100644
index 0000000..290718d
--- /dev/null
+++ b/docs/source/lang/api/togglepin.rst
@@ -0,0 +1,17 @@
+.. _lang-togglepin:
+
+togglePin()
+===========
+
+Switches a digital output pin from :ref:`HIGH <lang-constants-high>`
+to :ref:`LOW <lang-constants-low>`, or from LOW to HIGH.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: togglePin
+
+See Also
+--------
+
+- :ref:`toggleLED() <lang-toggleled>`
diff --git a/docs/source/lang/api/waitforbuttonpress.rst b/docs/source/lang/api/waitforbuttonpress.rst
new file mode 100644
index 0000000..34c5066
--- /dev/null
+++ b/docs/source/lang/api/waitforbuttonpress.rst
@@ -0,0 +1,17 @@
+.. _lang-waitforbuttonpress:
+
+waitForButtonPress()
+====================
+
+Wait for the board's built-in button (labeled BUT on the silkscreen)
+to be pressed, possibly with timeout.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: waitForButtonPress
+
+See Also
+--------
+
+- :ref:`lang-isbuttonpressed`
diff --git a/docs/source/lang/cpp/numeric-types.rst b/docs/source/lang/cpp/built-in-types.rst
index 9d2be48..1323db8 100644
--- a/docs/source/lang/cpp/numeric-types.rst
+++ b/docs/source/lang/cpp/built-in-types.rst
@@ -1,16 +1,20 @@
-.. _lang-numeric-types:
+.. highlight:: cpp
 
-Numeric types
-=============
+.. _lang-built-in-types:
 
-This document serves as a reference for all of the built-in numeric
-types which are available when programming in the IDE.  Programmers
-using the :ref:`command-line tools <unix-toolchain>` will have access
-to these types as long as they have imported ``wirish.h``; several are
-defined in in `libmaple_types.h
+================
+ Built-in Types
+================
+
+This document serves as a reference for many of the built-in types
+which are available when programming in the IDE.  Programmers using
+the :ref:`command-line tools <unix-toolchain>` will have access to
+these types as long as they have imported `wirish.h
+<https://github.com/leaflabs/libmaple/blob/master/wirish/wirish.h>`_;
+several are defined in in `libmaple_types.h
 <https://github.com/leaflabs/libmaple/blob/master/libmaple/libmaple_types.h>`_.
 
-.. _lang-numeric-types-integral:
+.. _lang-built-in-types-integral:
 
 Integral types
 --------------
@@ -77,3 +81,15 @@ Floating-Point Types
 .. cpp:type:: double
 
    64-bit, IEEE 754 double-precision floating-point type.
+
+Other Types
+-----------
+
+.. cpp:type:: voidFuncPtr
+
+   Pointer to a function that takes no arguments and returns nothing, i.e.
+
+   ::
+
+       typedef void (*voidFuncPtr)(void);
+
diff --git a/docs/source/lang/cpp/keywords.rst b/docs/source/lang/cpp/keywords.rst
index e4ebe99..e3bc20d 100644
--- a/docs/source/lang/cpp/keywords.rst
+++ b/docs/source/lang/cpp/keywords.rst
@@ -94,7 +94,7 @@ The following keywords are used for built-in types.
 - :ref:`lang-float`
 - :ref:`lang-int`
 - :ref:`lang-long`
-- :ref:`short <lang-numeric-types-integral>`
+- :ref:`short <lang-built-in-types-integral>`
 - :ref:`void <lang-void>` (not really a type, but used in the absence
   of one)
 
diff --git a/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst
index 9094cd5..e6da0c9 100644
--- a/docs/source/lang/cpp/variables.rst
+++ b/docs/source/lang/cpp/variables.rst
@@ -37,7 +37,7 @@ named ``inputVariable2``, with an initial value of ``0``::
     int inputVariable2 = 0;
 
 The Maple environment comes ready to use with many useful types of
-variables.  See the :ref:`built-in types <lang-numeric-types>` page
+variables.  See the :ref:`built-in types <lang-built-in-types>` page
 for more information.
 
 Here are a few examples of declaring variables of different types::
@@ -116,7 +116,7 @@ he goes past the left side of the screen, he reappears on the right::
        x = x + 1; // x now contains -2,147,483,648; rolled over "right to left"
 
 Each numeric type's reference page includes its range.  See the
-:ref:`built-in types <lang-numeric-types>` reference for links to each
+:ref:`built-in types <lang-built-in-types>` reference for links to each
 type's reference page.
 
 Using Variables
@@ -149,7 +149,7 @@ See Also
 --------
 
 - :ref:`lang-scope`
-- :ref:`lang-numeric-types`
+- :ref:`lang-built-in-types`
 
 .. rubric:: Footnotes
 
diff --git a/docs/source/lang/cpp/void.rst b/docs/source/lang/cpp/void.rst
index 88bd448..88c9c64 100644
--- a/docs/source/lang/cpp/void.rst
+++ b/docs/source/lang/cpp/void.rst
@@ -5,10 +5,12 @@
 ``void``
 ========
 
-The ``void`` keyword is used only in function declarations. It
-indicates that the function is expected to return no information to
-the function from which it was called, or that it expects no arguments
-from its caller.
+.. cpp:type:: void
+
+   The ``void`` keyword is used in function declarations. It indicates
+   that the function is expected to return no information to the
+   function from which it was called, or that it expects no arguments
+   from its caller.
 
 Example
 -------
diff --git a/docs/source/lang/unimplemented/interrupts.rst b/docs/source/lang/unimplemented/interrupts.rst
deleted file mode 100644
index 55b8e93..0000000
--- a/docs/source/lang/unimplemented/interrupts.rst
+++ /dev/null
@@ -1,59 +0,0 @@
-.. _lang-interrupts:
-
-interrupts()
-============
-
-Re-enables interrupts (after they've been disabled by
-`noInterrupts <http://arduino.cc/en/Reference/NoInterrupts>`_\ ()).
-Interrupts allow certain important tasks to happen in the
-background and are enabled by default. Some functions will not work
-while interrupts are disabled, and incoming communication may be
-ignored. Interrupts can slightly disrupt the timing of code,
-however, and may be disabled for particularly critical sections of
-code.
-
-
-
-Parameters
-----------
-
-None
-
-
-
-Returns
--------
-
-None
-
-
-
-Example
--------
-
-::
-
-    void setup() {}
-
-    void loop()
-    {
-      noInterrupts();
-      // critical, time-sensitive code here
-      interrupts();
-      // other code here
-    }
-
-
-
-See Also
---------
-
-
--  `noInterrupts <http://arduino.cc/en/Reference/NoInterrupts>`_\ ()
--  `attachInterrupt <http://arduino.cc/en/Reference/AttachInterrupt>`_\ ()
--  `detachInterrupt <http://arduino.cc/en/Reference/DetachInterrupt>`_\ ()
-
-
-
-
-.. include:: /lang/cc-attribution.txt
diff --git a/docs/source/lang/unimplemented/nointerrupts.rst b/docs/source/lang/unimplemented/nointerrupts.rst
deleted file mode 100644
index fb2e5f9..0000000
--- a/docs/source/lang/unimplemented/nointerrupts.rst
+++ /dev/null
@@ -1,59 +0,0 @@
-.. _lang-nointerrupts:
-
-noInterrupts()
-==============
-
-Description
------------
-
-Disables interrupts (you can re-enable them with interrupts()).
-Interrupts allow certain important tasks to happen in the
-background and are enabled by default. Some functions will not work
-while interrupts are disabled, and incoming communication may be
-ignored. Interrupts can slightly disrupt the timing of code,
-however, and may be disabled for particularly critical sections of
-code.
-
-
-
-Parameters
-----------
-
-None.
-
-
-
-Returns
--------
-
-None.
-
-
-
-Example
--------
-
-::
-
-    void setup() {}
-
-    void loop()
-    {
-      noInterrupts();
-      // critical, time-sensitive code here
-      interrupts();
-      // other code here
-    }
-
-
-
-See Also
---------
-
-
--  `interrupts <http://arduino.cc/en/Reference/Interrupts>`_\ ()
-
-
-
-
-.. include:: /lang/cc-attribution.txt