aboutsummaryrefslogtreecommitdiffstats
path: root/source
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-05-13 20:06:41 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-05-13 20:10:37 -0400
commit8482c195902d9c98085b8dc79d71db4b17c37964 (patch)
tree5abdb37dcf48f77a2f43078f9fe4f05a592f2abd /source
parentb93c724a9e811c6716cd6e0b34a233f4b4d35502 (diff)
downloadlibrambutan-8482c195902d9c98085b8dc79d71db4b17c37964.tar.gz
librambutan-8482c195902d9c98085b8dc79d71db4b17c37964.zip
Docs: Updating Servo docs.
Diffstat (limited to 'source')
-rw-r--r--source/libs/servo.rst110
1 files changed, 22 insertions, 88 deletions
diff --git a/source/libs/servo.rst b/source/libs/servo.rst
index 891f151..3b96467 100644
--- a/source/libs/servo.rst
+++ b/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