Board-specific values; corresponding QA test generalizations.

Various board-specific #defines and arrays of pins added.

For the changelog (some of this information predates this commit):

* wirish/boards.h now declares the following arrays of pin numbers:

      * boardPWMPins - PWM-capable pins
      * boardADCPins - ADC-capable pins
      * boardUsedPins - pins already in use, e.g. BOARD_BUTTON_PIN

  It also declares a bool boardUsesPin(uint8 pin) function for
  convenient testing of whether a pin is in use.

* wirish/boards/*.h now define:

      * BOARD_USART1_TX_PIN
      * BOARD_USART1_RX_PIN
      * BOARD_USART2_TX_PIN
      * BOARD_USART2_RX_PIN
      * BOARD_USART3_TX_PIN
      * BOARD_USART3_RX_PIN
      * BOARD_NR_GPIO_PINS (renamed from NR_GPIO_PINS)
      * BOARD_NR_USARTS (renamed from NR_USARTS)
      * BOARD_NR_PWM_PINS
      * BOARD_NR_ADC_PINS
      * BOARD_NR_USED_PINS

* wirish/boards/maple_native.h now defines:

      * BOARD_UART4_TX_PIN
      * BOARD_UART4_RX_PIN
      * BOARD_UART5_TX_PIN
      * BOARD_UART5_RX_PIN

  (Unfortunately, wirish/boards/maple_RET6.h cannot, since at least
  one of the UART4/UART5 pins are used already; this will require layout
  changes for a wide-release Maple form factor RET6 board).

* wirish/boards/*.cpp all include the corresponding array definitions.
  They all live in flash by default, thanks to the new __FLASH__ macro
  in wirish/wirish_types.h, which is a synonym for the existing __attr_flash
  #define in libmaple/libmaple_types.h.

The documentation was updated to include this information.  It also
gained various FIXME/TODO comments related to its generalization
across boards.

The quality assurance-related examples (examples/qa-slave-shield.cpp
and examples/test-session.cpp) now make heavy use of board-specific
values to ensure portability.

9 files changed, 227 insertions, 31 deletions

diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst
index 35c6fbc..7099b69 100644
--- a/docs/source/lang/api/analogread.rst
+++ b/docs/source/lang/api/analogread.rst
@@ -35,6 +35,8 @@ have to do this once, so it's usually done in :ref:`lang-setup`\ ).
 Parameter Discussion
 --------------------
 
+.. FIXME generalize Maple-specific information
+
 The pin parameter is the number of the analog input pin to read from.
 Header pins on the Maple with ADC functionality (marked as "AIN" on
 the silkscreen) are:
@@ -49,24 +51,25 @@ Note
 ----
 
 If the analog input pin is not connected to anything, the value
-returned by analogRead() will fluctuate based on a number of factors
-(e.g. the values of the other analog inputs, how close your hand is to
-the board, etc.) in a seemingly random way.
+returned by ``analogRead()`` will fluctuate due to a number of reasons
+(like the values of the other analog inputs, how close your hand is to
+the board, etc.) in a "random" way.
 
 
 Example
 -------
 
- ::
+::
 
+    int analogPin = 3;     // Potentiometer wiper (middle terminal) connected
+                           // to analog pin 3. outside leads to ground and +3.3V.
+                           // You may have to change this value if your board
+                           // cannot perform ADC conversion on pin 3.
 
-    int analogPin = 3;     // potentiometer wiper (middle terminal) connected
-                           // to analog pin 3. outside leads to ground and +3.3V
     int val = 0;           // variable to store the value read
 
     void setup() {
       pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input
-      SerialUSB.begin();                // set up usb virtual COM port
     }
 
     void loop() {
@@ -97,23 +100,27 @@ shift <lang-bitshift>` the value of a Maple readout by 2, like so::
     // be aware that you're losing a lot of precision if you do this
     int adc_reading = analogRead(pin) >> 2;
 
+.. FIXME Mention Native can do analogReference(), when it's time
+
 On the Arduino, the input range and resolution can be changed using
 their implementation of `analogReference()
 <http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the
 way its hardware (as of Rev 5) was designed, it's not possible to
 implement analogReference on the Maple, so this function doesn't
 exist.  If your inputs lie in a different voltage range than 0V--3.3V,
-you'll need to bring them into that range before using analogRead.
-Some basic tools to accomplish this are `resistor dividers
-<http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener diodes
+you'll need to bring them into that range before using
+``analogRead()``.  Some basic tools to accomplish this are `resistor
+dividers <http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener
+diodes
 <http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\
-. However, opamps and other powered components can also be used if
-greater precision is required.
+. However, `operational amplifiers
+<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other
+powered components can also be used if greater precision is required.
 
 See also
 --------
 
-- :ref:`ADC note <adc>`
+- :ref:`ADC tutorial <adc>`
 - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
 
 .. include:: cc-attribution.txt
diff --git a/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst
new file mode 100644
index 0000000..367adbb
--- /dev/null
+++ b/docs/source/lang/api/board-values.rst
@@ -0,0 +1,155 @@
+.. _lang-board-values:
+
+Board-Specific Constants
+========================
+
+There are a number of board-specific values: constants or variables
+which are different depending on which LeafLabs board you have.
+
+This page lists and documents the board-specific values.  You should
+use these when appropriate in your own programs.  This will help make
+it easier to share your code with other people who have different
+boards.  Some example usages are given :ref:`below
+<lang-board-values-examples>`.
+
+.. contents:: Contents
+   :local:
+
+Constants
+---------
+
+- ``CYCLES_PER_MICROSECOND``: Number of CPU cycles per microsecond on
+  your board.
+
+.. _lang-board-values-but:
+
+- ``BOARD_BUTTON_PIN``: Pin connected to the built-in button (labeled
+  "BUT" on your board's silkscreen).
+
+.. _lang-board-values-led:
+
+- ``BOARD_LED_PIN``: Pin connected to the built-in LED.
+
+- ``BOARD_NR_GPIO_PINS``: Total number of :ref:`GPIO pins <gpio>` that
+  are broken out to headers.  Some of these might already be connected
+  to external hardware (like the built-in LED and button).  To find
+  out if a pin is in use, see :ref:`boardUsesPin()
+  <lang-boardusespin>` (and also :ref:`boardUsedPins
+  <lang-board-values-used-pins>`).
+
+.. _lang-board-values-nr-pwm-pins:
+
+- ``BOARD_NR_PWM_PINS``: Total *number* of GPIO pins that can be used
+  for :ref:`PWM <pwm>`.  The actual *pins* that can do PWM are in the
+  :ref:`boardPWMPins <lang-board-values-pwm-pins>` array.
+
+.. _lang-board-values-nr-adc-pins:
+
+- ``BOARD_NR_ADC_PINS``: Total number of GPIO pins that can be used
+  for :ref:`analog-to-digital conversion <adc>`.  The actual pins that
+  can do ADC conversion are in the :ref:`boardADCPins
+  <lang-board-values-adc-pins>` array.
+
+.. _lang-board-values-nr-used-pins:
+
+- ``BOARD_NR_USED_PINS``: Total number of GPIO pins that are already
+  connected to some external hardware (like a built-in LED) on the
+  board.  The actual pins that that are already used are in the
+  :ref:`boardUsedPins <lang-board-values-used-pins>` array.  To see if
+  a pin is already in use, use the :ref:`boardUsesPin()
+  <lang-boardusespin>` function.
+
+.. _lang-board-values-usart:
+
+- USART (serial port) related constants:
+
+    * ``BOARD_USART1_TX_PIN``, ``BOARD_USART2_TX_PIN``, ``BOARD_USART3_TX_PIN``:
+      TX pins for the 3 USARTS.
+
+    * ``BOARD_USART1_RX_PIN``, ``BOARD_USART2_RX_PIN``, ``BOARD_USART3_RX_PIN``:
+      RX pins for the 3 USARTS.
+
+    * ``BOARD_UART4_TX_PIN``, ``BOARD_UART5_TX_PIN``: TX pins for
+      UARTs 4 and 5 (high-density boards like Maple Native only).
+
+    * ``BOARD_UART4_RX_PIN``, ``BOARD_UART5_RX_PIN``: RX pins for
+      UARTs 4 and 5 (high-density boards like Maple Native only).
+
+    * ``BOARD_NR_USARTS``: Number of serial ports on the board.  This
+      number includes UARTs 4 and 5 if they are available.
+
+.. _lang-board-values-pwm-pins:
+.. _lang-board-values-adc-pins:
+.. _lang-board-values-used-pins:
+
+Pin Arrays
+----------
+
+Some :ref:`arrays <lang-array>` of pin numbers are available which you
+can use to find out certain important information about a given pin.
+
+.. TODO add links to the board-specific hardware information on what
+.. are in these arrays
+
+- ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM
+  <pwm>` output, using :ref:`pwmWrite() <lang-pwmwrite>`.  The total
+  number of these pins is :ref:`BOARD_NR_PWM_PINS
+  <lang-board-values-nr-pwm-pins>`.
+
+- ``boardADCPins``: Pin numbers of each pin capable of :ref:`ADC
+  <adc>` conversion, using :ref:`analogRead() <lang-analogread>`.  The
+  total number of these pins is :ref:`BOARD_NR_ADC_PINS
+  <lang-board-values-nr-adc-pins>`.
+
+- ``boardUsedPins``: Pin numbers of each pin that, by default, is used
+  for some special purpose by the board.  The total number of these
+  pins is :ref:`BOARD_NR_USED_PINS <lang-board-values-nr-used-pins>`.
+  To check if a pin is used for a special purpose, use
+  :ref:`boardUsesPin() <lang-boardusespin>`.
+
+.. _lang-board-values-examples:
+
+Examples
+--------
+
+:ref:`BOARD_LED_PIN <lang-board-values-led>` On the Maple, the
+built-in LED is connected to pin 13.  On the Maple Mini, however, it
+is connected to pin 33.  You can write a "blinky" program that works
+on all LeafLabs boards using ``BOARD_LED_PIN`` and :ref:`toggleLED()
+<lang-toggleled>`::
+
+    void setup() {
+        pinMode(BOARD_LED_PIN, OUTPUT);
+    }
+
+    void loop() {
+        toggleLED();
+        delay(100);
+    }
+
+:ref:`BOARD_BUTTON_PIN <lang-board-values-but>`: Similarly, you can
+write a single program that prints a message whenever the button is
+pressed which will work on all LeafLabs boards using
+``BOARD_BUTTON_PIN`` and :ref:`isButtonPressed()
+<lang-isbuttonpressed>`::
+
+    void setup() {
+        pinMode(BOARD_BUTTON_PIN, INPUT);
+    }
+
+    void loop() {
+        if (isButtonPressed()) {
+            SerialUSB.println("You pressed the button!");
+        }
+    }
+
+See Also
+--------
+
+- :ref:`lang-boardusespin`
+- :ref:`lang-isbuttonpressed`
+- :ref:`lang-waitforbuttonpress`
+- :ref:`lang-pinmode`
+- :ref:`lang-toggleled`
+- :ref:`lang-analogread`
+- :ref:`lang-pwmwrite`
diff --git a/docs/source/lang/api/boardusespin.rst b/docs/source/lang/api/boardusespin.rst
new file mode 100644
index 0000000..8dc4c64
--- /dev/null
+++ b/docs/source/lang/api/boardusespin.rst
@@ -0,0 +1,27 @@
+.. highlight:: cpp
+
+.. _lang-boardusespin:
+
+boardUsesPin()
+==============
+
+Each LeafLabs board connects some pins to external hardware.  The most
+important examples of this are the built-in LED and button.  You can
+check if a board uses a particular pin using this function.
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: boardUsesPin
+
+See Also
+--------
+
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`boardUsedPins <lang-board-values-used-pins>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
+- :ref:`toggleLED() <lang-toggleled>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
+- :ref:`isButtonPressed() <lang-isbuttonpressed>`
+- :ref:`waitForButtonPress() <lang-waitforbuttonpress>`
+
diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst
index 2e968e7..c5a7c0c 100644
--- a/docs/source/lang/api/constants.rst
+++ b/docs/source/lang/api/constants.rst
@@ -293,23 +293,16 @@ exponent indicators.  Some examples are given in the following table:
 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.
+There are several :ref:`board-specific constants <lang-board-values>`
+whose value depends on which LeafLabs board you have.  If you use
+them, it will help make sure that your code will work well on all
+LeafLabs boards, not just the one you have.  This will make it much
+easier to share your code with others.
 
-.. 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.
+For example, the pin number connected to the board's built-in LED is
+different on the different boards, but the board-specific constant
+:ref:`BOARD_LED_PIN <lang-board-values-led>` will always be the
+correct value for each board.
 
 See Also
 --------
@@ -325,5 +318,6 @@ See Also
 - :ref:`unsigned long long <lang-unsignedlonglong>`
 - :ref:`float <lang-float>`
 - :ref:`double <lang-double>`
+- :ref:`Board-Specific Values <lang-board-values>`
 
 .. include:: cc-attribution.txt
diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst
index c7a630d..3f086ca 100644
--- a/docs/source/lang/api/hardwaretimer.rst
+++ b/docs/source/lang/api/hardwaretimer.rst
@@ -10,6 +10,12 @@ built-in timer peripherals.  More information on these peripherals
 (including code examples) is available in the :ref:`timers reference
 <timers>`.
 
+.. FIXME update HardwareTimer documentation after redoing it in terms
+.. of the new timer interface.
+
+.. warning:: This class has been deprecated.  It is not available in
+   the current build.
+
 Library Documentation
 ---------------------
 
diff --git a/docs/source/lang/api/isbuttonpressed.rst b/docs/source/lang/api/isbuttonpressed.rst
index dbff0c9..8c350b9 100644
--- a/docs/source/lang/api/isbuttonpressed.rst
+++ b/docs/source/lang/api/isbuttonpressed.rst
@@ -4,7 +4,8 @@ isButtonPressed()
 =================
 
 Check whether the board's built-in button (labeled BUT on the
-silkscreen) is pressed.
+silkscreen) is pressed.  The pin number of the built-in button is
+given by the constant ``BOARD_BUTTON_PIN``.
 
 Library Documentation
 ---------------------
@@ -14,4 +15,6 @@ Library Documentation
 See Also
 --------
 
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
 - :ref:`lang-waitforbuttonpress`
diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst
index 9d50077..cea602b 100644
--- a/docs/source/lang/api/pwmwrite.rst
+++ b/docs/source/lang/api/pwmwrite.rst
@@ -11,6 +11,8 @@ pwmWrite(), the pin will output a steady square wave with the given
 duty cycle.  You can change the duty cycle later by calling pwmWrite()
 again with the same pin and a different duty.
 
+.. FIXME board-specific information
+
 On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8,
 9, 11, 12, 14, 24, 27, and 28.
 
diff --git a/docs/source/lang/api/toggleled.rst b/docs/source/lang/api/toggleled.rst
index 0cc20c2..54a7d64 100644
--- a/docs/source/lang/api/toggleled.rst
+++ b/docs/source/lang/api/toggleled.rst
@@ -13,5 +13,5 @@ Library Documentation
 See Also
 --------
 
-- :ref:`BOARD_LED_PIN <lang-constants-led>`
+- :ref:`BOARD_LED_PIN <lang-board-values-led>`
 - :ref:`togglePin() <lang-togglepin>`
diff --git a/docs/source/lang/api/waitforbuttonpress.rst b/docs/source/lang/api/waitforbuttonpress.rst
index 34c5066..a5bd45c 100644
--- a/docs/source/lang/api/waitforbuttonpress.rst
+++ b/docs/source/lang/api/waitforbuttonpress.rst
@@ -14,4 +14,6 @@ Library Documentation
 See Also
 --------
 
+- :ref:`Board-specific values <lang-board-values>`
+- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>`
 - :ref:`lang-isbuttonpressed`