2 files changed, 196 insertions, 0 deletions
diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst
new file mode 100644
index 0000000..80288c6
--- /dev/null
+++ b/docs/source/libs/servo.rst
@@ -0,0 +1,92 @@
+.. highlight:: cpp
+
+.. _libs-servo:
+
+Servo
+=====
+
+This documents the Servo library for controlling RC servomotors.  It
+is implemented as a thin layer over the built-in :ref:`timer
+peripherals <timers>`.
+
+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 the ``/libraries/Servo/`` :ref:`libmaple`
+directory.
+
+.. contents:: Contents
+   :local:
+
+Servo Class Reference
+---------------------
+
+You can construct a Servo object by including the declaration ::
+
+     Servo servo;
+
+in your sketch.  This will create a Servo object called ``servo``.
+You can then use any of its methods; for instance, to control a
+servomotor attached to pin 9, you could write ::
+
+     servo.attach(9);
+
+.. doxygenclass:: Servo
+   :members:
+
+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
+servos with "bit-banged" PWM (in the sense that timer interrupt
+handlers are used to manually toggle pins), the Maple implementation
+uses :ref:`timers <timers>` to drive the PWM directly.
+
+Consequently, **the Maple implementation only allows Servo instances
+to attach to pins that support PWM**.
+
+To determine if a pin supports PWM, you can either check if "PWM"
+appears next to its number on your board's silkscreen, or look for it
+in the list of :ref:`boardPWMPins <lang-board-values-pwm-pins>` in
+your board's :ref:`hardware documentation <index-boards>`.
+
+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.
+
+And here's some fine print:
+
+- 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).
+
+- In another bit of undocumented behavior, the Arduino implementation
+  of write() also treats its argument as an angle or a pulse width
+  depending on its value.  This is a bad idea, and we don't do it.
+
+.. 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`.
+
+