merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 92 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.