aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/libs/servo.rst
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@mit.edu>2010-12-21 10:27:37 -0500
committerMarti Bolivar <mbolivar@mit.edu>2010-12-21 10:27:37 -0500
commitc45bccad44187da27505cf5808424e709e3f54a1 (patch)
tree18a459a50f8d0551ba046e30462c93999d982725 /docs/source/libs/servo.rst
parent84fd2532a7f23d20354ff590790b3f892cb7e7d7 (diff)
parentd5ad2a27f4e69e6cc9324331945937c983c30366 (diff)
downloadlibrambutan-c45bccad44187da27505cf5808424e709e3f54a1.tar.gz
librambutan-c45bccad44187da27505cf5808424e709e3f54a1.zip
Merge branch 'master' into debug-serialusb.
Chose debug-serialusb version in cases of conflict. Conflicts: libmaple/usb/usb_callbacks.c
Diffstat (limited to 'docs/source/libs/servo.rst')
-rw-r--r--docs/source/libs/servo.rst108
1 files changed, 108 insertions, 0 deletions
diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst
new file mode 100644
index 0000000..f92fd91
--- /dev/null
+++ b/docs/source/libs/servo.rst
@@ -0,0 +1,108 @@
+.. 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 ``$LIB_MAPLE_HOME/libraries/Servo/``.
+
+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);
+
+.. cpp:class:: Servo
+
+ Class for controlling RC servomotors via :ref:`timers <timers>`.
+
+.. _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>`.