aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/Doxyfile3
-rw-r--r--docs/source/libs/servo.rst110
-rw-r--r--libraries/Servo/Servo.h1
3 files changed, 25 insertions, 89 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile
index 5fbb079..a441c4f 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -591,7 +591,8 @@ WARN_LOGFILE =
# with spaces.
INPUT = ../libmaple/ \
- ../wirish/
+ ../wirish/ \
+ ../libraries/
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst
index 891f151..3b96467 100644
--- a/docs/source/libs/servo.rst
+++ b/docs/source/libs/servo.rst
@@ -5,8 +5,6 @@
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
peripherals <timers>`.
@@ -31,83 +29,15 @@ servomotor attached to pin 9, you could write ::
servo.attach(9);
-.. cpp:class:: Servo
-
- Class for controlling RC servomotors via :ref:`timers <timers>`.
+.. TODO [0.0.10] figure out the cpp domain well enough to replace
+.. references here
.. _libs-servo-attach:
-.. cpp:function:: bool Servo::attach(uint8 pin, uint16 min, uint16 max)
-
- Attach this Servo object to the given ``pin``. The pin must be
- capable of PWM. You can check this by seeing if "PWM" is written
- next to its number on the Maple silkscreen, or by consulting the
- :ref:`pwmWrite() <lang-pwmwrite>` documentation.
-
- Sets this pin's :ref:`mode <lang-pinmode>` to :ref:`PWM
- <lang-pinmode-wiringpinmode>`, and returns true if successful.
- Does nothing and returns false if the pin doesn't support PWM.
-
- Parameter ``min`` is the pulse width corresponding to 0 degrees;
- ``max`` is the pulse width corresponding to 180 degrees (both are
- in microseconds).
-
-.. cpp:function:: bool Servo::attach(uint8 pin)
-
- Equivalent to :ref:`attach(pin, 544, 2400) <libs-servo-attach>`.
-
.. _libs-servo-attached:
-.. cpp:function:: int Servo::attached() const
-
- If currently attached (via :ref:`attach() <libs-servo-attach>`) to
- a pin, returns that pin's number. Returns ``NOT_ATTACHED``
- otherwise.
-
-.. cpp:function:: bool Servo::detach()
-
- If this Servo object is currently attached to pin, stops driving
- the servo by setting a zero pulse width (this is accomplished by
- setting the associated :ref:`channel mode
- <lang-hardwaretimer-setchannelmode>` to ``TIMER_DISABLED``).
-
- Subsequently, calling :ref:`attached() <libs-servo-attached>` will
- return ``NOT_ATTACHED``.
-
-.. cpp:function:: void Servo::write(unsigned int value)
-
- If ``value`` is less than ``SERVO_MAX_WRITE_ANGLE`` (which, for
- Arduino compatibility, is 200), it's interpreted as an angle in
- degrees. Otherwise, it's treated as a pulse width in microseconds.
-
- Drives the servo to target the given angle, based on a linear
- interpolation of the ``min`` and ``max`` pulse widths determined
- when :ref:`attach() <libs-servo-attach>` was called.
-
- Be aware that some (especially lower-cost) servos have fairly
- non-linear maps between pulse width and target angle. Make sure to
- test your motor before relying on this method.
-
-.. cpp:function:: void Servo::writeMicroseconds(uint16 pulseWidth)
-
- Drives the servo using a ``pulseWidth``-microsecond pulse.
-
- If ``pulseWidth`` is outside of the [``min``, ``max``\ ] pulse
- width range set during :ref:`attach() <libs-servo-attach>`, it will
- be clamped to lie in this range.
-
-.. cpp:function:: int Servo::read() const
-
- Returns the servo's target angle, in degrees. This will be clamped
- to lie between 0 (when the pulse width is at most ``min``) and 180
- (when the pulse width is at least ``max``).
-
-.. cpp:function:: uint16 Servo::readMicroseconds() const
-
- Returns the pulse width of the wave currently driving the servo, in
- microseconds. This will be clamped to lie in the [``min``,
- ``max``\ ] pulse width range set during :ref:`attach()
- <libs-servo-attach>`.
+.. doxygenclass:: Servo
+ :members:
Arduino Compatibility
---------------------
@@ -126,9 +56,10 @@ 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.
+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
@@ -141,17 +72,20 @@ 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.
+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
diff --git a/libraries/Servo/Servo.h b/libraries/Servo/Servo.h
index f80339e..c28f015 100644
--- a/libraries/Servo/Servo.h
+++ b/libraries/Servo/Servo.h
@@ -76,6 +76,7 @@
#define SERVO_DEFAULT_MIN_ANGLE 0
#define SERVO_DEFAULT_MAX_ANGLE 180
+/** Class for interfacing with RC servomotors. */
class Servo {
public:
/**