0.0.10 Documentation checkpoint.

The vast majority of the Maple-specific values have been pulled out of
the higher-level overview pages and replaced with refs into documents
under /docs/source/hardware/.

Much of the work that's left to be done in this regard is labeled with
versioned TODO and FIXME comments.

Suggestions from StephenFromNYC and gbulmer were incorporated from
this forum thread:

      http://forums.leaflabs.com/topic.php?id=703

1 files changed, 55 insertions, 4 deletions

diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst
index 475f7dd..891f151 100644
--- a/docs/source/libs/servo.rst
+++ b/docs/source/libs/servo.rst
@@ -2,9 +2,8 @@
 
 .. _libs-servo:
 
-=======
- Servo
-=======
+Servo
+=====
 
 .. FIXME [0.0.10] this is out of date
 
@@ -16,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
 ---------------------
@@ -108,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.