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.