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