From b64cdaedef60afb9ab84ed13130edc0f3ae15555 Mon Sep 17 00:00:00 2001
From: Martin O'Hanlon <martin.ohanlon@raspberrypi.org>
Date: Tue, 20 Dec 2022 16:52:41 +0000
Subject: [PATCH 1/4] issue fix plus pinout

---
 docs/examples/print_pinout.py |  3 +++
 docs/recipes.rst              | 32 ++++++++++++++++++++++++++++++++
 picozero/__init__.py          |  2 ++
 picozero/picozero.py          | 26 +++++++++++++++++++++++++-
 4 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/print_pinout.py

diff --git a/docs/examples/print_pinout.py b/docs/examples/print_pinout.py
new file mode 100644
index 0000000..6038025
--- /dev/null
+++ b/docs/examples/print_pinout.py
@@ -0,0 +1,3 @@
+from picozero import pinout
+
+pinout()
\ No newline at end of file
diff --git a/docs/recipes.rst b/docs/recipes.rst
index e39513b..3a7df59 100644
--- a/docs/recipes.rst
+++ b/docs/recipes.rst
@@ -48,6 +48,38 @@ Using the :obj:`pico_led` is equivalent to::
 
 You can use :obj:`pico_led` in the same way as external LEDs created using :class:`LED`.
 
+Pin out
+-------
+
+You can output a *diagram* of the Raspberry Pi Pico which displays its pins and their numbers.
+
+.. literalinclude:: examples/print_pinout.py
+
+::
+
+            ---usb---
+    GP0  1  |o     o| -1  VBUS
+    GP1  2  |o     o| -2  VSYS
+    GND  3  |o     o| -3  GND
+    GP2  4  |o     o| -4  3V3_EN
+    GP3  5  |o     o| -5  3V3(OUT)
+    GP4  6  |o     o| -6           ADC_VREF
+    GP5  7  |o     o| -7  GP28     ADC2
+    GND  8  |o     o| -8  GND      AGND
+    GP6  9  |o     o| -9  GP27     ADC1
+    GP7  10 |o     o| -10 GP26     ADC0
+    GP8  11 |o     o| -11 RUN
+    GP9  12 |o     o| -12 GP22
+    GND  13 |o     o| -13 GND
+    GP10 14 |o     o| -14 GP21
+    GP11 15 |o     o| -15 GP20
+    GP12 16 |o     o| -16 GP19
+    GP13 17 |o     o| -17 GP18
+    GND  18 |o     o| -18 GND
+    GP14 19 |o     o| -19 GP17
+    GP15 20 |o     o| -20 GP16
+            ---------
+
 LEDs
 ------
  
diff --git a/picozero/__init__.py b/picozero/__init__.py
index feecead..8ddd10d 100644
--- a/picozero/__init__.py
+++ b/picozero/__init__.py
@@ -7,6 +7,8 @@
     PWMChannelAlreadyInUse,
     EventFailedScheduleQueueFull,
 
+    pinout,
+
     DigitalOutputDevice,
     DigitalLED,
     Buzzer,
diff --git a/picozero/picozero.py b/picozero/picozero.py
index 886dcde..5b93b59 100644
--- a/picozero/picozero.py
+++ b/picozero/picozero.py
@@ -18,6 +18,30 @@ class EventFailedScheduleQueueFull(Exception):
 
 def clamp(n, low, high): return max(low, min(n, high))
 
+def pinout():
+    print("""        ---usb---
+GP0  1  |o     o| -1  VBUS
+GP1  2  |o     o| -2  VSYS
+GND  3  |o     o| -3  GND
+GP2  4  |o     o| -4  3V3_EN
+GP3  5  |o     o| -5  3V3(OUT)
+GP4  6  |o     o| -6           ADC_VREF
+GP5  7  |o     o| -7  GP28     ADC2
+GND  8  |o     o| -8  GND      AGND
+GP6  9  |o     o| -9  GP27     ADC1
+GP7  10 |o     o| -10 GP26     ADC0
+GP8  11 |o     o| -11 RUN
+GP9  12 |o     o| -12 GP22
+GND  13 |o     o| -13 GND
+GP10 14 |o     o| -14 GP21
+GP11 15 |o     o| -15 GP20
+GP12 16 |o     o| -16 GP19
+GP13 17 |o     o| -17 GP18
+GND  18 |o     o| -18 GND
+GP14 19 |o     o| -19 GP17
+GP15 20 |o     o| -20 GP16
+        ---------""")
+
 class PinMixin:
     """
     Mixin used by devices that have a single pin number.
@@ -1630,7 +1654,7 @@ def when_deactivated(self):
         """
         return self._when_deactivated
     
-    @when_activated.setter
+    @when_deactivated.setter
     def when_deactivated(self, value):
         self._when_deactivated = value
     

From 786b984841c2647e6771422c9dc2f67fc626039d Mon Sep 17 00:00:00 2001
From: Martin O'Hanlon <martin.ohanlon@raspberrypi.org>
Date: Tue, 20 Dec 2022 18:05:50 +0000
Subject: [PATCH 2/4] pinout tests and docs

---
 docs/api.rst           |  5 +++++
 picozero/picozero.py   | 17 ++++++++++++++---
 tests/test_picozero.py | 10 +++++++++-
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 7a461b9..b08953d 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -140,3 +140,8 @@ DigitalInputDevice
     :show-inheritance:
     :inherited-members:
     :members: 
+
+pinout
+------
+
+.. autofunction:: pinout
\ No newline at end of file
diff --git a/picozero/picozero.py b/picozero/picozero.py
index 5b93b59..94b8cb7 100644
--- a/picozero/picozero.py
+++ b/picozero/picozero.py
@@ -18,8 +18,15 @@ class EventFailedScheduleQueueFull(Exception):
 
 def clamp(n, low, high): return max(low, min(n, high))
 
-def pinout():
-    print("""        ---usb---
+def pinout(output=True):
+    """
+    Returns a textual representation of the Raspberry Pi pico pins and functions.
+
+    :param bool output:
+        If :data:`True` (the default) the pinout will be "printed".
+        
+    """
+    pins = """        ---usb---
 GP0  1  |o     o| -1  VBUS
 GP1  2  |o     o| -2  VSYS
 GND  3  |o     o| -3  GND
@@ -40,7 +47,11 @@ def pinout():
 GND  18 |o     o| -18 GND
 GP14 19 |o     o| -19 GP17
 GP15 20 |o     o| -20 GP16
-        ---------""")
+        ---------"""
+
+    if output:
+        print(pins)
+    return pins
 
 class PinMixin:
     """
diff --git a/tests/test_picozero.py b/tests/test_picozero.py
index bbd4afa..f47ee5d 100644
--- a/tests/test_picozero.py
+++ b/tests/test_picozero.py
@@ -67,7 +67,15 @@ def assertInRange(self, value, lower, upper):
         msg = "Expected %r to be in range {} to {}".format(lower, upper)
         self.assertTrue(value <= upper, msg)
         self.assertTrue(value >= lower, msg)
-        
+
+    ###########################################################################
+    # SUPPORTING
+    ###########################################################################
+    
+    def test_pinout(self):
+        pins = pinout(output=False)
+        self.assertIsNotNone(pins)
+
     ###########################################################################
     # OUTPUT DEVICES
     ###########################################################################

From ce8e0cde15d4628b986f2ba544186dbc252939f5 Mon Sep 17 00:00:00 2001
From: Martin O'Hanlon <martin.ohanlon@raspberrypi.org>
Date: Thu, 22 Dec 2022 08:31:01 +0000
Subject: [PATCH 3/4] docs update

---
 docs/developing.rst                 |  4 +--
 docs/examples/led_blink.py          |  1 -
 docs/examples/led_pulse.py          |  2 +-
 docs/examples/led_pulse_method.py   |  5 ++++
 docs/examples/pico_temperature.py   |  2 +-
 docs/examples/robot_rover_square.py |  1 -
 docs/gettingstarted.rst             | 43 ++++++++++++++++++++++-------
 docs/recipes.rst                    | 14 ++++++----
 8 files changed, 51 insertions(+), 21 deletions(-)
 create mode 100644 docs/examples/led_pulse_method.py

diff --git a/docs/developing.rst b/docs/developing.rst
index a5c6935..9bd39e1 100644
--- a/docs/developing.rst
+++ b/docs/developing.rst
@@ -40,11 +40,11 @@ Install sphinx using ::
 
 To test the documentation build, run the following command from the docs directory ::
 
-    $ make html
+    $ ./make html
 
 The website will be built in the directory docs/_build/html.
 
-Documentation can be viewed at `picozero.readthedocs.io`_ and is automatically built and deployed on commit.
+Documentation can be viewed at `picozero.readthedocs.io`_ and is automatically built and deployed on push to github.
 
 .. _picozero.readthedocs.io: https://picozero.readthedocs.io
 
diff --git a/docs/examples/led_blink.py b/docs/examples/led_blink.py
index 73e525d..96cdb23 100644
--- a/docs/examples/led_blink.py
+++ b/docs/examples/led_blink.py
@@ -1,5 +1,4 @@
 from picozero import LED
-from time import sleep
 
 led = LED(14)
 
diff --git a/docs/examples/led_pulse.py b/docs/examples/led_pulse.py
index e906e5b..31ef404 100644
--- a/docs/examples/led_pulse.py
+++ b/docs/examples/led_pulse.py
@@ -1,5 +1,5 @@
-from time import sleep
 from picozero import LED
+from time import sleep
 from math import sin, radians
 
 led = LED(14) 
diff --git a/docs/examples/led_pulse_method.py b/docs/examples/led_pulse_method.py
new file mode 100644
index 0000000..50e685e
--- /dev/null
+++ b/docs/examples/led_pulse_method.py
@@ -0,0 +1,5 @@
+from picozero import LED
+
+led = LED(14) 
+
+led.pulse()
\ No newline at end of file
diff --git a/docs/examples/pico_temperature.py b/docs/examples/pico_temperature.py
index 299c491..cd3b9bb 100644
--- a/docs/examples/pico_temperature.py
+++ b/docs/examples/pico_temperature.py
@@ -1,7 +1,7 @@
 # Choose View -> Plotter in Thonny to see a graph of the results
 
-from time import sleep
 from picozero import pico_temp_sensor
+from time import sleep
 
 while True:
     print(pico_temp_sensor.temp)
diff --git a/docs/examples/robot_rover_square.py b/docs/examples/robot_rover_square.py
index 0b16ba7..05ecac1 100644
--- a/docs/examples/robot_rover_square.py
+++ b/docs/examples/robot_rover_square.py
@@ -1,5 +1,4 @@
 from picozero import Robot
-from time import sleep
 
 robot_rover = Robot(left=(14,15), right=(12,13))
 
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index b994471..95710ab 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -2,9 +2,13 @@
 ..
 .. SPDX short identifier: MIT
 
+===============
 Getting started
 ===============
 
+Install using Thonny
+====================
+
 Requirements
 ------------
 
@@ -20,12 +24,13 @@ Once Thonny is installed, you will need to ensure that you are using the latest
 
 .. _Pico guide: https://learning-admin.raspberrypi.org/en/projects/introduction-to-the-pico/3
 
-Use the MicroPython interpreter
--------------------------------
+Select the MicroPython interpreter
+----------------------------------
 
 You can change which interpreter you are using in Thonny by selecting the desired option at the bottom right of the screen. Make sure that **MicroPython (Raspberry Pi Pico)** is selected.
 
 .. image:: images/thonny-switch-interpreter.jpg
+    :alt: Selecting MicroPython (Raspberry Pi Pico) from the interpreter menu in the bottom right of the Thonny IDE
 
 Install picozero from PyPI in Thonny
 ------------------------------------
@@ -33,23 +38,39 @@ Install picozero from PyPI in Thonny
 To install picozero within Thonny, select **Tools** > **Manage packages...**
 
 .. image:: images/thonny-manage-packages.jpg
+    :alt: Selecting Manage Packages from the Tools menu in Thonny
 
 Search for `picozero` on PyPI.
 
 .. image:: images/thonny-packages-picozero.jpg
+    :alt: picozero entered in the Search box of the Manage Packages window in Thonny
 
 Click on **install** to download the package.
 
 .. image:: images/thonny-install-package.jpg
+    :alt: Information about the picozero package shown in the Manage Packages window
+
+Manual install
+==============
+
+picozero can be installed by copying the ``picozero.py`` code to your Raspberry Pi Pico.
+
+Either clone the picozero `GitHub repository`_ or copy the code from the `picozero.py`_ file and save it on your main computer.
+
+.. _GitHub repository: https://github.com/RaspberryPiFoundation/picozero
+.. _picozero.py: https://raw.githubusercontent.com/RaspberryPiFoundation/picozero/master/picozero/picozero.py?token=GHSAT0AAAAAABRLTKWZDBSYBE54NJ7AIZ6MYSENI2A
+
+Create a new file called picozero.py, copy code into the file and save it on your Raspberry Pi Pico.
 
-Other install options
----------------------
+Copy picozero.py using Thonny
+-----------------------------
 
-You can use the Thonny file manager to transfer a ``picozero.py`` file to your Raspberry Pi Pico.
+Alternatively, you can use the Thonny file manager to transfer the ``picozero.py`` file to your Raspberry Pi Pico.
 
 In the **View** menu, ensure that the **Files** option has a tick. This will let you see the files.
 
 .. image:: images/thonny-view-files.jpg
+    :alt: The Files option selected from the View menu
 
 Either clone the picozero `GitHub repository`_ or copy the code from the `picozero.py`_ file and save it on your main computer.
 
@@ -63,10 +84,12 @@ In Thonny, navigate to the cloned directory or location you saved the file in an
 Right click on the file and select the **Upload to /** option. You should see a copy of the ``picozero.py`` file on the Raspberry Pi Pico.
 
 .. image:: images/thonny-upload-files.jpg
+    :alt: The "Upload to /" option selected in the picozero.py file menu
 .. image:: images/thonny-copy-picozero.jpg
+    :alt: The picozero.py file shown in the Raspberry Pi Pico file viewer.
 
 Write a program to control the onboard LED
-------------------------------------------
+==========================================
 
 The following code will blink the onboard LED at a frequency of once per second.::
 
@@ -79,8 +102,8 @@ The following code will blink the onboard LED at a frequency of once per second.
         pico_led.off()
         sleep(0.5)
 
-Run a program on your computer
-------------------------------
+Run the program on your computer
+--------------------------------
 
 You can choose to run the program from your computer.
 
@@ -92,8 +115,8 @@ Choose to save the script on **This computer** and provide a filename.
 
 .. image:: images/save-this-computer.png
 
-Run a program on your Raspberry Pi Pico
-----------------------------------
+Run the program on your Raspberry Pi Pico
+-----------------------------------------
 
 You can choose to run the program from the Raspberry Pi Pico.
 
diff --git a/docs/recipes.rst b/docs/recipes.rst
index 3a7df59..9887689 100644
--- a/docs/recipes.rst
+++ b/docs/recipes.rst
@@ -114,8 +114,12 @@ Create a pulse effect:
 
 .. literalinclude:: examples/led_pulse.py
 
+Alternatively, you can use the :meth:`~picozero.LED.pulse` method.
+
+.. literalinclude:: examples/led_pulse_method.py
+
 Buttons
-------
+-------
 
 You can connect buttons and switches to a Raspberry Pi Pico and detect when they are pressed. 
 
@@ -142,7 +146,7 @@ Turn the :obj:`pico_led` on when a :class:`Button` is pressed and off when it is
 .. literalinclude:: examples/button_led.py
 
 RGB LEDs
-------
+--------
 
 Set colours with an :class:`RGBLED`:
 
@@ -176,7 +180,7 @@ The default for :meth:`~picozero.RGBLED.cycle` is to cycle from red to green, th
 .. literalinclude:: examples/rgb_cycle.py
 
 Potentiometer
----------------
+-------------
 
 Print the value, voltage, and percent reported by a potentiometer:
 
@@ -198,7 +202,7 @@ Control an active buzzer that plays a note when powered:
 .. literalinclude:: examples/buzzer.py
 
 Speaker
---------
+-------
 
 Control a passive buzzer or speaker that can play different tones or frequencies:
 
@@ -246,7 +250,7 @@ Move a motor connected via two pins (forward and backward) and a motor controlle
 .. literalinclude:: examples/motor_move.py
 
 Robot rover
--------------
+-----------
 
 Make a simple two-wheeled robot rover.
 

From 28686b68319eb399060a42ebe1611a02bf6af0c7 Mon Sep 17 00:00:00 2001
From: Martin O'Hanlon <martin.ohanlon@raspberrypi.org>
Date: Thu, 22 Dec 2022 08:41:01 +0000
Subject: [PATCH 4/4] 0.4.1

---
 docs/changelog.rst   | 21 ++++++++++++++-------
 docs/conf.py         |  2 +-
 picozero/__init__.py |  2 +-
 setup.py             |  2 +-
 4 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index ea71046..eb5e05e 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -3,14 +3,21 @@ Change log
 
 .. currentmodule:: picozero
 
+0.4.1 - 2022-12-22
+------------------
+
++ Introduced ``pinout()``
++ Bug fix with ``DigitalInputDevice.when_deactivated`` decorator
++ Documentation tidy up and minor fixes
+
 0.4.0 - 2022-11-18
-~~~~~~~~~~~~~~~~~~
+------------------
 
 + Introduced ``Servo`` class
 + Documentation fixes
 
 0.3.0 - 2022-08-12
-~~~~~~~~~~~~~~~~~~
+------------------
 
 + Introduced ``Motor``, ``Robot``, and ``DistanceSensor`` classes.
 + Renamed ``LED`` factory ``use_pwm`` parameter to ``pwm`` to match other classes. **Note:** This is an API breaking change. 
@@ -20,12 +27,12 @@ Change log
 + Documentation updates.
 
 0.2.0 - 2022-06-29
-~~~~~~~~~~~~~~~~~~
+------------------
 
 + Pico W compatibility fix for onboard LED.
 
 0.1.1 - 2022-06-08
-~~~~~~~~~~~~~~~~~~
+------------------
 
 + Minor fixes for bugs found during testing.
 + Small improvements to exception messages.
@@ -34,19 +41,19 @@ Change log
 + Added RGBLED.colour as an alias to RGBLED.color.
 
 0.1.0 - 2022-04-08
-~~~~~~~~~~~~~~~~~~
+------------------
 
 + Beta release.
 + Documentation updates.
 + Minor bug fixes and refactoring.
 
 0.0.2 - 2022-03-31
-~~~~~~~~~~~~~~~~~~
+------------------
 
 + Bug fixes and documentation updates.
 
 0.0.1 - 2022-03-21
-~~~~~~~~~~~~~~~~~~
+------------------
 
 + Initial alpha release to test installation process.
 
diff --git a/docs/conf.py b/docs/conf.py
index eb4c8fc..3afb34a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -47,7 +47,7 @@ def __getattr__(cls, name):
 author = 'Raspberry Pi Foundation'
 
 # The full version, including alpha/beta/rc tags
-release = '0.4.0'
+release = '0.4.1'
 
 
 # -- General configuration ---------------------------------------------------
diff --git a/picozero/__init__.py b/picozero/__init__.py
index 8ddd10d..8e8fb43 100644
--- a/picozero/__init__.py
+++ b/picozero/__init__.py
@@ -1,6 +1,6 @@
 __name__ = "picozero"
 __package__ = "picozero"
-__version__ = '0.4.0'
+__version__ = '0.4.1'
 __author__ = "Raspberry Pi Foundation"
 
 from .picozero import (
diff --git a/setup.py b/setup.py
index 1afd37b..03755d7 100644
--- a/setup.py
+++ b/setup.py
@@ -3,7 +3,7 @@
 __project__ = 'picozero'
 __packages__ = ['picozero']
 __desc__ = 'A beginner-friendly library for using common electronics components with the Raspberry Pi Pico. '
-__version__ = '0.4.0'
+__version__ = '0.4.1'
 __author__ = "Raspberry Pi Foundation"
 __author_email__ = 'learning@raspberrypi.org'
 __license__ = 'MIT'