Docs: Add Maple Mini information

Flesh out and uncomment maple-mini.rst.  Add links to pieces of it in
various appropriate places throughout the rest of the documentation.

8 files changed, 396 insertions, 42 deletions

diff --git a/source/adc.rst b/source/adc.rst
index f3d5f55..a749201 100644
--- a/source/adc.rst
+++ b/source/adc.rst
@@ -20,31 +20,42 @@ number of techniques must be used to get good precision and accuracy.
 Noise and Bias
 --------------
 
-.. FIXME [0.0.11, Maple form factor-specific]
-
-The biggest issues with analog-digital conversion are noise and bias.
-With the Maple, we have tried to isolate the ADC pins and traces from
-strong noise sources, but there are always trade--offs between noise,
-additional functionality, cost, and package size.
-
-The 6 ADC pins in a bank (D15--D20) generally have the least
-noise, and should be used for fine measurements.  If the input voltage
-changes relatively slowly, a number of samples can be taken in
-succession and averaged together, or the same voltage can even be
-sampled by multiple ADC pins at the same time.
-
-An important factor when taking a voltage reading is the reference
-voltages that the sample is being compared against. In the case of the
-Maple, the high reference is |vcc| and the low reference is ground.
-This means that noise or fluctuations on either |vcc| or ground will
-affect the measurement. It also means that the voltage you are trying
-to sample must be between ground and 3.3V.
+.. FIXME [0.0.12, Maple Native]
+
+The biggest issues with analog to digital conversion are noise and
+bias.  With the Maple line, we have tried to isolate the ADC pins and
+traces from strong noise sources, but there are always trade-offs
+between noise, additional functionality, cost, and package size.
+We've tried to enable good analog performance by isolating as many ADC
+pins as possible from digital noise on each board.
+
+More information on these isolated pins is available in each board's
+hardware documentation:
+
+* :ref:`Maple <maple-adc-bank>`
+* :ref:`Maple RET6 Edition <maple-ret6-adc-bank>`
+* :ref:`Maple Mini <maple-mini-adc-bank>`
+
+.. :ref:`Maple Native <maple-native-adc-bank>`
+
+That said, there are a number of more general things you can do to try
+to get good readings.  If your input voltage changes relatively
+slowly, a number of samples can be taken in succession and averaged
+together, or the same voltage can even be sampled by multiple ADC pins
+at the same time.
+
+Another important factor when taking a voltage reading is the
+reference voltages that the sample is being compared against. In the
+case of the Maple, the high reference is |vcc| and the low reference
+is ground.  This means that noise or fluctuations on either |vcc| or
+ground will affect the measurement. It also means that the voltage you
+are trying to sample must be between ground and 3.3 V.
 
 .. _adc-range:
 
 In the case of a variable reading, it is best if the voltage varies
-over the entire range of 0--3.3V; otherwise, only a fraction of the
-sensitivity is being leveraged.  Some basic tools to accomplish this
+over the entire range of 0 through 3.3 V; otherwise, only a fraction
+of the sensitivity is being used.  Some basic tools to accomplish this
 are `resistor dividers
 <http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener diodes
 <http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\
diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst
index ac065a4..ccb9afd 100644
--- a/source/external-interrupts.rst
+++ b/source/external-interrupts.rst
@@ -37,17 +37,20 @@ means that every pin on the Maple connects to what is called an *EXTI
 line*, and within an EXTI line, only one of the pins that connects to
 it can be used to detect external interrupts at a time.
 
+.. TODO [0.0.12] Maple Native links
+
 The EXTI Line Pin Map for your board lists which pins connect to which
 EXTI lines:
 
 * :ref:`Maple <maple-exti-map>`
 * :ref:`Maple RET6 Edition <maple-ret6-exti-map>`
+* :ref:`Maple Mini <maple-mini-exti-map>`
 
 .. note::
 
-   You should set the :ref:`pin mode <lang-pinmode>` of your
-   desired pin to an input mode (e.g ``INPUT`` or ``INPUT_FLOATING``,
-   ``INPUT_PULLUP``, ``INPUT_PULLDOWN``).
+   You should set the :ref:`pin mode <lang-pinmode>` of your desired
+   pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``,
+   ``INPUT_PULLDOWN``).
 
 Function Reference
 ------------------
diff --git a/source/gpio.rst b/source/gpio.rst
index 74be3d4..64ad494 100644
--- a/source/gpio.rst
+++ b/source/gpio.rst
@@ -20,19 +20,19 @@ Pin Maps
 The hardware documentation for your board lists each pin's
 capabilities, by pin number:
 
-.. TODO [0.1.0] Uncomment Mini and Native GPIO links
+.. TODO [0.0.12] Native link
 
 * :ref:`Maple <maple-gpios>`
 * :ref:`Maple RET6 Edition <maple-ret6-gpios>`
+* :ref:`Maple Mini <maple-mini-gpios>`
 
-.. * :ref:`Maple Mini <maple-mini-gpios>`
 .. * :ref:`Maple Native <maple-native-gpios>`
 
 The current and voltage limitations were determined using the STM32
 datasheets.  In particular, only some GPIO pins are **5V tolerant**,
 which means that applying 5 volts to a pin and reading it as input or
 allowing it to drain to ground will not damage that pin.  Connecting a
-voltage higher than 3.3V to a non-5V tolerant pin may damage your
+voltage higher than 3.3 V to a non-5 V tolerant pin may damage your
 board.
 
 .. _gpio-modes:
diff --git a/source/hardware/maple-mini.rst b/source/hardware/maple-mini.rst
index a8a4186..3e79ed0 100644
--- a/source/hardware/maple-mini.rst
+++ b/source/hardware/maple-mini.rst
@@ -1,6 +1,344 @@
-.. _hardware-maple-mini:
+.. _maple-mini:
 
 Maple Mini
 ==========
 
-Stub.
+This page is a general resource for information specific to the Maple
+Mini.  The Maple Mini is a smaller version of the Maple that fits on a
+breadboard.
+
+.. contents:: Contents
+   :local:
+
+.. TODO [dma.rst] Ref to dma.rst in sequel instead of libmaple-dma
+
+Technical Specifications
+------------------------
+
+* MCU: **STM32F103RCBT6**, a 32-bit ARM Cortex M3 microprocessor
+* Clock Speed: **72 MHz**
+* **128 KB Flash** and **20 KB SRAM**
+* 34 Digital I/O Pins (:ref:`gpio`)
+* 12 **PWM** pins at 16 bit resolution (:ref:`pwm`)
+* 9 analog input pins, 12 bit **ADC** resolution (:ref:`adc`)
+* 2 **SPI** peripherals (:ref:`spi`)
+* 2 **I2C** peripherals (:ref:`i2c`)
+* 7 Channels of Direct Memory Access (**DMA**) (:ref:`libmaple-dma`)
+* 3 **USART** peripherals (:ref:`usart`)
+* 1 advanced and 3 general-purpose **timers** (:ref:`timers`)
+* Dedicated **USB** port for programming and communications (:ref:`usb`)
+* **JTAG** (:ref:`jtag`)
+* Nested Vectored Interrupt Controller (NVIC) (including
+  :ref:`external interrupt <external-interrupts>` on GPIOs)
+* Supplies up to 500 mA at 3.3 V, with :ref:`separate 250 mA digital
+  and analog regulators <maple-mini-adc-bank>` for low-noise analog
+  performance
+* :ref:`Four layer design <maple-mini-hardware>`
+* Support for low power, sleep, and standby modes (<500 μA)
+* Operating Voltage: 3.3 V
+* Input Voltage (recommended): 3 V — 12 V
+* Dimensions: 2.02″ × 0.72″
+
+.. _maple-mini-powering:
+
+Powering the Maple Mini
+-----------------------
+
+You can power the Maple Mini via the USB plug or by powering Vin
+directly.
+
+.. warning:: The silkscreen on the Maple Mini suggests it will accept
+   an input voltage up to 16 V.  We recommend applying **no greater
+   than 12 V**.
+
+   See :ref:`this erratum <maple-mini-vin>` for more information.
+
+.. _maple-mini-gpios:
+
+GPIO Information
+----------------
+
+The Maple Mini features 34 total input/output pins, numbered ``D0``
+through ``D33``.  These numbers correspond to the numeric values next
+to each header on the Maple Mini's silkscreen.  However, some of them
+have special uses by default [#fusedpins]_.
+
+.. _maple-mini-usb-pins:
+
+Pin ``D23`` is the :ref:`USB <usb>` D+ line, and ``D24`` is the USB D-
+line.  To use them as GPIOs, your program will need to :ref:`disable
+SerialUSB <lang-serialusb-end>` first.  Be aware, however, that
+disabling SerialUSB means that the :ref:`bootloader <bootloader>`
+won't work properly, and you'll need to use
+:ref:`troubleshooting-perpetual-bootloader` to make your next upload.
+
+.. _maple-mini-but:
+
+Pin ``D32`` is the Mini's :ref:`button pin <lang-board-values-but>`.
+It is thus mainly useful as an :ref:`input <lang-pin-levels>`.  The
+pin will :ref:`read <lang-digitalread>` ``HIGH`` when the :ref:`button
+is pressed <lang-isbuttonpressed>`.
+
+.. _maple-mini-led:
+
+Pin ``D33`` is the Mini's :ref:`LED pin <lang-board-values-led>`.  It
+is thus mainly useful as an :ref:`output <lang-pin-levels>`.  The LED
+will glow when ``HIGH`` is :ref:`written <lang-digitalwrite>` to it.
+(It also supports :ref:`pwm`, for finer-grained brightness control).
+
+.. TODO [0.1.0] silkscreen pictures which expand abbreviations
+
+.. _maple-mini-pin-map-master:
+
+Master Pin Map
+^^^^^^^^^^^^^^
+
+This table shows a summary the available functionality on every GPIO
+pin, by peripheral type.  The "5 V?" column documents whether or not
+the pin is 5 volt tolerant.
+
+.. csv-table::
+   :header: Pin, :ref:`GPIO <gpio>`, :ref:`ADC <adc>`, :ref:`Timer <timers>`, :ref:`I2C <i2c>`, :ref:`UART <usart>`, :ref:`SPI <spi>`, 5 V?
+
+   D0,  PB11,   -, -,         2_SDA,  3_RX,  -,      Yes
+   D1,  PB10,   -, -,         2_SCL,  3_TX,  -,      Yes
+   D2,  PB2,    -, -,         -,      -,     -,      Yes
+   D3,  PB0,  CH8, 3_CH3,     -,      -,     -,      -
+   D4,  PA7,  CH7, 3_CH2,     -,      -,     1_MOSI, -
+   D5,  PA6,  CH6, 3_CH1,     -,      -,     1_MISO, -
+   D6,  PA5,  CH5, -,         -,      -,     1_SCK,  -
+   D7,  PA4,  CH4, -,         -,      2_CK,  1_NSS,  -
+   D8,  PA3,  CH3, 2_CH4,     -,      2_RX,  -,      -
+   D9,  PA2,  CH2, 2_CH3,     -,      2_TX,  -,      -
+   D10, PA1,  CH1, 2_CH2,     -,      2_RTS, -,      -
+   D11, PA0,  CH0, 2_CH1_ETR, -,      2_CTS, -,      -
+   D12, PC15,   -, -,         -,      -,     -,      -
+   D13, PC14,   -, -,         -,      -,     -,      -
+   D14, PC13,   -, -,         -,      -,     -,      -
+   D15, PB7,    -, 4_CH2,     1_SDA,  -,     -,      Yes
+   D16, PB6,    -, 4_CH1,     2_SCL,  -,     -,      Yes
+   D17, PB5,    -, -,         1_SMBA, -,     -,      -
+   D18, PB4,    -, -,         -,      -,     -,      Yes
+   D19, PB3,    -, -,         -,      -,     -,      Yes
+   D20, PA15,   -, -,         -,      -,     -,      Yes
+   D21, PA14,   -, -,         -,      -,     -,      Yes
+   D22, PA13,   -, -,         -,      -,     -,      Yes
+   D23, PA12,   -, 1_ETR,     -,      1_RTS, -,      Yes
+   D24, PA11,   -, 1_CH4,     -,      1_CTS, -,      Yes
+   D25, PA10,   -, 1_CH3,     -,      1_RX,  -,      Yes
+   D26, PA9,    -, 1_CH2,     -,      1_TX,  -,      Yes
+   D27, PA8,    -, 1_CH1,     -,      1_CK,  -,      Yes
+   D28, PB15,   -, -,         -,      -,     2_MOSI, Yes
+   D29, PB14,   -, -,         -,      3_RTS, 2_MISO, Yes
+   D30, PB13,   -, -,         -,      3_CTS, 2_SCK,  Yes
+   D31, PB12,   -, 1_BKIN,    2_SMBA, 3_CK,  2_NSS,  Yes
+   D32, PB8,    -, 4_CH3,     -,      -,     -,      Yes
+   D33, PB1,  CH9, 3_CH4,     -,      -,     -,      -
+
+.. _maple-mini-timer-map:
+
+Timer Pin Map
+^^^^^^^^^^^^^
+
+The following table shows what pins are associated with a particular
+timer's capture/compare channels.
+
+.. csv-table::
+   :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4
+   :delim: |
+
+   1 | D27 | D26 | D25                         | D24
+   2 | D11 | D10 | D9                          | D8
+   3 | D5  | D4  | D3                          | :ref:`D33 <maple-mini-led>`
+   4 | D16 | D15 | :ref:`D32 <maple-mini-but>` |
+
+.. _maple-mini-exti-map:
+
+EXTI Line Pin Map
+^^^^^^^^^^^^^^^^^
+
+The following table shows which pins connect to which :ref:`EXTI lines
+<external-interrupts-exti-line>` on the Maple.
+
+.. list-table::
+   :widths: 1 1
+   :header-rows: 1
+
+   * - EXTI Line
+     - Pins
+   * - EXTI0
+     - 3, 11
+   * - EXTI1
+     - 10, 33
+   * - EXTI2
+     - 2, 9
+   * - EXTI3
+     - 8, 19
+   * - EXTI4
+     - 7, 18
+   * - EXTI5
+     - 6, 17
+   * - EXTI6
+     - 5, 16
+   * - EXTI7
+     - 4, 15
+   * - EXTI8
+     - 27, 32
+   * - EXTI9
+     - 26
+   * - EXTI10
+     - 1, 25
+   * - EXTI11
+     - 0, 24
+   * - EXTI12
+     - 23, 31
+   * - EXTI13
+     - 14, 22, 30
+   * - EXTI14
+     - 13, 21, 29
+   * - EXTI15
+     - 12, 20, 28
+
+.. _maple-mini-usart-map:
+
+USART Pin Map
+^^^^^^^^^^^^^
+
+The Maple RET6 Edition has three serial ports whose pins are broken
+out to headers (also known as :ref:`USARTs <usart>`). They communicate
+using the pins summarized in the following table:
+
+.. csv-table::
+   :header: Serial Port, TX, RX, CK, CTS, RTS
+   :delim: |
+
+   ``Serial1`` | 26 | 25 | 27 | 24 | 23
+   ``Serial2`` | 9  |  8 |  7 | 11 | 10
+   ``Serial3`` | 1  |  0 | 31 | 30 | 29
+
+.. _maple-mini-adc-bank:
+
+Low-Noise ADC Pins
+^^^^^^^^^^^^^^^^^^
+
+Analog input pins D4 — D11 on the Maple Mini generally offer
+lower-noise ADC performance than D3.  If you’re concerned about
+getting good ADC readings, we recommend using one of these pins to
+take your measurements.
+
+Maple Mini has an electrically isolated analog power plane with its
+own regulator, and a geometrically isolated ground plane, connected to
+the digital plane by an inductor.  Pins D4 — D11 are laid out to
+correspond with these analog planes, and our measurements indicate
+that they generally have the lowest noise of all the analog lines.
+However, analog performance may vary depending upon the activity of
+the other GPIOs.  Consult the :ref:`Maple Mini hardware design files
+<maple-mini-hardware>` for more details.
+
+.. _maple-mini-board-values:
+
+Board-Specific Values
+---------------------
+
+This section lists the Maple Mini's :ref:`board-specific values
+<lang-board-values>`.
+
+- ``CYCLES_PER_MICROSECOND``: 72
+- ``BOARD_BUTTON_PIN``: 32
+- ``BOARD_LED_PIN``: 33
+- ``BOARD_NR_GPIO_PINS``: 34
+- ``BOARD_NR_PWM_PINS``: 12
+- ``boardPWMPins``: 3, 4, 5, 8, 9, 10, 11, 15, 16, 25, 26, 27
+- ``BOARD_NR_ADC_PINS``: 9
+- ``boardADCPins``: 3, 4, 5, 6, 7, 8, 9, 10, 11
+- ``BOARD_NR_USED_PINS``: 4
+- ``boardUsedPins``: ``BOARD_LED_PIN``, ``BOARD_BUTTON_PIN``, 23, 24
+  (23 and 24 are used by :ref:`USB <maple-mini-usb-pins>`)
+- ``BOARD_NR_USARTS``: 3
+- ``BOARD_USART1_TX_PIN``: 26
+- ``BOARD_USART1_RX_PIN``: 25
+- ``BOARD_USART2_TX_PIN``: 9
+- ``BOARD_USART2_RX_PIN``: 8
+- ``BOARD_USART3_TX_PIN``: 1
+- ``BOARD_USART3_RX_PIN``: 0
+- ``BOARD_NR_SPI``: 2
+- ``BOARD_SPI1_NSS_PIN``: 7
+- ``BOARD_SPI1_MOSI_PIN``: 4
+- ``BOARD_SPI1_MISO_PIN``: 5
+- ``BOARD_SPI1_SCK_PIN``: 6
+- ``BOARD_SPI2_NSS_PIN``: 31
+- ``BOARD_SPI2_MOSI_PIN``: 28
+- ``BOARD_SPI2_MISO_PIN``: 29
+- ``BOARD_SPI2_SCK_PIN``: 30
+- ``BOARD_JTMS_SWDIO_PIN``: 22
+- ``BOARD_JTCK_SWCLK_PIN``: 21
+- ``BOARD_JTDI_PIN``: 20
+- ``BOARD_JTDO_PIN``: 19
+- ``BOARD_NJTRST_PIN``: 18
+
+.. _maple-mini-hardware:
+
+Hardware Design Files
+---------------------
+
+The hardware schematics and board layout files are available in the
+`Maple Mini GitHub repository <https://github.com/leaflabs/maplemini>`_
+
+From the GitHub repository main page, you can download the entire
+repository by clicking the "Download" button.  If you are familiar
+with `Git <http://git-scm.com/>`_, you can also clone the repository
+at the command line with ::
+
+    $ git clone git://github.com/leaflabs/maplemini.git
+
+Failure Modes
+-------------
+
+The following known failure modes apply to all Maple boards.  The
+failure modes aren't design errors, but are easy ways to break or
+damage your board permanently.
+
+* **High voltage on non-tolerant pins**: not all header pins are 5 V
+  compatible; so e.g. connecting certain serial devices in the wrong
+  way could over-voltage the pins.  The :ref:`pin-mapping master table
+  <maple-mini-pin-map-master>` details which pins are 5 V-tolerant.
+
+Errata
+------
+
+This section lists known issues and warnings for the Maple Mini Rev 2
+(the first Rev sold to the public).
+
+.. _maple-mini-vin:
+
+* **Silkscreen Vin voltage mistake**: The silkscreen on the Maple Mini
+  falsely indicates that Vin may be supplied with up to 16 V.  We
+  recommend an input voltage **no greater than 12 V**.
+
+  The voltage regulator on the Mini is rated up to 16 V.  However, our
+  tests indicate that as its input voltage approaches 16 V, its output
+  begins to rise to levels higher than those recommended by ST for
+  supplying the STM32F103CB.  The limit of 12 V keeps the voltage
+  supplied to the processor at safe levels.
+
+Recommended Reading
+-------------------
+
+STMicro documentation for STM32F103CB microcontroller:
+
+* `Datasheet
+  <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00161566.pdf>`_
+  (PDF); covers STM32F103x8, STM32F103xB.
+* `Reference Manual RM0008
+  <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_
+  (PDF); general, definitive resource for STM32F1 line.
+* `Programming Manual PM0056
+  <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/PROGRAMMING_MANUAL/CD00228163.pdf>`_
+  (PDF); assembly language and register reference.
+* `STM32F103CB <http://www.st.com/internet/mcu/product/189782.jsp>`_
+  overview page with links to further references.
+
+.. rubric:: Footnotes
+
+.. [#fusedpins] See :ref:`boardUsedPins <lang-board-values-used-pins>`
+   for more information.
diff --git a/source/index.rst b/source/index.rst
index ce3985f..d17c4db 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -67,11 +67,7 @@ Have fun!
 
    hardware/maple.rst
    hardware/maple-ret6.rst
+   hardware/maple-mini.rst
 
 .. TODO write/include these upon Mini and Native release
-
-.. .. toctree::
-..    :hidden:
-
-..    hardware/maple-mini.rst
 ..    hardware/maple-native.rst
diff --git a/source/lang/api/hardwarespi.rst b/source/lang/api/hardwarespi.rst
index a80e429..054d1a8 100644
--- a/source/lang/api/hardwarespi.rst
+++ b/source/lang/api/hardwarespi.rst
@@ -43,7 +43,7 @@ Turning the SPI Port On
 Now it's time to turn your SPI port on.  Do this with the ``begin()``
 function (an example is given below).
 
-.. FIXME [0.0.11] Breathe doesn't include the class; fix & submit pull req
+.. FIXME [Breathe] Output doesn't include the class; fix & submit pull req
 
 .. doxygenfunction:: HardwareSPI::begin
 
diff --git a/source/timers.rst b/source/timers.rst
index 403193f..e23579d 100644
--- a/source/timers.rst
+++ b/source/timers.rst
@@ -77,11 +77,17 @@ your program.
 PWM Conflicts
 ^^^^^^^^^^^^^
 
-Because PWM functionality on a given pin depends on
-the configuration of the timer and channel, you must chose your
-channels carefully if you want to use both timer interrupts and PWM in
-the same program.  Refer to your board's :ref:`Timer Pin Map
-<gpio-pin-maps>` to match up timer channels and pin numbers.
+Because PWM functionality on a given pin depends on the configuration
+of the timer and channel, you must chose your channels carefully if
+you want to use both timer interrupts and PWM in the same program.
+Refer to your board's timer pin map to match up timer channels and pin
+numbers:
+
+.. TODO [0.0.12] Native links
+
+* :ref:`Maple <maple-timer-map>`
+* :ref:`Maple RET6 Edition <maple-ret6-timer-map>`
+* :ref:`Maple Mini <maple-mini-timer-map>`
 
 Overhead
 ^^^^^^^^
diff --git a/source/usart.rst b/source/usart.rst
index b3e1ea1..8766e3f 100644
--- a/source/usart.rst
+++ b/source/usart.rst
@@ -9,8 +9,7 @@ USART
 Hardware/Circuit Design
 -----------------------
 
-.. FIXME [0.0.12/Maple Native] UART4 and UART5, Native links
-.. FIXME [0.0.11] Mini info and links
+.. TODO [0.0.12/Maple Native] UART4 and UART5, Native links
 
 Each LeafLabs board has at least 3 separate USART devices. In the most
 simple use case, the RX and TX pins are used to send data at a
@@ -24,6 +23,7 @@ available here:
 
 * :ref:`Maple <maple-usart-map>`
 * :ref:`Maple RET6 Edition <maple-ret6-usart-map>`
+* :ref:`Maple Mini <maple-mini-usart-map>`
 
 If you use a particular serial port, you cannot also use its
 communication pins for other purposes at the same time.