Merge pull request #93 from RaspberryPiFoundation/dev

Martin O'Hanlon · web-flow · commit f5030e96e60b · 2022-12-22T08:42:49.000Z
0.4.1
diff --git a/docs/api.rst b/docs/api.rst
@@ -140,3 +140,8 @@ DigitalInputDevice
     :show-inheritance:
     :inherited-members:
     :members: 
+
+pinout
+------
+
+.. autofunction:: pinout
diff --git 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
@@ -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/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
@@ -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
@@ -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
@@ -0,0 +1,5 @@
+from picozero import LED
+
+led = LED(14) 
+
+led.pulse()
diff --git 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/print_pinout.py b/docs/examples/print_pinout.py
@@ -0,0 +1,3 @@
+from picozero import pinout
+
+pinout()
diff --git 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
@@ -2,9 +2,13 @@
 ..
 .. SPDX short identifier: MIT
 
+===============
 Getting started
 ===============
 
+Install using Thonny
+====================
+
 Requirements
 ------------
 
@@ -20,36 +24,53 @@ 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
 ------------------------------------
 
 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
@@ -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
 ------
  
@@ -82,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. 
 
@@ -110,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`:
 
@@ -144,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:
 
@@ -166,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:
 
@@ -214,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.
 
diff --git a/picozero/__init__.py b/picozero/__init__.py
@@ -1,12 +1,14 @@
 __name__ = "picozero"
 __package__ = "picozero"
-__version__ = '0.4.0'
+__version__ = '0.4.1'
 __author__ = "Raspberry Pi Foundation"
 
 from .picozero import (
     PWMChannelAlreadyInUse,
     EventFailedScheduleQueueFull,
 
+    pinout,
+
     DigitalOutputDevice,
     DigitalLED,
     Buzzer,
diff --git a/picozero/picozero.py b/picozero/picozero.py
@@ -18,6 +18,41 @@ class EventFailedScheduleQueueFull(Exception):
 
 def clamp(n, low, high): return max(low, min(n, high))
 
+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
+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
+        ---------"""
+
+    if output:
+        print(pins)
+    return pins
+
 class PinMixin:
     """
     Mixin used by devices that have a single pin number.
@@ -1630,7 +1665,7 @@ def when_deactivated(self):
         """
         return self._when_deactivated
     
-    @when_activated.setter
+    @when_deactivated.setter
     def when_deactivated(self, value):
         self._when_deactivated = value
     
diff --git a/setup.py b/setup.py
diff --git a/tests/test_picozero.py b/tests/test_picozero.py

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`from picozero import LED`
`2`		`-from time import sleep`
`3`	`2`
`4`	`3`	`led = LED(14)`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+from picozero import pinout`
	`2`	`+`
	`3`	`+pinout()`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`from picozero import Robot`
`2`		`-from time import sleep`
`3`	`2`
`4`	`3`	`robot_rover = Robot(left=(14,15), right=(12,13))`
`5`	`4`