more sphinx docs

11 files changed, 1089 insertions, 59 deletions

diff --git a/docs/source/_static/img/jtag-wiring.png b/docs/source/_static/img/jtag-wiring.png
new file mode 100644
index 0000000..9c63e82
--- /dev/null
+++ b/docs/source/_static/img/jtag-wiring.png
diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst
index c4c5da2..fea1f35 100644
--- a/docs/source/bootloader.rst
+++ b/docs/source/bootloader.rst
@@ -88,6 +88,8 @@ bootloader was attractive, it became clear, after much toiling, we
 were going to have to write some custom drivers across several
 platforms to make everything work this way.
 
+.. _bootloader-rev3:
+
 Maple Rev3
 ----------
 
diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst
index 2567221..9104fed 100644
--- a/docs/source/gpio.rst
+++ b/docs/source/gpio.rst
@@ -22,6 +22,8 @@ that pin), while some are not.
 .. contents:: Contents
    :local:
 
+.. _pin-mapping-mega-table:
+
 Pin Mapping Mega Table
 ----------------------
 
@@ -34,53 +36,121 @@ above).
 .. 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
-
-   Analog header
-
-   D15  PC0     ADC10   -       -       -       -       No
-   D16  PC1     ADC11   -       -       -       -       No
-   D17  PC2     ADC12   -       -       -       -       No
-   D18  PC3     ADC13   -       -       -       -       No
-   D19  PC4     ADC14   -       -       -       -       No
-   D20  PC5     ADC15   -       -       -       -       No
-
-   External header
-
-   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     -       -       -       -       -       
-
-
-Stub (unfinished).
+   "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"
+
+.. _gpio-modes:
+
+GPIO Modes
+----------
+
+``OUTPUT``
+
+    Basic digital output: when the pin set high the voltage is held at
+    +3.3V (|vcc|) and when set low it is pulled down to ground.
+
+``OUTPUT_OPEN_DRAIN``
+
+    In open drain mode, the pin indicates "low" by accepting current
+    flow to ground and "high" by providing increased impedance. An
+    example use would be to connect a pin to a bus line (which is
+    pulled up to a positive voltage by a separate supply through a
+    large resistor). When the pin is high, not much current flows
+    through to ground and the line stays at positive voltage; when the
+    pin is low the bus "drains" to ground with a small amount of
+    current constantly flowing through the large resistor from the
+    external supply. In this mode no current is ever actually
+    *sourced* from the pin.
+
+``INPUT`` (or ``INPUT_FLOATING``)
+
+    Basic digital input. The pin voltage is sampled; when it is closer
+    to 3.3V (|vcc|) the pin status is high, and when it is closer to
+    0V (ground) it is low. If no external circuit is pulling the pin
+    voltage to high or low, it will tend to randomly oscillate and be
+    very sensitive to noise (e.g., a breath of air across the pin will
+    cause the state to flip).
+
+``INPUT_PULLUP``
+
+    The state of the pin in this mode is reported the same way as with
+    INPUT, but the pin voltage is gently "pulled up" towards
+    +3.3V. This means the state will be high unless an external device
+    is specifically pulling the pin down to ground, in which case the
+    "gentle" pull up will not effect the state of the input.
+
+``INPUT_PULLDOWN``
+
+    The state of the pin in this mode is reported the same way as with
+    INPUT, but the pin voltage is gently "pulled down" towards
+    0V. This means the state will be low unless an external device is
+    specifically pulling the pin up to 3.3V, in which case the
+    "gentle" pull down will not effect the state of the input.
+
+``INPUT_ANALOG``
+
+    This is a special mode for when the pin will be used for analog
+    (not digital) reads. See the :ref:`ADC <adc>` page.
+
+``PWM``
+
+    This is a special mode for when the pin will be used for PWM
+    output (a special case of digital output). See the :ref:`PWM
+    <pwm>` page.
+
+.. TODO PWM_OPEN_DRAIN needs documentation
+
+Function Reference
+------------------
+
+``pinMode(pin_number, MODE)``
+
+    Usually called from within `setup()`_ to configure the pin. MODE
+    is one of the set listed :ref:`above <gpio-modes>`.
+
+``digitalRead(pin_number)``
+
+    Returns ``HIGH`` (|vcc|) or ``LOW`` (0V).
+
+``digitalWrite(pin_number, value)``
+
+    Sets the pin to ``HIGH`` or ``LOW``.
 
 .. _gpio-recommended-reading:
 
@@ -90,5 +160,5 @@ Recommended Reading
 STMicro documentation for STM32F103RB microcontroller:
 
   * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
-  * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_
-  * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_
+  * `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/i2c.rst b/docs/source/i2c.rst
index 34bd57c..564ca0e 100644
--- a/docs/source/i2c.rst
+++ b/docs/source/i2c.rst
@@ -4,4 +4,89 @@
 |i2c|
 =====
 
-Stub.
+.. note::
+
+   The i2c interface is currently only available from the 'i2c' branch
+   of the github `libmaple <http://github.com/leaflabs/libmaple>`_
+   repository.
+
+|i2c| is a crude and easy-to-hack serial protocol that requires only
+two wires/channels for communication between many devices.  Every
+message passed on the bus is between a *master* (who initiates the
+message) and a *slave* device.  Slaves are addressed using 7-bit
+addresses (up to 127 unique devices); 10-bit addressing is possible,
+but currently unimplemented.  Every message consists of an arbitrary
+combination of 8-bit reads and writes as requested by the master.
+Higher level functionality, such as reading a particular register
+value, is achieved by writing to set the memory location then reading
+to pull out the data.
+
+Note that the master/slave designation is on a message-by-message
+basis. The 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.
+
+.. contents:: Contents
+   :local:
+
+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.
+
+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.
+
+Proper wiring and pull-up resistor selection are essential when
+incorporating |i2c| into a circuit, especially with data rates above
+100kHz. In the lab, we usually use approximately 5kΩ resistors with
+|vcc| (3.3V) as the high voltage, and try to connect the pullup
+voltage as close to the SDA and SCL pins as possible.  We recommend
+looking at the ST reference website for |i2c| (see the
+:ref:`recommended reading <i2c-recommended-reading>` below), starting
+with a slow clock rate (10kHz), and, if possible, using an
+oscilloscope to debug any issues.
+
+Function Reference
+------------------
+
+The function API for |i2c| is not finished! See the `source code
+<http://github.com/leaflabs/libmaple/blob/i2c/libmaple/i2c.h>`_ for
+now.
+
+.. TODO link to libmaple I2C docs once (1) finished, (2) in master
+
+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.
+
+.. TODO link to libmaple SMBus docs once (1) finished, (2) in master
+
+.. _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:
+
+  * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
+  * `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)
diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst
index e94229f..5301a18 100644
--- a/docs/source/jtag.rst
+++ b/docs/source/jtag.rst
@@ -4,4 +4,68 @@
  JTAG
 ======
 
-Stub.
+JTAG is an interface for low-level debugging of digital devices. It
+gives instruction by instruction control over the microprocessor and
+allows data to be read and written to arbitrary memory and register
+locations. It is typically used with a debugging tool like `gdb
+<http://www.gnu.org/software/gdb/>`_ when hacking low level routines
+and hardware peripherals (we use it when working on :ref:`libmaple
+<libmaple>`) or to flash a new bootloader.
+
+Note that the STM32 on the Maple has a built-in low level serial
+debugger which could also be used to flash bootloaders, and that the
+:ref:`ASSERT <language-assert>` framework allows basic debugging over
+a USART serial channel.  We expect only advanced users to use this
+feature.
+
+.. contents:: Contents
+   :local:
+
+
+Wiring Diagram
+--------------
+
+.. figure:: /_static/img/jtag-wiring.png
+   :align: center
+   :alt: JTAG wiring diagram
+
+   JTAG wiring diagram to connect a standard 20-pin ARM JTAG device to
+   the 8-pin JTAG port on the Maple.
+
+.. TODO jtag wiring diagram (above) looks terrible; replace it
+
+The Maple has holes for a 8-pin JTAG header but that header is not
+soldered on by default. If you know ahead of time that you'll be
+needing it, and you order `straight from LeafLabs
+<http://leaflabs.com/store/>`_, add a comment to your order and we can
+probably solder one on for no charge.  Otherwise, you can simply
+attach standard 0.1" pitch male header pins (either the exact 4x2
+block or two 4-pin pieces of breakaway straight header). For a one-off
+usage hack, the header can be jammed in the holes and twisted to
+ensure electrical contact; this is what we do to flash our bootloader.
+
+The above schematic assumes that the header has been soldered on to
+the *bottom* of the board, not the top; most ribbon cable connectors
+will interfere with the power header. If you don't want a header
+coming off the bottom, you can use a slim connector and invert this
+diagram appropriately.
+
+
+Compatible Devices
+------------------
+
+We have had good experience with the `Olimex ARM-USB-OCD
+<http://www.olimex.com/dev/arm-usb-ocd.html>`_ device, which costs
+about 55 euro plus shipping (as of October 2010).
+
+
+Recommended Reading
+-------------------
+
+* `Wikipedia Article on Joint Test Action Group (JTAG) <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_
+* `STM32/gdb/OpenOCD HOWTO <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_
+* STMicro documentation for STM32F103RB microcontroller:
+
+  * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
+  * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_
+  * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_
diff --git a/docs/source/language.rst b/docs/source/language.rst
index 6eb5bc7..36cb801 100644
--- a/docs/source/language.rst
+++ b/docs/source/language.rst
@@ -484,6 +484,10 @@ Recommended Reading
 * STMicro documentation for STM32F103RB microcontroller:
 
     * `All documents <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
-    * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_
-    * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_
-    * `Programming Manual (pdf) <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference)
+    * `Datasheet (pdf)
+      <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_
+    * `Reference Manual (pdf)
+      <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_
+    * `Programming Manual (pdf)
+      <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_
+      (assembly language and register reference)
diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst
index c01e415..8d3a8d9 100644
--- a/docs/source/pwm.rst
+++ b/docs/source/pwm.rst
@@ -4,4 +4,161 @@
  Pulse-Width Modulation (PWM)
 ==============================
 
-Stub.
+Pulse Width Modulation is a basic technique to create repeated square
+waves (digital high/low voltage transitions) of user defined length
+and duty cycle. It can be used as a way to encode an "analog" signal
+on a single digital (high/low) line using the time between transitions
+("pulse width") as the variable; this technique is commonly used to
+send servo position and motor speed commands. Another use is to use to
+the ratio of "high" and "low" time to approximate a voltage output;
+this technique can be used to dim an LED or even (with careful
+filtering) generate audio waveforms.
+
+.. contents:: Contents
+   :local:
+
+Overview
+--------
+
+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
+<compatibility>`.
+
+The following table shows which :ref:`timer <timers>` generates 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 
+
+Background
+----------
+
+In its simplest form, the device is a single counter with two
+variables.  The counter starts at zero, and the output starts at
+"high".  The counter increments every clock cycle until it reaches the
+first variable number, at which point the output goes "low".  The
+counter continues incrementing until it reaches the second variable at
+which point the output goes "high" again and the counter resets to
+zero. The time spent with output high is called the **pulse duration**
+or **duty**; the total time before repeat is the **period**.
+
+This simple functionality could be approximated in software by setting
+a GPIO high or low, but the beauty of PWM is that user code simply has
+to configure the device and set the two variables and the device will
+function on its own; no further microprocessor cycles will be
+consumed, and a repeated high/low waveform will spew out.
+
+The Maple has 16-bit PWM resolution, which means that the counter and
+variables can be as large as 65535, as opposed to 255 with 8-bit
+resolution. With a 72MHz clock rate, a PWM output could have maximum
+period of about one millisecond; using a :ref:`prescaler
+<pwm-prescaler>` (clock divider) in front of the counter can increase
+this maximum period.  Setting the :ref:`period <pwm-overflow>` to
+something other than the maximum value gives further control over the
+total length of the waveform.  However, this effectively limits the
+resolution with which the duty can be modified: the duty must be less
+than or equal to the period.
+
+Here are some commonly used PWM configurations (note that servos are
+notoriously variable, especially the lower cost models):
+
++-------------+----------+-----------+---------+---------------+------+
+|**Purpose**  |**Period**|**Duty**   |Prescaler|Period         |Duty  |
+|             |(ms)      |(ms)       |         |               |      |
++=============+==========+===========+=========+===============+======+
+|LED throb    |0.020     |0--0.020   |1 (none) |65535 (default)|0--767|
+|             |          |           |         |               |      |
++-------------+----------+-----------+---------+---------------+------+
+|Servo control|20        |1.25 (0°)  |21       |65535 (default)|4096  |
+|             |          |           |         |               |      |
+|             |          |1.50 (90°) |21       |65535 (default)|4915  |
+|             |          |           |         |               |      |
+|             |          |1.75 (180°)|21       |65535 (default)|5734  |
+|             |          |           |         |               |      |
++-------------+----------+-----------+---------+---------------+------+
+
+Function Reference
+------------------
+
+``pinMode(pin_num, PWM)``
+
+    This command is usually called from `setup()`_ to tell the
+    microcontroller that pin_num should be configured to PWM
+    output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` is
+    also available (see the list of :ref:`GPIO modes <gpio-modes>` for
+    more information).
+
+.. _pwm-pwmwrite:
+
+``pwmWrite(pin_num, value)``
+
+    This command sets the PWM duty. User code is expected to determine
+    and honor the maximum value (based on the configured period). As a
+    convenience, ``analogWrite`` is an alias for ``pwmWrite`` to ease
+    porting Arduino code, though period and duty will have to be
+    recalibrated (see :ref:`compatibility <compatibility>`).
+
+.. _pwm-overflow:
+
+``Timer1.setOverflow(overflow)``
+
+    This function sets the period ("reload" or "overflow") value for
+    an entire PWM timer bank. The value is 16bit (0 to 65535) and
+    determines the maximum value that can be written with
+    :ref:`pwmWrite() <pwm-pwmwrite>` corresponding to 100% duty
+    cycle. This also affects the PWM frequency: the higher reload is,
+    the lower the PWM frequency will be.
+
+    The PWM output pin starts HIGH, then the timer begins counting up
+    from zero (with frequency equal to 72MHz/:ref:`prescaler
+    <pwm-prescaler>`) until it hits the duty value, at which point it
+    drops to LOW.  The timer then continues counting up until it hits
+    the total period (set with this function), at which point the
+    cycle starts again.
+
+.. _pwm-prescaler:
+
+``Timer[1,2,3,4].setPrescaleFactor(prescale)``
+
+    Find the appropriate timer for a given PWM header using the table
+    :ref:`above <pwm-timer-table>`, then set the prescaler.  A
+    prescaler is a clock divider.  The timer will normally count with
+    frequency equal to the STM32's normal clock (72MHz); this
+    corresponds to setting ``prescale`` to 1 (which is the default).
+
+    If a longer frequency is desired, use a larger ``prescale`` value.
+    For instance, an 8MHz frequency can be achieved by setting
+    ``prescale`` to 9, since 72MHz / 9 = 8MHz.
+
+    This function is normally called once from, `setup()`_, but the
+    timer can be reconfigured with a new prescaler at any time.
+
+Recommended Reading
+-------------------
+
+* `Wikipedia Article on Pulse-width modulation
+  <http://en.wikipedia.org/wiki/Pulse-width_modulation>`_
+* `Arduino tutorial on PWM <http://www.arduino.cc/en/Tutorial/PWM>`_
+* `Secrets of Arduino PWM
+  <http://www.arcfn.com/2009/07/secrets-of-arduino-pwm.html>`_ by Ken
+  Shirriff
+* `So You Want To Use PWM, Eh? <http://www.arcfn.com/2009/07/secrets-of-arduino-pwm.html>`_ at Non-Lexical Vocables
+* STMicro documentation for STM32F103RB microcontroller:
+
+  * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
+  * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_
+  * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_
diff --git a/docs/source/spi.rst b/docs/source/spi.rst
index 8518f3c..3c29b79 100644
--- a/docs/source/spi.rst
+++ b/docs/source/spi.rst
@@ -4,4 +4,68 @@
  SPI
 =====
 
-Stub.
+The Maple has two SPI ports. The first has NSS on D10, MOSI on D11,
+MISO on D12, and SCK on D13. The second has NSS on D31, SCK on D32,
+MISO on D33, and MOSI on D34.
+
+.. _spi-speeds:
+
+Each port can be configured at one of the following speeds:
+
+* ``SPI_18MHZ``: 18 MHz
+* ``SPI_9MHZ``: 9 MHz
+* ``SPI_4_5MHZ``: 4.5 MHz
+* ``SPI_2_25MHZ``: 2.25 MHz
+* ``SPI_1_125MHZ``: 1.124 MHz
+* ``SPI_562_500KHZ``: 562.500 KHz
+* ``SPI_281_250KHZ``: 281.250 KHz
+* ``SPI_140_625KHZ``: 140.625 KHz
+
+.. contents:: Contents
+   :local:
+
+Function Reference
+------------------
+
+``HardwareSPI Spi(number);``
+
+    This declaration must be included at the start of any sketch or
+    program that uses the SPI interface. The argument number is either
+    1 or 2 and specifies which port to use.
+
+``Spi.begin(freq, endianness, mode)``
+
+    ``begin`` is usually called in `setup()`_ to configure the
+    baudrate of the given SPI port and to set up the header pins
+    appropriately. ``freq`` is one of the set listed :ref:`above
+    <spi-speeds>`; ``endianness`` is either ``LSBFIRST`` or
+    ``MSBFIRST``; mode is one of 0, 1, 2, 3, and specifies which "SPI
+    Mode" is used (see specification docs linked below).
+
+``Spi.begin()``
+
+    A default ``begin`` with no arguments is provided for the lazy; it
+    is equivalent to ``Spi.begin(SPI_1_125MHZ, MSBFIRST, 0)``.
+
+``Spi.send(data, size)``
+
+    Writes data into the port buffer to be transmitted as soon as
+    possible.  ``data`` should be an array of type ``byte*``; ``size``
+    should be the number of elements in ``data``.
+
+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:
+
+  * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
+  * `Datasheet (pdf)
+    <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_
+  * `Reference Manual (pdf)
+    <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_
+
diff --git a/docs/source/timers.rst b/docs/source/timers.rst
index c156d4f..e0e57cb 100644
--- a/docs/source/timers.rst
+++ b/docs/source/timers.rst
@@ -1,7 +1,315 @@
+.. highlight:: cpp
+
 .. _timers:
 
 ========
  Timers
 ========
 
-Stub.
+There are four general purpose timers in the Maple microcontroller
+that can be configured to generate periodic or delayed events with
+minimal work done by the microcontroller. For example, the :ref:`PWM
+<pwm>` channels, once enabled, generate regular square-wave signals on
+specific output pins that will continue even if the microcontroller is
+busy crunching numbers or handling communications interrupts. By
+attaching interrupt handlers to these channels (instead of just
+changing the voltage on an external pin), more complex events like
+printing to a serial port, updating a variable, or emitting a whale
+mating call can be scheduled. You can even modify the configuration of
+the timer itself at a regular interval; the possibilities are endless!
+
+The four timers each have four separate compare channels. Each timer
+is a single 16-bit counter that can be configured with both a
+prescaler and an overflow value. The prescaler acts as a divider of
+the 72MHz system clock; without prescaling the counter would get up to
+65536 (2 to the 16th power) and roll over more than a thousand times a
+second; even with the full prescaler it rolls over about once a
+minute. The overflow value is the maximum value the counter will go up
+to. It defaults to the full 65535; smaller values will cause the
+counter to reset to zero more frequently.
+
+
+Caveats
+-------
+
+**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 full :ref:`pin mapping table
+<pin-mapping-mega-table>` to match up timer channels and Maple header
+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.
+
+.. compound::
+
+   **Jitter:** other interrupts (USB, Serial, SysTick, or other
+   timers) can and will get called before or during the timer
+   interrupt routines, causing pseudo-random 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.
+
+   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.
+
+.. _timers-modes:
+
+General Timer Modes
+-------------------
+
+``TIMER_DISABLED``
+
+    Exactly what it sounds like: the timer stops counting, interrupts
+    are not called, and no state changes are output.
+
+``TIMER_PWM``
+
+    This is the default mode for pins after initialization. See the
+    :ref:`PWM docs <pwm>` for more information on this mode.
+
+    .. note::
+    
+       ``Timer1.setChannel1Mode(TIMER_PWM)`` may not work as expected;
+       if you want PWM functionality on a channel, make sure you don't
+       set it to something else.
+
+``TIMER_OUTPUTCOMPARE``
+
+    In this mode, the timer counts from 0 to the overflow value
+    repeatedly; every time the counter value reaches one of the
+    channel compare values, the corresponding interrupt is fired.
+
+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()``.
+
+Function Reference
+------------------
+
+For all of these functions, ``Timer1`` can be replaced with
+``Timer2``, ``Timer3``, or ``Timer4``; the channel numbers also range
+from 1 to 4.
+
+``Timer1.pause()``/\ ``Timer1.resume()``
+
+    These functions start and stop the counter without affecting the
+    rest of the configuration. These functions can be used during the
+    setup period to prevent interrupts from firing before they are
+    completely configured. Note that there is some function call
+    overhead with these functions, so they are not a perfect way to
+    align multiple timers to the same count value.
+
+``Timer1.setOverflow(val)``
+
+    Sets the overflow (or "reload") value for the whole timer; when
+    the counter reaches this value it resets to zero. Defaults to
+    65535 (the largest unsigned 16bit integer); setting it to anything
+    lower will cause interrupts to be called more frequently (see the
+    setPeriod function below for a shortcut). This number sets the
+    maximum value for the channel compare values.
+
+``Timer1.setPrescaleFactor(val)``
+
+    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 you set the prescaler to 1098, then the clock rate is
+    effectively 65.56KHz, and the counter will reach 65536 in (15.25
+    microseconds) * (65536 counts) = (0.999 seconds), or just about
+    once a second. Use the :ref:`setPeriod <timers-set-period>`
+    function below if you are allergic to math!
+
+.. _timers-set-period:
+
+``Timer1.setPeriod(val)``
+
+    This tricky trick will configure the prescaler and overflow values
+    to generate a timer reload with a period as close to val
+    microseconds as possible. It returns the chosen overflow value,
+    which you can then use to set the channel compare values
+    appropriately: if you just want the interrupts to fire when the
+    clock rolls over and you don't care about the relative "phase",
+    you can always set the channel compare values to 1.
+
+    Remember: a microsecond is 1/1,000,000th of a second, or 1/1,000
+    of a millisecond. The prescaler itself is 16bit, so the longest
+    period that can be configured is 1/(72MHz) * (2^32) = (59.65
+    seconds) or about a minute. You can get around this by creating an
+    interrupt that increments a 32-bit variable, by using the
+    ``millis()`` function, or by interfacing with an external
+    real-time-clock chip.
+
+``Timer1.setCount(val)``/\ ``Timer1.getCount()``
+
+    These functions let you mess with the counter's brains
+    directly. You can probably make it not work if you try! The timer
+    is 16bit, so ``val`` and the return value of ``getCount`` are
+    ``uint16``.
+
+``Timer1.setChannel1Mode(MODE)``
+
+    This sets the given channel (here 1) of the given timer (here 1)
+    to the given mode. See the :ref:`list above <timers-modes>` for
+    possible values; for interrupts you want ``TIMER_OUTPUTCOMPARE``.
+
+``Timer1.setCompare1(val)``
+
+    Sets the compare value for the given channel; when the counter
+    reaches this value the interrupt for this channel will fire if the
+    channel is in output compare mode and an interrupt is attached.
+
+    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 overhead means that the smallest increment
+    rate is a couple microseconds.
+
+``Timer1.attachCompare1Interrupt(function)``/\ ``Timer1.detachCompare1Interrupt()``
+
+    This is how to attach or disable an interrupt handlers to timer
+    channels; this what will get called when the counter reaches the
+    compare value set with ``setCompareN(val)``. ``function``
+    (sometimes referred to as an ISR: "interrupt service routine")
+    should be of a type that does not accept or return any values
+    (C/C++ programmers: ``void (function*)(void)``). They are just
+    like any other function in your sketch/program and must be
+    initialized at the top of the file and defined below.
+
+    ``function`` should try to do what it has to do as fast as
+    possible. Blinking the LED, some logic, PWM updates, and Serial
+    writes are fine; writing to SerialUSB or waiting for user input
+    can take a long time and other compare interrupts won't fire. Tip:
+    if you have a ``delay()`` in your ISR, you're probably doing it
+    wrong.
+
+    Stay vigilant here... function pointers are serious business, and
+    once you go down that path you'll find yourself in a `forest of
+    parentheses <http://mitpress.mit.edu/sicp/>`_ before you know it.
+
+Code Examples
+-------------
+
+LED blink
+^^^^^^^^^
+
+\  ::
+
+    #define LED_PIN 13
+    #define LED_RATE 500000    // in microseconds; should give 0.5Hz toggles
+
+    void handler_led(void);
+
+    int toggle = 0;
+
+    void setup()
+    {
+        // Set up the LED to blink 
+        pinMode(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) {
+        toggle ^= 1;
+        digitalWrite(LED_PIN, toggle);
+    } 
+
+Racing Counters
+^^^^^^^^^^^^^^^
+
+\  ::
+
+    #define BUTTON_PIN 38
+
+    void handler_count1(void);
+    void handler_count2(void);
+
+    int count1 = 0;
+    int count2 = 0;
+
+    void setup()
+    {
+        // Set up BUT for input
+        pinMode(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(BUTTON_PIN)) {
+                Timer4.pause();
+            } else {
+                Timer4.resume();
+            }
+            delay(1);
+        }
+    }
+
+    void handler1(void) {
+        count1++;
+    } 
+    void handler2(void) {
+        count2++;
+    } 
diff --git a/docs/source/usart.rst b/docs/source/usart.rst
index 30c953a..19b054f 100644
--- a/docs/source/usart.rst
+++ b/docs/source/usart.rst
@@ -4,4 +4,96 @@
  USART
 =======
 
-Stub.
+.. contents::
+   :local:
+
+Hardware/Circuit Design
+-----------------------
+
+The Maple has 3 separate USART devices: ``Serial1``, ``Serial2``, and
+``Serial3``. 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.
+
++-----------+--------+-----+
+|Port       |Function|Pin  |
++===========+========+=====+
+|``Serial1``|TX      |D7   |
+|           |        |     |
+|           |RX      |D8   |
+|           |        |     |
+|           |CK      |D6   |
++-----------+--------+-----+
+|``Serial2``|TX      |D1   |
+|           |        |     |
+|           |RX      |D0   |
+|           |        |     |
+|           |CK      |D10  |
+|           |        |     |
+|           |CTS     |D2   |
+|           |        |     |
+|           |RTS     |D3   |
++-----------+--------+-----+
+|``Serial3``|TX      |D29  |
+|           |        |     |
+|           |RX      |D30  |
+|           |        |     |
+|           |CK      |D31  |
+|           |        |     |
+|           |CTS     |D32  |
+|           |        |     |
+|           |RTS     |D33  |
++-----------+--------+-----+
+
+.. TODO make above less ugly
+
+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 certainly be possible.
+
+Function Reference
+------------------
+
+In the following, you may replace ``SerialN`` with ``Serial1``,
+``Serial2``, or ``Serial3``.
+
+``SerialN.begin(baudrate)``
+
+    ``SerialN.begin`` is usually called in `setup()`_ to configure the
+    baudrate of the given serial port and to set up the header pins
+    appropriately. It can be called at any time to reconfigure a port
+    or to change the baudrate. 9600 baud is the generic speed most
+    widely supported by other devices and terminals.
+
+``SerialN.print(...)``/\ ``SerialN.println(...)``
+
+    Writes data into the port buffer to be transmitted as soon as
+    possible. Accepts strings (``char*``). If a raw integer is
+    passed, the corresponding ASCII character will be transmitted; to
+    print out a number in human readable form add a second parameter
+    with the base system. 
+
+    For example, to print out the decimal number '1234' use
+    ``SerialN.print(1234, DEC)``; to print out the binary number
+    '1001', use ``SerialN.print(9, BIN)``.
+
+``SerialN.available()``/\ ``SerialN.read()``
+
+    ``SerialN.read()`` will return the next unread character that has
+    been received over the port. ``SerialN.available()`` returns how
+    many such bytes are available (or zero if none are). If none are
+    available, ``SerialN.read()`` will block/fail, so the usual
+    program structure is to poll with ``SerialN.available`` and only
+    read if a nonzero value is returned.
+
+Recommended Reading
+-------------------
+
+* `Wikipedia article on Universal asynchronous receiver/transmitter (USART) <http://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter>`_
+* `Arduino reference on Serial <http://arduino.cc/en/Reference/Serial>`_
+* STMicro documentation for STM32F103RB microcontroller:
+
+  * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
+  * `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/usb.rst b/docs/source/usb.rst
index 2460df5..1ce91f0 100644
--- a/docs/source/usb.rst
+++ b/docs/source/usb.rst
@@ -1,7 +1,191 @@
+.. highlight:: cpp
+
 .. _usb:
 
 =====
  USB
 =====
 
-Stub.
+.. note:: Changes and Caveats
+
+   The SerialUSB functionality was modified for the 0.0.6 IDE
+   release. It now includes a 50 millisecond timeout for writes and
+   does not try to detect if the USB host is "really" connected or
+   just enumerated and initialized. This means that if you have a
+   number of SerialUSB writes or prints in your code and you are not
+   monitoring on a computer your program will run much, much slower
+   than if it is being monitored or totally disconnected (battery).
+
+   You can avoid this behavior by :ref:`deciphering the port status
+   <usb-safe-print>` using the DTR and RTS line status; the behavior
+   of these control lines is platform dependent and we no longer
+   interpret them by default.
+
+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 emulated terminal is relatively slow and inefficient; it is best
+for transferring data at regular serial speeds (kilobaud). Users
+requiring faster data transfer should consider implementing a
+different communications protocol; the Maple could be reprogrammed to
+appear as a mass storage device (thumb drive), human interface device
+(mouse or keyboard), microphone, or any other USB device.
+
+The SerialUSB channel is also used as part of the auto-reset feature
+of the IDE to program the board (on Maple Rev3): 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
+``SerialUSB.end()``).
+
+Function Reference
+------------------
+
+``SerialUSB.print(...)``/\ ``SerialUSB.println(...)``
+
+    Writes data into the port buffer to be transmitted as soon as
+    possible. Accepts strings (``char*``). If a raw integer is passed
+    the corresponding ASCII character will be transmitted; to print
+    out a number in human readable form add a second parameter with
+    the base system. For example, to print out the decimal number
+    "1234", use ``SerialUSB.print(1234, DEC)``; to print out the
+    binary number "1001", use ``SerialUSB.print(9, BIN)``.
+
+.. _usb-write:
+
+``SerialUSB.write(bytes)``
+
+    ``write`` is a lower-level function that writes bytes directly
+    into the buffer. :ref:`print() <usb-print>` often calls this
+    function dozens of times to write out a single formatted number;
+    user code can optimize raw data speed by calling this function
+    with 64-byte chunks instead.
+ 
+``SerialUSB.available()``/\ ``SerialUSB.read()``
+
+    ``SerialUSB.read()`` will return the next available character
+    (``byte``) that has been received over the port.
+    ``SerialUSB.available()`` returns how many such bytes are actually
+    available. If there is no data, ``read`` will block/fail, so the
+    usual program structure is to poll with ``available`` and only
+    ``read`` if there are data to read.
+
+``SerialUSB.read(buffer, length)``
+
+    An alternative version of ``SerialUSB.read``; will write the next
+    ``length`` available characters into the array ``buffer``.
+
+``SerialUSB.pending()``
+
+    Returns the number of bytes waiting in the transmit
+    buffer. Usercode can use this to prevent any blocking/waiting when
+    using the direct :ref:`write <usb-write>` functions, or to check
+    if data was actually requested/received by the host.
+
+``SerialUSB.getRTS()``
+
+    Returns the state (1 or 0) of the virtual RTS ("ready to send")
+    line. This can be used to guess if the USB host is actively
+    waiting for data (e.g., if a serial monitor program is running) or
+    just "configured" (i.e., the virtual serial port is configured,
+    but no program is reading data).
+
+``SerialUSB.getDTR()``
+
+    Returns the state (1 or 0) of the virtual DTR ("data terminal
+    ready") line. This can be used to guess if the USB host is
+    actively waiting for data (e.g., if a serial monitor program is
+    running) or just "configured" (i.e., the virtual serial port is
+    configured, but no program is reading data).
+
+.. TODO deprecate crap out of above two functions; write a sane API
+
+``SerialUSB.isConnected()``
+
+    Returns 1 if the USB host is connected and the virtual serial
+    interface is initialized (though not necessarily active).
+    Otherwise, returns 0.
+
+``SerialUSB.end()``/\ ``SerialUSB.begin()``
+
+    The USB peripheral is enabled by default so that the auto-reset
+    feature will work, but it can be disabled/restarted at any time
+    with the ``SerialUSB.end()`` and ``SerialUSB.begin()``
+    functions.
+
+    ``SerialUSB.end()`` is a relatively hard shutdown, similar to
+    unplugging the board; this may crash or confuse any programs
+    running host-side.  Note that calling this function will require
+    the Maple to be put into :ref:`perpetual bootloader mode
+    <troubleshooting-perpetual-bootloader>` before another program can
+    be uploaded onto it, unless ``SerialUSB.begin()`` is called before
+    the upload is attempted.
+
+    It's probably wise to wait a few seconds between calls to
+    ``SerialUSB.end()`` and ``SerialUSB.begin()`` (or to
+    ``SerialUSB.begin()`` and ``SerialUSB.print()``) to let the
+    computer reconfigure.
+
+Code Examples
+-------------
+
+.. _usb-safe-print:
+
+Safe Print
+^^^^^^^^^^
+
+This function should run smoothly and not block; the LED should blink
+at roughly the same speed whether being monitored, running from
+battery, or connected but not monitored. You may need to experiment
+with the DTR/RTS logic for your platform and device configuration.  ::
+
+    #define LED_PIN 13
+
+    void setup() {
+        /* Set up the LED to blink  */
+        pinMode(LED_PIN, OUTPUT);
+    }
+
+    void loop() {
+        // LED will stay off if we are disconnected;
+        // will blink quickly if USB is unplugged (battery etc)
+        if(SerialUSB.isConnected()) {
+            digitalWrite(LED_PIN, 1);
+        }
+        delay(100);
+
+        // If this logic fails to detect if bytes are going to
+        // be read by the USB host, then the println() will fully
+        // many times, causing a very slow LED blink.
+        // If the characters are printed and read, the blink will
+        // only slow a small amount when "really" connected, and fast 
+        // when the virtual port is only configured.
+        if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) {
+            for(int i=0; i<10; i++) {
+               SerialUSB.println(123456,BIN); 
+            }
+        } 
+        digitalWrite(LED_PIN, 0);
+        delay(100);
+    }
+
+Recommended Reading
+-------------------
+
+* `USB in a NutShell <http://www.beyondlogic.org/usbnutshell/usb1.htm>`_ overview from Beyond Logic
+* `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:
+
+    * `All documents <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_
+    * `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)