Make Motors PWM devices with optional speed argument on methods

Author: bennuttall

docs/boards.md

@@ -253,11 +253,11 @@ robot = Robot(left=(4, 14), right=(17, 18))
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
-| `forward()` | Drive the robot forwards. | `seconds` - The number of seconds to drive for. If `None`, stay on. Default: `None` |
-| `backward()` | Drive the robot backwards. | `seconds` - The number of seconds to drive for. If `None`, stay on. Default: `None` |
-| `left()` | Make the robot turn left. | `seconds` - The number of seconds to turn for. If `None`, stay on. Default: `None` |
-| `right()` | Make the robot turn right. | `seconds` - The number of seconds to turn for. If `None`, stay on. Default: `None` |
-| `stop()` | Stop the robot. | None |
+| `forward()`  | Drive the robot forwards.  | `speed` - Speed at which to drive the motors, `0` to `1`. Default: `1` |
+| `backward()` | Drive the robot backwards. | `speed` - Speed at which to drive the motors, `0` to `1`. Default: `1` |
+| `left()`     | Make the robot turn left.  | `speed` - Speed at which to drive the motors, `0` to `1`. Default: `1` |
+| `right()`    | Make the robot turn right. | `speed` - Speed at which to drive the motors, `0` to `1`. Default: `1` |
+| `stop()`     | Stop the robot.            | None |
 
 ## Ryanteck MCB Robot
 

docs/outputs.md

@@ -161,6 +161,6 @@ motor = Motor(forward=17, back=18)
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
-| `forward()` | Drive the motor forwards. | `seconds` - The number of seconds to stay on for. If `None`, stay on. Default: `None` |
-| `backward()` | Drive the motor backwards. | `seconds` - The number of seconds to stay on for. If `None`, stay on. Default: `None` |
+| `forward()` | Drive the motor forwards. | `speed` - Speed at which to drive the motor, `0` to `1`. Default: `1` |
+| `backward()` | Drive the motor backwards. | `speed` - Speed at which to drive the motor, `0` to `1`. Default: `1` |
 | `stop()` | Stop the motor. | None |

gpiozero/boards.py

@@ -229,65 +229,76 @@ def __init__(self, left=None, right=None):
         self._left = Motor(forward=left_forward, back=left_back)
         self._right = Motor(forward=right_forward, back=right_back)
 
-    def left(self, seconds=None):
+        self._min_pwm = self._left._min_pwm
+        self._max_pwm = self._left._max_pwm
+
+    def forward(self, speed=1):
         """
-        Make the robot turn left. If seconds given, stop after given number of
-        seconds.
+        Drive the robot forward.
 
-        seconds: `None`
-            Number of seconds to turn left for
+        speed: `1`
+            Speed at which to drive the motors, 0 to 1.
         """
-        self._left.forward()
-        self._right.backward()
-        if seconds is not None:
-            sleep(seconds)
-            self._left.stop()
-            self._right.stop()
+        self._left._backward.off()
+        self._right._backward.off()
+
+        self._left._forward.on()
+        self._right._forward.on()
+        if speed < 1:
+            sleep(0.1)  # warm up the motors
+            self._left._forward.value = speed
+            self._right._forward.value = speed
 
-    def right(self, seconds=None):
+    def backward(self, speed=1):
         """
-        Make the robot turn right. If seconds given, stop after given number of
-        seconds.
+        Drive the robot backward.
 
-        seconds: `None`
-            Number of seconds to turn right for
+        speed: `1`
+            Speed at which to drive the motors, 0 to 1.
         """
-        self._right.forward()
-        self._left.backward()
-        if seconds is not None:
-            sleep(seconds)
-            self._left.stop()
-            self._right.stop()
+        self._left._forward.off()
+        self._right._forward.off()
+
+        self._left._backward.on()
+        self._right._backward.on()
+        if speed < 1:
+            sleep(0.1)  # warm up the motors
+            self._left._backward.value = speed
+            self._right._backward.value = speed
 
-    def forward(self, seconds=None):
+    def left(self, speed=1):
         """
-        Drive the robot forward. If seconds given, stop after given number of
-        seconds.
+        Make the robot turn left.
 
-        seconds: `None`
-            Number of seconds to drive forward for
+        speed: `1`
+            Speed at which to drive the motors, 0 to 1.
         """
-        self._left.forward()
-        self._right.forward()
-        if seconds is not None:
-            sleep(seconds)
-            self._left.stop()
-            self._right.stop()
+        self._right._backward.off()
+        self._left._forward.off()
 
-    def backward(self, seconds=None):
+        self._right._forward.on()
+        self._left._backward.on()
+        if speed < 1:
+            sleep(0.1)  # warm up the motors
+            self._right._forward.value = speed
+            self._left._backward.value = speed
+
+    def right(self, speed=1):
         """
-        Drive the robot backward. If seconds given, stop after given number of
-        seconds.
+        Make the robot turn right.
 
-        seconds: `None`
-            Number of seconds to drive backward for
+        speed: `1`
+            Speed at which to drive the motors, 0 to 1.
         """
-        self._left.backward()
-        self._right.backward()
-        if seconds is not None:
-            sleep(seconds)
-            self._left.stop()
-            self._right.stop()
+        self._left._backward.off()
+        self._right._forward.off()
+
+        self._left._forward.on()
+        self._right._backward.on()
+        if speed < 1:
+            sleep(0.1)  # warm up the motors
+            self._left._forward.value = speed
+            self._right._backward.value = speed
 
     def stop(self):
         """

gpiozero/output_devices.py

@@ -195,7 +195,7 @@ def value(self):
     def value(self, n):
         _min = self._min_pwm
         _max = self._max_pwm
-        if _min >= n >= _max:
+        if _min <= n <= _max:
             n *= 100
         else:
             raise GPIODeviceError(
@@ -289,22 +289,31 @@ def __init__(self, forward=None, back=None):
         if not all([forward, back]):
             raise GPIODeviceError('forward and back pins must be provided')
 
-        self._forward = OutputDevice(forward)
-        self._backward = OutputDevice(back)
+        self._forward = PWMOutputDevice(forward)
+        self._backward = PWMOutputDevice(back)
 
-    def forward(self):
+        self._min_pwm = self._forward._min_pwm
+        self._max_pwm = self._forward._max_pwm
+
+    def forward(self, speed=1):
         """
         Drive the motor forwards
         """
-        self._forward.on()
-        self._backward.off()
+        self._backward.value = self._min_pwm
+        self._forward.value = self._max_pwm
+        if speed < 1:
+            sleep(0.1)  # warm up the motor
+            self._forward.value = speed
 
-    def backward(self):
+    def backward(self, speed=1):
         """
         Drive the motor backwards
         """
-        self._backward.on()
-        self._forward.off()
+        self._forward.value = self._min_pwm
+        self._backward.value = self._max_pwm
+        if speed < 1:
+            sleep(0.1)  # warm up the motor
+            self._backward.value = speed
 
     def stop(self):
         """