Add Stepper motor class

docs/api.rst

@@ -63,6 +63,14 @@ Servo
     :inherited-members:
     :members: 
 
+Stepper
+-------
+
+.. autoclass:: Stepper
+    :show-inheritance:
+    :inherited-members:
+    :members: 
+
 Motor
 -----
 

docs/changelog.rst

@@ -7,6 +7,8 @@ Change log
 -----------
 
 + Introduced ``MotionSensor`` class for PIR sensors
++ Introduced ``Stepper`` class for stepper motor control
++ Added comprehensive stepper motor API with multiple control methods
 
 0.4.2 - 2023-05-12
 ------------------

docs/examples/stepper.py

@@ -0,0 +1,96 @@
+from picozero import Stepper
+from time import sleep
+
+stepper = Stepper((1, 2, 3, 4))
+
+print(f"Starting position: {stepper.step_count} steps, {stepper.angle:.1f} degrees")
+sleep(0.5)
+print()
+
+print("Using step() with default clockwise direction:")
+stepper.step(10)
+print(f"Position after step(10): {stepper.step_count} steps")
+sleep(0.5)
+print()
+
+print("step_clockwise(20):")
+stepper.step_clockwise(20)
+print(f"Position: {stepper.step_count} steps")
+sleep(0.5)
+print()
+
+print("step_counterclockwise(15):")
+stepper.step_counterclockwise(15)
+print(f"Position: {stepper.step_count} steps")
+sleep(0.5)
+print()
+
+print("step_ccw(5) - short alias:")
+stepper.step_ccw(5)
+print(f"Position: {stepper.step_count} steps")
+sleep(0.5)
+print()
+
+print("step(10, direction=1) - numeric:")
+stepper.step(10, direction=1)
+print(f"Position: {stepper.step_count} steps")
+print()
+
+print("step(10, direction='cw') - string abbreviation:")
+stepper.step(10, direction='cw')
+print(f"Position: {stepper.step_count} steps")
+sleep(0.5)
+print()
+
+print("step(10, direction='clockwise') - full string:")
+stepper.step(10, direction='clockwise')
+print(f"Position: {stepper.step_count} steps")
+sleep(0.5)
+print()
+
+print("rotate_clockwise(90) - 90 degrees CW:")
+stepper.rotate_clockwise(90)
+print(f"Position: {stepper.step_count} steps, {stepper.angle:.1f} degrees")
+sleep(0.5)
+print()
+
+print("rotate(45, direction='ccw') - 45 degrees CCW:")
+stepper.rotate(45, direction='ccw')
+print(f"Position: {stepper.step_count} steps, {stepper.angle:.1f} degrees")
+sleep(0.5)
+print()
+
+print("revolve_clockwise() - 1 full revolution CW:")
+stepper.revolve_clockwise()  # Default is 1 revolution
+print(f"Position: {stepper.step_count} steps, {stepper.angle:.1f} degrees")
+sleep(0.5)
+print()
+
+print("revolve(0.5, direction=-1) - half revolution CCW:")
+stepper.revolve(0.5, direction=-1)
+print(f"Position: {stepper.step_count} steps, {stepper.angle:.1f} degrees")
+sleep(0.5)
+print()
+
+print("Resetting position to home (0 steps, 0°)...")
+stepper.reset_position()
+print(f"After reset: {stepper.step_count} steps, {stepper.angle:.1f} degrees")
+sleep(0.5)
+print()
+
+print()
+print("Final demonstration - all methods achieve the same result:")
+for i, (method_name, method_call) in enumerate([
+    ("Default direction", lambda: stepper.step(5)),
+    ("Numeric direction", lambda: stepper.step(5, direction=1)),
+    ("String direction", lambda: stepper.step(5, direction='cw')),
+    ("Convenience method", lambda: stepper.step_clockwise(5))
+], 1):
+    print(f"{i}. {method_name}: 5 steps clockwise")
+    method_call()
+
+print(f"All methods reached: {stepper.step_count} steps total")
+
+# Turn off motor when done
+stepper.off()
+stepper.close()

docs/examples/stepper_positioning.py

@@ -0,0 +1,110 @@
+from picozero import Stepper, pico_led
+from time import sleep
+
+# Create devices
+stepper = Stepper((1, 2, 3, 4), step_sequence="half", step_delay=0.003)
+
+print("Stepper Motor Positioning Demo")
+print("Press Ctrl+C to exit")
+print()
+
+# Define preset positions in degrees
+positions = [0, 90, 180, 270, 360, 270, 180, 90]  # Forward and return cycle
+position_names = ["Home", "90° CW", "180° CW", "270° CW", "Full rotation", "270° CCW", "180° CCW", "90° CCW"]
+
+def move_to_position(target_angle, description=""):
+    """Move stepper to target angle from current position."""
+    current_angle = stepper.angle
+    angle_diff = target_angle - current_angle
+
+    print(f"Target: {description} ({target_angle}°)")
+    print(f"  Moving from {current_angle:.1f}° to {target_angle}°")
+    pico_led.on()  # Indicate movement
+
+    if angle_diff > 0:
+        print(f"  → Rotating {angle_diff}° clockwise...")
+        stepper.rotate_clockwise(angle_diff)
+    elif angle_diff < 0:
+        print(f"  → Rotating {-angle_diff}° counter-clockwise...")
+        stepper.rotate_counterclockwise(-angle_diff)
+    else:
+        print("  → Already at target position")
+
+    pico_led.off()  # Movement complete
+    print(f"  ✓ Position: {stepper.angle:.1f}° ({stepper.step_count} steps)")
+    print()
+
+def demonstrate_positioning_methods():
+    """Demonstrate different positioning approaches."""
+    print("=== POSITIONING METHOD COMPARISON ===")
+    print()
+
+    # Method 1: Using convenience methods (current approach)
+    print("Method 1: Convenience methods (rotate_clockwise/rotate_counterclockwise)")
+    stepper.reset_position()
+    move_to_position(90, "90° using rotate_clockwise")
+    move_to_position(45, "45° using rotate_counterclockwise") 
+
+    sleep(1)
+
+    # Method 2: Using parameterized methods
+    print("Method 2: Parameterized methods (rotate with direction parameter)")
+    stepper.reset_position()
+
+    print("Target: 120° using rotate(120, direction='cw')")
+    stepper.rotate(120, direction='cw')
+    print(f"  ✓ Position: {stepper.angle:.1f}°")
+
+    print("Target: 60° using rotate(60, direction='ccw')")
+    stepper.rotate(60, direction='ccw')
+    print(f"  ✓ Position: {stepper.angle:.1f}°")
+    print()
+
+    sleep(1)
+
+# Start demonstration
+stepper.reset_position()
+print(f"Starting position: {stepper.angle}° ({stepper.step_count} steps)")
+print()
+
+try:
+    # Demonstrate positioning methods
+    demonstrate_positioning_methods()
+
+    # Main positioning sequence
+    print("=== AUTOMATIC POSITIONING SEQUENCE ===")
+    print("Moving through preset positions...")
+    print()
+
+    for i, (target_pos, name) in enumerate(zip(positions, position_names)):
+        print(f"Step {i+1}/8:")
+        move_to_position(target_pos, name)
+        sleep(1.5)
+
+    print("=== ADVANCED POSITIONING DEMO ===")
+    print("Demonstrating precise positioning capabilities...")
+    print()
+
+    # Reset and demonstrate fractional positioning
+    stepper.reset_position()
+
+    # Small precise movements
+    precise_positions = [22.5, 67.5, 112.5, 157.5, 202.5]
+    for pos in precise_positions:
+        move_to_position(pos, f"Precise positioning to {pos}°")
+        sleep(1)
+
+    # Return home
+    move_to_position(0, "Return to home")
+
+    print("Positioning demonstration complete!")
+
+except KeyboardInterrupt:
+    print("\nInterrupted by user")
+
+finally:
+    # Clean shutdown
+    stepper.off()
+    pico_led.off()
+    stepper.close()
+    pico_led.close()

docs/recipes.rst

@@ -276,13 +276,35 @@ 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):
+
+.. literalinclude:: examples/stepper.py
+
+Advanced positioning with precise angle control:
+
+.. literalinclude:: examples/stepper_positioning.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
 --------------------------
 

picozero/__init__.py

@@ -23,6 +23,7 @@
     RGBLED,
     Motor,
     Robot,
+    Stepper,
     Servo,
 
     DigitalInputDevice,