RaspberryPiFoundation · martinohanlon · Aug 12, 2022 · Jun 10, 2022 · Jul 8, 2022 · Jul 8, 2022
diff --git a/docs/api.rst b/docs/api.rst
@@ -56,6 +56,21 @@ Speaker
     :inherited-members:
     :members: 
 
+Motor
+-----
+
+.. autoclass:: Motor
+    :show-inheritance:
+    :inherited-members:
+    :members: 
+
+Robot / Rover
+-------------
+
+.. autoclass:: Robot
+    :show-inheritance:
+    :inherited-members:
+    :members: 
 
 DigitalOutputDevice
 -------------------
@@ -87,22 +102,30 @@ Switch
     :inherited-members:
     :members: 
 
-Potentiometer
--------------
+Potentiometer / Pot
+-------------------
 
 .. autoclass:: Potentiometer
     :show-inheritance:
     :inherited-members:
     :members: 
 
-TemperatureSensor
------------------
+TemperatureSensor / TempSensor / Thermistor
+-------------------------------------------
 
 .. autoclass:: TemperatureSensor
     :show-inheritance:
     :inherited-members:
     :members: 
 
+DistanceSensor
+--------------
+
+.. autoclass:: DistanceSensor
+    :show-inheritance:
+    :inherited-members:
+    :members: 
+
 DigitalInputDevice
 ------------------
 

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -6,7 +6,7 @@ Change log
 0.2.0 - 2022-06-29
 ~~~~~~~~~~~~~~~~~~
 
-+ Compatibility fix LED
++ Pico W compatibility fix for onboard LED
 
 0.1.1 - 2022-06-08
 ~~~~~~~~~~~~~~~~~~

diff --git a/docs/conf.py b/docs/conf.py
@@ -38,6 +38,7 @@ def __getattr__(cls, name):
 # add the ticks_ms function to time (as it is in micropython)
 import time
 setattr(time, 'ticks_ms', lambda x: None)
+setattr(time, 'ticks_us', lambda x: None)
 
 # -- Project information -----------------------------------------------------
 

diff --git a/docs/developing.rst b/docs/developing.rst
@@ -38,13 +38,13 @@ Install sphinx using ::
 
     pip3 install sphinx
 
-To build the documentation, run the following command from the docs directory ::
+To test the documentation build, run the following command from the docs directory ::
 
     $ make html
 
 The website will be built in the directory docs/_build/html.
 
-Documentation can be viewed at `picozero.readthedocs.io`_.
+Documentation can be viewed at `picozero.readthedocs.io`_ and is automatically built and deployed on commit.
 
 .. _picozero.readthedocs.io: https://picozero.readthedocs.io
 
@@ -59,4 +59,16 @@ The tests are design to be run on a Raspberry Pi Pico.
 
 3. Copy the ``test_picozero.py`` to the pico.
 
-4. Run the ``test_picozero.py`` file.
+4. Run the ``test_picozero.py`` file.
+
+If a test fails it is helpful to be able to see verbose error messages. To see error messages you need to modify the ``lib/unittest.py`` file on the pico.
+
+Locate the following code in the ``run_class`` function::
+
+    # Uncomment to investigate failure in detail
+    #raise
+
+Uncomment ``raise``::
+
+    # Uncomment to investigate failure in detail
+    raise
diff --git a/docs/examples/motor_move.py b/docs/examples/motor_move.py
@@ -0,0 +1,8 @@
+from picozero import Motor
+from time import sleep
+
+motor = Motor(14, 15)
+
+motor.move()
+sleep(1)
+motor.stop()
diff --git a/docs/examples/robot_rover_forward.py b/docs/examples/robot_rover_forward.py
@@ -0,0 +1,9 @@
+from picozero import Robot
+from time import sleep
+
+robot_rover = Robot(left=(14,15), right=(12,13))
+
+# move forward
+robot_rover.forward()
+sleep(1)
+robot_rover.stop()
diff --git a/docs/examples/robot_rover_square.py b/docs/examples/robot_rover_square.py
@@ -0,0 +1,10 @@
+from picozero import Robot
+from time import sleep
+
+robot_rover = Robot(left=(14,15), right=(12,13))
+
+for i in range(4):
+    # move forward for 1 second
+    robot_rover.forward(t=1, wait=True)
+    # rotate to the left for 1 second
+    robot_rover.left(t=1, wait=True)
diff --git a/docs/examples/ultrasonic_distance_sensor.py b/docs/examples/ultrasonic_distance_sensor.py
@@ -0,0 +1,8 @@
+from picozero import DistanceSensor
+from time import sleep
+
+ds = DistanceSensor(echo=4, trigger=5)
+
+while True:
+    print(ds.distance)
+    sleep(0.1)
diff --git a/docs/images/distance_sensor_bb.svg b/docs/images/distance_sensor_bb.svg
diff --git a/docs/images/robot_bb.svg b/docs/images/robot_bb.svg
diff --git a/docs/recipes.rst b/docs/recipes.rst
@@ -154,7 +154,6 @@ Print the value, voltage and percent reported by a potentiometer:
 
     In the Thonny Python editor, choose View->Plotter to plot the output of :meth:`print`. 
 
-
 Buzzer
 ------
 
@@ -169,6 +168,29 @@ Control a passive buzzer or speaker that can play different tones or frequencies
 
 .. literalinclude:: examples/speaker.py
 
+Motor
+-----
+
+Move a motor which is connected via 2 pins (forward / backward) and a motor controller board
+
+.. literalinclude:: examples/motor_move.py
+
+Robot rover
+-------------
+
+Make a simple 2 wheeled robot rover.
+
+.. image:: images/robot_bb.svg
+    :alt: A diagram of the Raspberry Pi Pico connected to 2 motors via a motor controller board powered by a battery pack
+
+Move the rover forward for 1 second and stop.
+
+.. literalinclude:: examples/robot_rover_forward.py
+
+Move the rover *roughly* in a square:
+
+.. literalinclude:: examples/robot_rover_square.py
+
 Play a tune
 ~~~~~~~~~~~
 
@@ -188,4 +210,14 @@ Internal Temperature Sensor
 
 Check the internal temperature of the Raspberry Pi Pico in degrees Celcius:
 
-.. literalinclude:: examples/pico_temperature.py
+.. literalinclude:: examples/pico_temperature.py
+
+Ultrasonic Distance Sensor
+--------------------------
+
+Get the distance in metres from an ultrasonic distance sensor (HC-SR04).
+
+.. image:: images/distance_sensor_bb.svg
+    :alt: A diagram of the Raspberry Pi Pico connected to HC-SR04 distance sensor
+
+.. literalinclude:: examples/ultrasonic_distance_sensor.py
diff --git a/docs/sketches/distance_sensor.fzz b/docs/sketches/distance_sensor.fzz
diff --git a/docs/images/pico_led_14.fzz → docs/sketches/pico_led_14.fzz b/docs/images/pico_led_14.fzz → docs/sketches/pico_led_14.fzz
diff --git a/docs/sketches/robot.fzz b/docs/sketches/robot.fzz
diff --git a/examples/motor.py b/examples/motor.py
@@ -0,0 +1,14 @@
+from picozero import Motor
+from time import sleep
+
+m = Motor(12, 13)
+
+# turn the motor for 1 second
+print("the motor is turning")
+m.move()
+sleep(1)
+m.stop()
+
+# or alternatively turn it at half speed for 2 seconds
+m.move(speed=0.5, t=2)
+print("the motor will turn at half speed and stop after 2 seconds")
diff --git a/examples/ultrasonic_distance_sensor.py b/examples/ultrasonic_distance_sensor.py
@@ -0,0 +1,8 @@
+from picozero import DistanceSensor
+from time import sleep
+
+ds = DistanceSensor(5, 4)
+
+while True:
+    print(ds.distance)
+    sleep(0.1)
diff --git a/picozero/__init__.py b/picozero/__init__.py
@@ -19,6 +19,8 @@
     Speaker,
 
     RGBLED,
+    Motor,
+    Robot,
 
     DigitalInputDevice,
     Switch,
@@ -32,4 +34,6 @@
     pico_temp_sensor,
     TempSensor,
     Thermistor,
+
+    DistanceSensor,
 )