From 3f88634feb98b50a124ab9c762ac962086c9f254 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 13 May 2011 20:06:41 -0400 Subject: Docs: Updating Servo docs. --- docs/Doxyfile | 3 +- docs/source/libs/servo.rst | 110 +++++++++------------------------------------ 2 files changed, 24 insertions(+), 89 deletions(-) (limited to 'docs') 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 `. @@ -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 `. +.. 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() ` documentation. - - Sets this pin's :ref:`mode ` to :ref:`PWM - `, 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-attached: -.. cpp:function:: int Servo::attached() const - - If currently attached (via :ref:`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 - ` to ``TIMER_DISABLED``). - - Subsequently, calling :ref:`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() ` 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() `, 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() - `. +.. doxygenclass:: Servo + :members: Arduino Compatibility --------------------- @@ -126,9 +56,10 @@ implementation uses :ref:`timers ` to drive the PWM directly. Consequently, **the Maple implementation only allows Servo instances to** :ref:`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() ` 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 ` in +your board's :ref:`hardware documentation `. RC Servos expect a pulse approximately every 20ms. In the Maple implementation, :ref:`periods ` 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 ` to match up pins and timer channels. -Another difference: although it is not publicly documented to do so, -the Arduino implementation of `attach() -`_ returns the timer -channel associated with the newly-attached pin, or 0 on failure (as of -Arduino 0021). The Maple implementation returns :ref:`true -` on success, and :ref:`false -` on failure (and this is its documented -behavior). - -We currently provide a soft (bit-banged) implementation of the -:ref:`Wire ` I2C library. +And here's some fine print: + +- Although it is not publicly documented to do so, the Arduino + implementation of `attach() + `_ returns the timer + channel associated with the newly-attached pin, or 0 on failure (as + of Arduino 0021). The Maple implementation returns :ref:`true + ` on success, and :ref:`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 -- cgit v1.2.3