Merge pull request #141 from RaspberryPiFoundation/dev

Dev

Author: pjbRPF

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright 2023 Raspberry Pi Foundation
+Copyright 2025 Raspberry Pi Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

docs/api.rst

@@ -63,6 +63,14 @@ Servo
     :inherited-members:
     :members: 
 
+Stepper
+-------
+
+.. autoclass:: Stepper
+    :show-inheritance:
+    :inherited-members:
+    :members: 
+
 Motor
 -----
 
@@ -109,6 +117,14 @@ MotionSensor
     :inherited-members:
     :members: 
 
+TouchSensor
+-----------
+
+.. autoclass:: TouchSensor
+    :show-inheritance:
+    :inherited-members:
+    :members: 
+
 Switch
 ------
 

docs/changelog.rst

@@ -3,9 +3,24 @@ Change log
 
 .. currentmodule:: picozero
 
+0.6.0 - 2025-11-26
+-----------
+
++ Introduced ``Stepper`` class for stepper motors
++ Introduced ``TouchSensor`` class for capacitive touch sensors
++ Updated tests and documentation
++ Other minor bug fixes
+
+
+0.5.2 - 2025-11-26
+-----------
+
++ Fixed 404 in manual install instructions
+
 0.5.1 - 2025-11-24
+-----------
 
-+ Fix to incorrect example in documentation.
++ Fix to incorrect example in documentation
 
 0.5.0 - 2025-10-31
 -----------

docs/conf.py

@@ -12,62 +12,75 @@
 #
 import os
 import sys
+
 # sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+
 
 # Mock out certain modules while building documentation
 class Mock:
     __all__ = []
-    def __init__(self, *args, **kw): pass
-    def __call__(self, *args, **kw): return Mock()
-    def __mul__(self, other): return Mock()
-    def __and__(self, other): return Mock()
-    def __bool__(self): return False
-    def __nonzero__(self): return False
+
+    def __init__(self, *args, **kw):
+        pass
+
+    def __call__(self, *args, **kw):
+        return Mock()
+
+    def __mul__(self, other):
+        return Mock()
+
+    def __and__(self, other):
+        return Mock()
+
+    def __bool__(self):
+        return False
+
+    def __nonzero__(self):
+        return False
+
     @classmethod
     def __getattr__(cls, name):
-        if name in ('__file__', '__path__'):
-            return '/dev/null'
+        if name in ("__file__", "__path__"):
+            return "/dev/null"
         else:
             return Mock()
 
-sys.modules['machine'] = Mock()
-sys.modules['micropython'] = Mock()
+
+sys.modules["machine"] = Mock()
+sys.modules["micropython"] = Mock()
 
 # 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)
+
+setattr(time, "ticks_ms", lambda x: None)
+setattr(time, "ticks_us", lambda x: None)
 
 # -- Project information -----------------------------------------------------
 
-project = 'picozero'
-copyright = '2025, Raspberry Pi Foundation'
-author = 'Raspberry Pi Foundation'
+project = "picozero"
+copyright = "2025, Raspberry Pi Foundation"
+author = "Raspberry Pi Foundation"
 
 # The full version, including alpha/beta/rc tags
-release = '0.5.0'
+release = "0.6.0"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx.ext.autodoc', 
-    'sphinx.ext.viewcode', 
-    'sphinx.ext.intersphinx'
-]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.intersphinx"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -79,26 +92,26 @@ def __getattr__(cls, name):
 # a list of builtin themes.
 #
 if on_rtd:
-    html_theme = 'sphinx_rtd_theme'
-    #html_theme_options = {}
+    html_theme = "sphinx_rtd_theme"
+    # html_theme_options = {}
     html_sidebars = {
-        '**': [
-            'globaltoc.html',
-            'relations.html',
-            'searchbox.html',
+        "**": [
+            "globaltoc.html",
+            "relations.html",
+            "searchbox.html",
         ],
     }
 else:
-    html_theme = 'alabaster'
-    #html_theme_options = {}
-    #html_sidebars = {}
+    html_theme = "alabaster"
+    # html_theme_options = {}
+    # html_sidebars = {}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # -- Autodoc configuration ------------------------------------------------
 
-autodoc_member_order = 'groupwise'
-autodoc_default_flags = ['members']
+autodoc_member_order = "groupwise"
+autodoc_default_flags = ["members"]

docs/examples/stepper_analog_clock.py

@@ -0,0 +1,10 @@
+from picozero import Stepper
+
+# Second Hand Clock - Continuous 60s Rotation
+# One full revolution every 60 seconds.
+
+STEP_DELAY = 60.0 / 2048  # ≈ 0.029296875 seconds per step (full-step)
+
+stepper = Stepper((1, 2, 3, 4), step_delay=STEP_DELAY)
+
+stepper.run_continuous(direction="cw")

docs/examples/stepper_automatic_blinds.py

@@ -0,0 +1,50 @@
+from picozero import Stepper
+from time import localtime, sleep
+
+stepper = Stepper((1, 2, 3, 4), step_sequence="half")
+
+OPEN_TIME = (7, 0)  # Open at 7:00 AM (hour, minute)
+CLOSE_TIME = (20, 0)  # Close at 8:00 PM
+ROTATIONS = 5  # Number of full rotations needed to fully open/close blinds
+
+# Track state
+is_open = False
+
+
+def open_blinds():
+    global is_open
+    if not is_open:
+        for _ in range(ROTATIONS):
+            stepper.rotate(1, "cw")
+        is_open = True
+
+
+def close_blinds():
+    global is_open
+    if is_open:
+        for _ in range(ROTATIONS):
+            stepper.rotate(1, "ccw")
+        is_open = False
+
+
+def check_schedule():
+    now = localtime()
+    current_time = (now.tm_hour, now.tm_min)
+
+    # Check if it's time to open
+    if current_time == OPEN_TIME and not is_open:
+        open_blinds()
+
+    # Check if it's time to close
+    elif current_time == CLOSE_TIME and is_open:
+        close_blinds()
+
+
+# Set starting position (closed)
+stepper.reset_position()
+is_open = False
+
+# Check every 30 seconds
+while True:
+    check_schedule()
+    sleep(30)

docs/examples/touch_sensor.py

@@ -0,0 +1,12 @@
+from picozero import TouchSensor, pico_led
+from time import sleep
+
+# Capacitive touch sensor output connected to pin 2
+touch = TouchSensor(2)
+
+while True:
+    if touch.is_touched:
+        pico_led.on()
+    else:
+        pico_led.off()
+    sleep(0.1)

docs/examples/touch_sensor_callbacks.py

@@ -0,0 +1,7 @@
+from picozero import TouchSensor, pico_led
+from time import sleep
+
+touch = TouchSensor(2)
+
+touch.when_touch_starts = pico_led.on
+touch.when_touch_ends = pico_led.off

docs/gettingstarted.rst

@@ -58,7 +58,7 @@ picozero can be installed by copying the ``picozero.py`` code to your Raspberry
 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
+.. _picozero.py: https://raw.githubusercontent.com/RaspberryPiFoundation/picozero/master/picozero/picozero.py
 
 Create a new file called picozero.py, copy code into the file and save it on your Raspberry Pi Pico.
 
@@ -72,10 +72,25 @@ In the **View** menu, ensure that the **Files** option has a tick. This will let
 .. 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.
+Either clone the picozero `GitHub repository`_ or download the `picozero.py`_ file and save it on your main computer.
+
+.. only:: html
+
+   .. raw:: html
+
+      <p>
+        <a href="https://raw.githubusercontent.com/RaspberryPiFoundation/picozero/master/picozero/picozero.py" download>
+          ⬇️ Download picozero.py
+        </a>
+      </p>
+
+.. only:: not html
+
+   Download ``picozero.py``:
+   https://raw.githubusercontent.com/RaspberryPiFoundation/picozero/master/picozero/picozero.py
 
 .. _GitHub repository: https://github.com/RaspberryPiFoundation/picozero
-.. _picozero.py: https://raw.githubusercontent.com/RaspberryPiFoundation/picozero/master/picozero/picozero.py?token=GHSAT0AAAAAABRLTKWZDBSYBE54NJ7AIZ6MYSENI2A
+.. _picozero.py: https://raw.githubusercontent.com/RaspberryPiFoundation/picozero/master/picozero/picozero.py
 
 In Thonny, navigate to the cloned directory or location you saved the file in and find the ``picozero.py`` file.
 

docs/recipes.rst

@@ -145,6 +145,17 @@ Turn the :obj:`pico_led` on when a :class:`Button` is pressed and off when it is
 
 .. literalinclude:: examples/button_led.py
 
+Touch sensor
+------------
+
+Detect touch using a capacitive touch sensor:
+
+.. literalinclude:: examples/touch_sensor.py
+
+Use callbacks to respond to touch events:
+
+.. literalinclude:: examples/touch_sensor_callbacks.py
+
 Motion sensor
 -------------
 
@@ -276,13 +287,37 @@ Move the rover (roughly) in a square:
 
 .. literalinclude:: examples/robot_rover_square.py
 
+
+Stepper motor
+-------------
+
+Control a stepper motor connected via a driver board (e.g. ULN2003) to create:
+
+Analog clock (continuous second hand):
+.. literalinclude:: examples/stepper_analog_clock.py
+
+Automatic blinds (multi-rotation, time-based):
+.. literalinclude:: examples/stepper_automatic_blinds.py
+
+
 Internal temperature sensor
 ---------------------------
 
 Check the internal temperature of the Raspberry Pi Pico in degrees Celcius:
 
 .. literalinclude:: examples/pico_temperature.py
 
+Motion sensor
+-------------
+
+Detect motion using a PIR (Passive Infrared) sensor:
+
+.. literalinclude:: examples/motion_sensor.py
+
+Use callbacks to respond to motion events:
+
+.. literalinclude:: examples/motion_sensor_callbacks.py
+
 Ultrasonic distance sensor
 --------------------------