Merge pull request #10 from dhalbert/check_fraction_range

Check fraction range; add post-constructor access to actuation_range and pulse widths.

Author: tannewt

adafruit_motor/motor.py

@@ -51,27 +51,21 @@ class DCMotor:
     def __init__(self, positive_pwm, negative_pwm):
         self._positive = positive_pwm
         self._negative = negative_pwm
+        self._throttle = None
 
     @property
     def throttle(self):
-        """How much power is being delivered to the motor. Values range from ``-1.0`` (full
-           throttle reverse) to ``1.0`` (full throttle forwards.) ``0`` will stop the motor from
-           spinning and ``None`` will let the motor spin freely."""
-        if self._positive.duty_cycle == 0 and self._negative.duty_cycle == 0:
-            return None
-        if self._positive.duty_cycle == 0xffff and self._negative.duty_cycle == 0xffff:
-            return float(0)
-        if self._positive.duty_cycle > 0 and self._negative.duty_cycle > 0:
-            raise RuntimeError("PWMs in invalid state")
-        value = max(self._positive.duty_cycle, self._negative.duty_cycle) / 0xffff
-        if self._negative.duty_cycle > 0:
-            return -1 * value
-        return value
+        """Motor speed, ranging from -1.0 (full speed reverse) to 1.0 (full speed forward),
+        or ``None``.
+        If ``None``, both PWMs are turned full off. If ``0.0``, both PWMs are turned full on.
+        """
+        return self._throttle
 
     @throttle.setter
     def throttle(self, value):
         if value is not None and (value > 1.0 or value < -1.0):
             raise ValueError("Throttle must be None or between -1.0 and 1.0")
+        self._throttle = value
         if value is None:
             self._positive.duty_cycle = 0
             self._negative.duty_cycle = 0

adafruit_motor/servo.py

@@ -41,10 +41,14 @@ class _BaseServo: # pylint: disable-msg=too-few-public-methods
        :param int min_pulse: The minimum pulse length of the servo in microseconds.
        :param int max_pulse: The maximum pulse length of the servo in microseconds."""
     def __init__(self, pwm_out, *, min_pulse=750, max_pulse=2250):
-        self._min_duty = int((min_pulse * pwm_out.frequency) / 1000000 * 0xffff)
-        max_duty = (max_pulse * pwm_out.frequency) / 1000000 * 0xffff
-        self._duty_range = int(max_duty - self._min_duty)
         self._pwm_out = pwm_out
+        self.set_pulse_width_range(min_pulse, max_pulse)
+
+    def set_pulse_width_range(self, min_pulse=750, max_pulse=2250):
+        """Change min and max pulse widths."""
+        self._min_duty = int((min_pulse * self._pwm_out.frequency) / 1000000 * 0xffff)
+        max_duty = (max_pulse * self._pwm_out.frequency) / 1000000 * 0xffff
+        self._duty_range = int(max_duty - self._min_duty)
 
     @property
     def fraction(self):
@@ -56,6 +60,8 @@ def fraction(self):
 
     @fraction.setter
     def fraction(self, value):
+        if not 0.0 <= value <= 1.0:
+            raise ValueError("Must be 0.0 to 1.0")
         duty_cycle = self._min_duty + int(value * self._duty_range)
         self._pwm_out.duty_cycle = duty_cycle
 
@@ -68,6 +74,13 @@ class Servo(_BaseServo):
        :param int min_pulse: The minimum pulse width of the servo in microseconds.
        :param int max_pulse: The maximum pulse width of the servo in microseconds.
 
+       ``actuation_range`` is an exposed property and can be changed at any time:
+
+        .. code-block:: python
+
+          servo = Servo(pwm)
+          servo.actuation_range = 135
+
        The specified pulse width range of a servo has historically been 1000-2000us,
        for a 90 degree range of motion. But nearly all modern servos have a 170-180
        degree range, and the pulse widths can go well out of the range to achieve this
@@ -80,22 +93,23 @@ class Servo(_BaseServo):
          get a wider range of movement. But if you go too low or too high,
          the servo mechanism may hit the end stops, buzz, and draw extra current as it stalls.
          Test carefully to find the safe minimum and maximum.
-"""
+    """
     def __init__(self, pwm_out, *, actuation_range=180, min_pulse=750, max_pulse=2250):
         super().__init__(pwm_out, min_pulse=min_pulse, max_pulse=max_pulse)
-        self._actuation_range = actuation_range
+        self.actuation_range = actuation_range
+        """The physical range of motion of the servo in degrees."""
         self._pwm = pwm_out
 
     @property
     def angle(self):
         """The servo angle in degrees. Must be in the range ``0`` to ``actuation_range``."""
-        return self._actuation_range * self.fraction
+        return self.actuation_range * self.fraction
 
     @angle.setter
     def angle(self, new_angle):
-        if new_angle < 0 or new_angle > self._actuation_range:
+        if new_angle < 0 or new_angle > self.actuation_range:
             raise ValueError("Angle out of range")
-        self.fraction = new_angle / self._actuation_range
+        self.fraction = new_angle / self.actuation_range
 
 class ContinuousServo(_BaseServo):
     """Control a continuous rotation servo.

docs/conf.py

@@ -74,6 +74,16 @@
 # If this is True, todo emits a warning for each TODO entries. The default is False.
 todo_emit_warnings = True
 
+# Avoid an `= None` on instance attributes with their own doc strings.
+# Workaround from here: https://github.com/sphinx-doc/sphinx/issues/2044#issuecomment-285888160
+#
+from sphinx.ext.autodoc import (
+    ClassLevelDocumenter, InstanceAttributeDocumenter)
+
+def iad_add_directive_header(self, sig):
+    ClassLevelDocumenter.add_directive_header(self, sig)
+
+InstanceAttributeDocumenter.add_directive_header = iad_add_directive_header
 
 # -- Options for HTML output ----------------------------------------------