docs: Add quickref info about Servo; improve Servo docs.

3 files changed, 67 insertions, 13 deletions

diff --git a/docs/library/pyb.Servo.rst b/docs/library/pyb.Servo.rst
index 486e7a057a..cea31fd28e 100644
--- a/docs/library/pyb.Servo.rst
+++ b/docs/library/pyb.Servo.rst
@@ -1,15 +1,37 @@
+.. _pyb.Servo:
+
 class Servo -- 3-wire hobby servo driver
 ========================================
 
-Servo controls standard hobby servos with 3-wires (ground, power, signal).
+Servo objects control standard hobby servo motors with 3-wires (ground, power,
+signal).  There are 4 positions on the pyboard where these motors can be plugged
+in: pins X1 through X4 are the signal pins, and next to them are 4 sets of power
+and ground pins.
+
+Example usage::
+
+    import pyb
+
+    s1 = pyb.Servo(1)   # create a servo object on position X1
+    s2 = pyb.Servo(2)   # create a servo object on position X2
+
+    s1.angle(45)        # move servo 1 to 45 degrees
+    s2.angle(0)         # move servo 2 to 0 degrees
 
+    # move servo1 and servo2 synchronously, taking 1500ms
+    s1.angle(-60, 1500)
+    s2.angle(30, 1500)
+
+.. note:: The Servo objects use Timer(5) to produce the PWM output.  You can
+   use Timer(5) for Servo control, or your own purposes, but not both at the
+   same time.
 
 Constructors
 ------------
 
 .. class:: pyb.Servo(id)
 
-   Create a servo object.  ``id`` is 1-4.
+   Create a servo object.  ``id`` is 1-4, and corresponds to pins X1 through X4.
 
 
 Methods
@@ -17,22 +39,41 @@ Methods
 
 .. method:: servo.angle([angle, time=0])
 
-   Get or set the angle of the servo.
-   
+   If no arguments are given, this function returns the current angle.
+
+   If arguments are given, this function sets the angle of the servo:
+
      - ``angle`` is the angle to move to in degrees.
-     - ``time`` is the number of milliseconds to take to get to the specified angle.
+     - ``time`` is the number of milliseconds to take to get to the specified
+       angle.  If omitted, then the servo moves as quickly as possible to its
+       new position.
 
-.. method:: servo.calibration([pulse_min, pulse_max, pulse_centre, [pulse_angle_90, pulse_speed_100]])
+.. method:: servo.speed([speed, time=0])
+
+   If no arguments are given, this function returns the current speed.
 
-   Get or set the calibration of the servo timing.
+   If arguments are given, this function sets the speed of the servo:
+
+     - ``speed`` is the speed to change to, between -100 and 100.
+     - ``time`` is the number of milliseconds to take to get to the specified
+       speed.  If omitted, then the servo accelerates as quickly as possible.
 
 .. method:: servo.pulse_width([value])
 
-   Get or set the pulse width in milliseconds.
+   If no arguments are given, this function returns the current raw pulse-width
+   value.
 
-.. method:: servo.speed([speed, time=0])
+   If an argument is given, this function sets the raw pulse-width value.
+
+.. method:: servo.calibration([pulse_min, pulse_max, pulse_centre, [pulse_angle_90, pulse_speed_100]])
+
+   If no arguments are given, this function returns the current calibration
+   data, as a 5-tuple.
+
+   If arguments are given, this function sets the timing calibration:
 
-   Get or set the speed of a continuous rotation servo.
-   
-     - ``speed`` is the speed to move to change to, between -100 and 100.
-     - ``time`` is the number of milliseconds to take to get to the specified speed.
+     - ``pulse_min`` is the minimum allowed pulse width.
+     - ``pulse_max`` is the maximum allowed pulse width.
+     - ``pulse_centre`` is the pulse width corresponding to the centre/zero position.
+     - ``pulse_angle_90`` is the pulse width corresponding to 90 degrees.
+     - ``pulse_speed_100`` is the pulse width corresponding to a speed of 100.
diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
index 3d05a40a74..2fab247592 100644
--- a/docs/library/pyb.rst
+++ b/docs/library/pyb.rst
@@ -98,6 +98,7 @@ Power related functions
    If given no arguments, returns a tuple of clock frequencies:
    (sysclk, hclk, pclk1, pclk2).
    These correspond to:
+
     - sysclk: frequency of the CPU
     - hclk: frequency of the AHB bus, core memory and DMA
     - pclk1: frequency of the APB1 bus
diff --git a/docs/quickref.rst b/docs/quickref.rst
index 5c3c7a7b2c..2a1429cb05 100644
--- a/docs/quickref.rst
+++ b/docs/quickref.rst
@@ -48,6 +48,18 @@ See :ref:`pyb.Pin <pyb.Pin>`. ::
     p_in = Pin('X2', Pin.IN, Pin.PULL_UP)
     p_in.value() # get value, 0 or 1
 
+Servo control
+-------------
+
+See :ref:`pyb.Servo <pyb.Servo>`. ::
+
+    from pyb import Servo
+
+    s1 = Servo(1) # servo on position 1 (X1, VIN, GND)
+    s1.angle(45) # move to 45 degrees
+    s1.angle(-60, 1500) # move to -60 degrees in 1500ms
+    s1.speed(50) # for continuous rotation servos
+
 External interrupts
 -------------------