Merge branch 'refactor'

This merges the libmaple refactor work into master.  The contents of
libmaple proper (/libmaple/) are almost completely incompatible with
previous APIs in master.  See /docs/source/libmaple/overview.rst for
more information on the new design.

Wirish incompatibilities are limited to the HardwareTimer class;
however, there are several new deprecations, most likely to be removed
in 0.1.0.

2 files changed, 161 insertions, 4 deletions

diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst
index f92fd91..891f151 100644
--- a/docs/source/libs/servo.rst
+++ b/docs/source/libs/servo.rst
@@ -2,9 +2,10 @@
 
 .. _libs-servo:
 
-=======
- Servo
-=======
+Servo
+=====
+
+.. FIXME [0.0.10] this is out of date
 
 This documents the Servo library for controlling RC servomotors.  It
 is implemented as a thin layer over the built-in :ref:`timer
@@ -14,7 +15,8 @@ You can use this library in the :ref:`IDE <ide>` by choosing the Servo
 item under the Sketch > Import Library... menu.
 
 If you are using the :ref:`Unix toolchain <unix-toolchain>`, the
-library is located in ``$LIB_MAPLE_HOME/libraries/Servo/``.
+library is located in the ``/libraries/Servo/`` :ref:`libmaple`
+directory.
 
 Servo Class Reference
 ---------------------
@@ -106,3 +108,54 @@ servomotor attached to pin 9, you could write ::
    microseconds.  This will be clamped to lie in the [``min``,
    ``max``\ ] pulse width range set during :ref:`attach()
    <libs-servo-attach>`.
+
+Arduino Compatibility
+---------------------
+
+The Servo class provides a public interface identical to the Arduino
+version's documented functionality (as of Arduino 0021), so in most
+cases, this library will be a drop-in replacement.
+
+However, there are some differences, essentially at the level of
+implementation details.
+
+The major difference is that while the Arduino implementation drives
+the servos with "bit-banged" :ref:`PWM <pwm>`, the Maple
+implementation uses :ref:`timers <timers>` to drive the PWM directly.
+
+Consequently, **the Maple implementation only allows Servo instances
+to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**.
+
+To determine if a pin supports PWM (15 Maple pins do), you can either
+check if "PWM" appears next to its number on the Maple silkscreen, or
+consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation.
+
+RC Servos expect a pulse approximately every 20ms.  In the Maple
+implementation, :ref:`periods <lang-hardwaretimer-setperiod>` are set
+for entire timers, rather than individual channels.  Thus,
+``attach()``\ ing a Servo to a pin can interfere with other pins
+associated with the same timer\ [#fard-servo]_.
+
+Because of this, we recommend connecting multiple servomotors to pins
+which share a timer, in order to keep as many timers free for other
+purposes as possible.  Consult your board's :ref:`Timer Pin Map
+<gpio-pin-maps>` to match up pins and timer channels.
+
+Another difference: although it is not publicly documented to do so,
+the Arduino implementation of `attach()
+<http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer
+channel associated with the newly-attached pin, or 0 on failure (as of
+Arduino 0021).  The Maple implementation returns :ref:`true
+<lang-constants-true>` on success, and :ref:`false
+<lang-constants-false>` on failure (and this is its documented
+behavior).
+
+We currently provide a soft (bit-banged) implementation of the
+:ref:`Wire <libs-wire>` I2C library.
+
+.. rubric:: Footnotes
+
+.. [#fard-servo] The Arduino implementation also captures timer
+   channels in groups as more Servo objects are attached, but the
+   details of which channels have their periods reset when are
+   slightly different.
diff --git a/docs/source/libs/wire.rst b/docs/source/libs/wire.rst
new file mode 100644
index 0000000..2c5bed9
--- /dev/null
+++ b/docs/source/libs/wire.rst
@@ -0,0 +1,104 @@
+.. highlight:: cpp
+
+.. _libs-wire:
+
+Wire
+====
+
+.. TODO [0.1.0] Format this correctly, using Breathe
+
+This page documents the Wire library for the :ref:`i2c` protocol.  You
+can use this library in the :ref:`Maple IDE <ide>` by choosing the
+Wire item under the Sketch > Import Library... menu.
+
+If you are using the :ref:`Unix toolchain <unix-toolchain>`, the
+library is located in the ``/libraries/Wire/`` :ref:`libmaple`
+directory.
+
+Wire Function Reference
+-----------------------
+
+``Wire.begin()``
+    Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL
+    (this is compatible with the pin settings on the Arduino Mega).
+
+``Wire.begin(sda, scl)``
+    Like ``Wire.begin()``, but with the given pins as SDA and
+    SCL.
+
+``Wire.beginTransmission(slave_address)``
+    Set up a transmission to a slave device with the given (7-bit)
+    address. Bytes subsequently queued for transmission (using
+    ``Wire.send``) will be sent to ``slave_address`` when ``void
+    Wire.endTransmission()`` is called.
+
+``void Wire.send(byte)``
+    Queues the given byte (``uint8`` or ``int``) to the slave address
+    previously specified by a call to ``Wire.beginTransmission``. At
+    most 32 bytes may be queued in a single transmission.
+
+``Wire.send(string)``
+    Queues a given string (``char*``) for transmission. The characters
+    of the string are individually queued for transmission as
+    bytes. At most 32 bytes may be queued in a single transmission.
+
+``Wire.send(buffer, length)``
+    Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with
+    ``length`` elements, for transmission. At most 32 bytes may be
+    queued in a single transmission.
+
+``Wire.endTransmission()``
+    Ends a transmission (begun by ``Wire.beginTransmission(uint8)``),
+    and actually sends the bytes queued by calls to Wire.send.
+
+    The return value is one of the following status codes:
+
+    * ``SUCCESS``: All bytes were transmitted successfully.
+
+    * ``EDATA``: More than 32 bytes were queued for transmission. No
+      bytes are actually sent when this happens.
+
+    * ``ENACKADDR``: Did not receive ACK on transmit of address. No
+      bytes are actually sent when this happens.
+
+    * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some
+      bytes may have been sent when this happens; however, the
+      transmission is aborted after the first byte of data which is
+      not ACKed by the slave device.
+
+    * ``EOTHER``: Other error occurred.
+
+``Wire.requestFrom(address, num_bytes)``
+    Requests ``num_bytes`` bytes from 7-bit slave address
+    address. Returns the actual number of bytes read. These bytes may
+    subsequently be read one at a time using ``Wire.receive()``.
+
+    Note: if ``num_bytes`` exceeds the size of the transmit/receive
+    buffer (currently 32), it will be truncated to 32.
+
+``Wire.receive()``
+    Get and return the next byte read during the previous call to
+    ``Wire.requestFrom(uint8, int)``. You can check how many bytes are
+    left to read using ``uint8 Wire.available()``.
+
+``Wire.available()``
+    Returns the number of bytes which are still available for reading
+    (with ``Wire.receive()``) from the last call to
+    ``Wire.requestFrom(uint8, int)``.
+
+Arduino Compatibility
+---------------------
+
+.. FIXME [0.1.0] Replace this section when i2c Wire wrapper is done
+
+This implementation is synchronous, and thus supports only a subset of
+the full Wire interface (however, the functionality which is supported
+is fully compatible with Arduino). For now, please use the function
+reference which follows when developing projects using our
+implementation.
+
+Please note that the current implementation only supports master mode
+using a bit-banged (software) protocol.  For now, use of the hardware
+:ref:`i2c` peripheral is only available through :ref:`libmaple-i2c`.
+
+