RaspberryPiFoundation · martinohanlon · Mar 16, 2022 · Mar 1, 2022 · Mar 1, 2022 · Mar 1, 2022
diff --git a/README.rst b/README.rst
@@ -18,9 +18,9 @@ A beginner-friendly library for using common electronics components with the Ras
 
 Full documentation is available at `picozero.readthedocs.io <https://picozero.readthedocs.io>`_ :
 
-- `Installation and getting started guide <https://picozero.readthedocs.ioen/latest/gettingstarted.html>`_
-- `Recipes and how-to's <https://picozero.readthedocs.ioen/latest/recipes.html>`_
-- `API <https://picozero.readthedocs.ioen/latest/api.html>`_
+- `Installation and getting started guide <https://picozero.readthedocs.io/en/latest/gettingstarted.html>`_
+- `Recipes and how-to's <https://picozero.readthedocs.io/en/latest/recipes.html>`_
+- `API <https://picozero.readthedocs.io/en/latest/api.html>`_
 
-picozero is inspired by `gpiozero <https://gpiozero.readthedocs.io/en/stable/>`_ (and reuses some of its underlying struture), but is by design lighter weight and aligned with the Raspberry Pi Pico. 
+picozero is inspired by `gpiozero <https://gpiozero.readthedocs.io/en/stable/>`_ (and reuses some of its underlying structure), but is by design lighter weight and aligned with the Raspberry Pi Pico. 
 
diff --git a/docs/api.rst b/docs/api.rst
@@ -24,6 +24,14 @@ PWMLED
     :inherited-members:
     :members:
 
+RGBLED
+----------
+
+.. autoclass:: RGBLED
+    :show-inheritance:
+    :inherited-members:
+    :members:
+
 Button
 ------
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -32,6 +32,7 @@ def __getattr__(cls, name):
             return Mock()
 
 sys.modules['machine'] = Mock()
+sys.modules['micropython'] = Mock()
 
 # add the ticks_ms function to time (as it is in micropython)
 import time

diff --git a/docs/examples/button_function.py b/docs/examples/button_function.py
@@ -1,7 +1,7 @@
 from picozero import Button, pico_led
 from time import sleep
 
-button = Button(17)
+button = Button(18)
 
 def led_on_off():
     pico_led.on()

diff --git a/docs/examples/button_is_pressed.py b/docs/examples/button_is_pressed.py
@@ -1,7 +1,7 @@
 from picozero import Button
 from time import sleep
 
-button = Button(17)
+button = Button(18)
 
 while True:
     if button.is_pressed:

diff --git a/docs/examples/button_led.py b/docs/examples/button_led.py
@@ -1,6 +1,6 @@
 from picozero import Button, pico_led
 
-button = Button(17)
+button = Button(18)
 
 button.when_pressed = pico_led.on
 button.when_released = pico_led.off
diff --git a/docs/examples/buzzer.py b/docs/examples/buzzer.py
@@ -1,4 +1,4 @@
-# Active Buzzer that plays a not when powered
+# Active Buzzer that plays a note when powered
 from time import sleep
 from picozero import Buzzer
 

diff --git a/docs/examples/rgb_blink.py b/docs/examples/rgb_blink.py
@@ -0,0 +1,19 @@
+from picozero import RGBLED
+from time import sleep
+
+rgb = RGBLED(1, 2, 3)
+
+rgb.blink() # does not wait
+sleep(6)
+rgb.off()
+sleep(1)
+
+# blink purple 2 seconds, off 0.5 seconds
+rgb.blink(on_times=(2, 0.5), colors=((1, 0, 1), (0, 0, 0)), wait=True, n=3)
+
+rgb.off()
+sleep(1)
+
+# blink red 1 second, green 0.5 seconds, blue 0.25 seconds
+rgb.blink((1, 0.5, 0.25), colors=((1, 0, 0), (0, 1, 0), (0, 0, 1)), wait=True, n=2)
+
diff --git a/docs/examples/rgb_cycle.py b/docs/examples/rgb_cycle.py
@@ -0,0 +1,14 @@
+from picozero import RGBLED
+from time import sleep
+
+rgb = RGBLED(1, 2, 3)
+
+# Gradually colour cycle through colours between red and green, green and blue then blue and red
+rgb.cycle()
+sleep(4)
+rgb.off()
+sleep(1)
+
+# Colour cycle slower in the opposite direction
+rgb.cycle(fade_times=3, colors=((0, 0, 1), (0, 1, 0), (1, 0, 0)), wait=True, n=2)
+rgb.off()
diff --git a/docs/examples/rgb_pulse.py b/docs/examples/rgb_pulse.py
@@ -0,0 +1,18 @@
+from picozero import RGBLED
+from time import sleep
+
+rgb = RGBLED(1, 2, 3)
+
+rgb.pulse() # does not wait
+sleep(6)
+rgb.off()
+sleep(1)
+
+# 2 second to fade from purple to off, 0.5 seconds to change from off to purple 
+rgb.pulse(fade_times=(2, 0.5), colors=((1, 0, 1), (0, 0, 0)), wait=True, n=3)
+
+rgb.off()
+sleep(1)
+
+# 4 seconds to change from red to green, 2 to change from green to blue, then 1 to change from blue back to red
+rgb.pulse((4, 2, 1), colors=((1, 0, 0), (0, 1, 0), (0, 0, 1)), wait=True, n=2)
diff --git a/docs/examples/speaker.py b/docs/examples/speaker.py
@@ -1,22 +1,13 @@
-from time import sleep
 from picozero import Speaker
+from time import sleep
 
-speaker = Speaker(10)
-
-speaker.play()
-
-sleep(1)
+speaker = Speaker(5)
 
 def tada():
     c_note = 523
-    speaker.play(freq=c_note, duration=0.1)
+    speaker.play(c_note, 0.1)
     sleep(0.1)
-    speaker.play(c_note, 0.4)
-    for i in range(100, 0, -1):
-        speaker.play(freq=c_note, duration=0.01, volume=i/100)
-
-tada()
-sleep(1)
+    speaker.play(c_note, 0.9)
 
 def chirp():
     global speaker
@@ -25,6 +16,11 @@ def chirp():
           speaker.play(i, 0.01)
         sleep(0.2)
 
-chirp()
 
-speaker.off()
+try: 
+    tada()
+    sleep(1)
+    chirp()
+
+finally: # Turn the speaker off if interrupted
+    speaker.off()
diff --git a/docs/examples/speaker_notes.py b/docs/examples/speaker_notes.py
@@ -0,0 +1,24 @@
+from picozero import Speaker
+from time import sleep
+
+speaker = Speaker(5)
+
+BEAT = 0.4
+
+liten_mus = [ ['d5', BEAT / 2], ['d#5', BEAT / 2], ['f5', BEAT], ['d6', BEAT], ['a#5', BEAT], ['d5', BEAT],  
+              ['f5', BEAT], ['d#5', BEAT], ['d#5', BEAT], ['c5', BEAT / 2],['d5', BEAT / 2], ['d#5', BEAT], 
+              ['c6', BEAT], ['a5', BEAT], ['d5', BEAT], ['g5', BEAT], ['f5', BEAT], ['f5', BEAT], ['d5', BEAT / 2],
+              ['d#5', BEAT / 2], ['f5', BEAT], ['g5', BEAT], ['a5', BEAT], ['a#5', BEAT], ['a5', BEAT], ['g5', BEAT],
+              ['g5', BEAT], ['', BEAT / 2], ['a#5', BEAT / 2], ['c6', BEAT / 2], ['d6', BEAT / 2], ['c6', BEAT / 2],
+              ['a#5', BEAT / 2], ['a5', BEAT / 2], ['g5', BEAT / 2], ['a5', BEAT / 2], ['a#5', BEAT / 2], ['c6', BEAT],
+              ['f5', BEAT], ['f5', BEAT], ['f5', BEAT / 2], ['d#5', BEAT / 2], ['d5', BEAT], ['f5', BEAT], ['d6', BEAT],
+              ['d6', BEAT / 2], ['c6', BEAT / 2], ['b5', BEAT], ['g5', BEAT], ['g5', BEAT], ['c6', BEAT / 2],
+              ['a#5', BEAT / 2], ['a5', BEAT], ['f5', BEAT], ['d6', BEAT], ['a5', BEAT], ['a#5', BEAT * 1.5]]
+
+try:
+    for note in liten_mus:
+        speaker.play(note)
+        sleep(0.1) # leave a gap between notes
+
+finally: # Turn speaker off if interrupted
+    speaker.off()
diff --git a/docs/examples/speaker_tune.py b/docs/examples/speaker_tune.py
@@ -0,0 +1,21 @@
+from picozero import Speaker
+
+speaker = Speaker(5)
+
+BEAT = 0.25 # 240 BPM
+
+liten_mus = [ ['d5', BEAT / 2], ['d#5', BEAT / 2], ['f5', BEAT], ['d6', BEAT], ['a#5', BEAT], ['d5', BEAT],  
+              ['f5', BEAT], ['d#5', BEAT], ['d#5', BEAT], ['c5', BEAT / 2],['d5', BEAT / 2], ['d#5', BEAT], 
+              ['c6', BEAT], ['a5', BEAT], ['d5', BEAT], ['g5', BEAT], ['f5', BEAT], ['f5', BEAT], ['d5', BEAT / 2],
+              ['d#5', BEAT / 2], ['f5', BEAT], ['g5', BEAT], ['a5', BEAT], ['a#5', BEAT], ['a5', BEAT], ['g5', BEAT],
+              ['g5', BEAT], ['', BEAT / 2], ['a#5', BEAT / 2], ['c6', BEAT / 2], ['d6', BEAT / 2], ['c6', BEAT / 2],
+              ['a#5', BEAT / 2], ['a5', BEAT / 2], ['g5', BEAT / 2], ['a5', BEAT / 2], ['a#5', BEAT / 2], ['c6', BEAT],
+              ['f5', BEAT], ['f5', BEAT], ['f5', BEAT / 2], ['d#5', BEAT / 2], ['d5', BEAT], ['f5', BEAT], ['d6', BEAT],
+              ['d6', BEAT / 2], ['c6', BEAT / 2], ['b5', BEAT], ['g5', BEAT], ['g5', BEAT], ['c6', BEAT / 2],
+              ['a#5', BEAT / 2], ['a5', BEAT], ['f5', BEAT], ['d6', BEAT], ['a5', BEAT], ['a#5', BEAT * 1.5]]
+
+try:
+    speaker.play(liten_mus)
+
+finally: # Turn speaker off if interrupted
+    speaker.off()
diff --git a/docs/recipes.rst b/docs/recipes.rst
@@ -82,7 +82,6 @@ Create a pulse effect:
 
 .. literalinclude:: examples/led_pulse.py
 
-
 Button
 ------
 
@@ -99,7 +98,7 @@ Run a function every time a :class:`Button` is pressed:
 
 .. note::
 
-    Note that the line ``button.when_pressed = led_on_off`` does not run the
+    The line ``button.when_pressed = led_on_off`` does not run the
     function ``led_on_off``, rather it creates a reference to the function to be
     called when the button is pressed. Accidental use of ``button.when_pressed
     = led_on_off()`` would set the ``when_pressed`` action to :data:`None` (the
@@ -113,14 +112,37 @@ Turn the :obj:`pico_led` on when a :class:`Button` is pressed and off when it is
 RGBLED
 ------
 
-Setting colours with an :class:`RGBLED`:
+Set colours with an :class:`RGBLED`:
 
 .. literalinclude:: examples/rgb_led.py
 
-Using :meth:`~picozero.RGBLED.toggle` and :meth:`~picozero.RGBLED.invert`:
+Use :meth:`~picozero.RGBLED.toggle` and :meth:`~picozero.RGBLED.invert`:
 
 .. literalinclude:: examples/rgb_toggle_invert.py
 
+Blink
+~~~~~
+
+Use :meth:`~picozero.RGBLED.blink` blink to change between colours. You can control which colours are used and how long the LED is set to each colour. The colour `(0, 0, 0)` represents off. 
+
+You can control whether :meth:`~picozero.RGBLED.blink` runs a fixed number of times and whether it waits until it has finished or returns immediately so other code can run.
+
+.. literalinclude:: examples/rgb_blink.py
+
+Pulse
+~~~~~
+
+Use :meth:`~picozero.RGBLED.pulse` to gradually change the LED between colours. The default will pulse between red and off, then green and off, then blue and off. 
+
+.. literalinclude:: examples/rgb_pulse.py
+
+Cycle
+~~~~~
+
+The default for :meth:`~picozero.RGBLED.cycle` is to cycle from red to green, then green to blue, then blue to red. 
+
+.. literalinclude:: examples/rgb_cycle.py
+
 Potentiometer
 ---------------
 
@@ -147,6 +169,20 @@ Control a passive buzzer or speaker that can play different tones or frequencies
 
 .. literalinclude:: examples/speaker.py
 
+Play a tune
+~~~~~~~~~~~
+
+Play a tune of note names and durations in beats: 
+
+.. literalinclude:: examples/speaker_tune.py
+
+Play individual notes
+~~~~~~~~~~~~~~~~~~~~~
+
+Play individual notes and control the timing or perform another action:
+
+.. literalinclude:: examples/speaker_notes.py
+
 Internal Temperature Sensor
 ---------------------------
 

diff --git a/picozero/__init__.py b/picozero/__init__.py
@@ -1,20 +1,29 @@
 from .picozero import (
+    PWMChannelAlreadyInUse,
+
     DigitalOutputDevice,
     DigitalLED,
     Buzzer,
     PWMOutputDevice,
     PWMLED,
     LED,
+    pico_led,
+
+    PWMBuzzer,
+    Speaker,
+
+    RGBLED,
+
     DigitalInputDevice,
-    Button,
     Switch,
-    RGBLED,
+    Button,
+
     AnalogInputDevice,
     Potentiometer,
+    Pot,
+
     TemperatureSensor,
     pico_temp_sensor,
     TempSensor,
     Thermistor,
-    PWMBuzzer,
-    Speaker,
 )