aboutsummaryrefslogtreecommitdiffstats
path: root/source/libs/servo.rst
blob: 3b96467b67429d0785e0af167f937f3f85cb38bb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
.. 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 the ``/libraries/Servo/`` :ref:`libmaple`
directory.

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);

.. TODO [0.0.10] figure out the cpp domain well enough to replace
.. references here

.. _libs-servo-attach:

.. _libs-servo-attached:

.. doxygenclass:: Servo
   :members:

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, 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
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.

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

.. [#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.