pin alarm deep sleep example and docs

adafruit_magtag/magtag.py

@@ -122,6 +122,10 @@ def exit_and_deep_sleep(self, sleep_time: float) -> None:
         See https://circuitpython.readthedocs.io/en/latest/shared-bindings/alarm/index.html for more
         details.
 
+        Note: This function is for time based deep sleep only. If you want to use a PinAlarm
+        to wake up from deep sleep you need to deinit() the pins and use the alarm module
+        directly.
+
         :param float sleep_time: The amount of time to sleep in seconds
 
         """

adafruit_magtag/peripherals.py

@@ -98,7 +98,9 @@ def play_tone(self, frequency: float, duration: float) -> None:
         self._speaker_enable.value = False
 
     def deinit(self) -> None:
-        """Call deinit on all resources to free them"""
+        """Call deinit to free all resources used by peripherals.
+        You must call this function before you can use the peripheral
+        pins for other purposes like PinAlarm with deep sleep."""
         self.neopixels.deinit()
         if self._neopixel_disable is not None:
             self._neopixel_disable.deinit()

docs/examples.rst

@@ -13,3 +13,9 @@ Other Demos
 .. literalinclude:: ../examples/magtag_quote_demo.py
     :caption: examples/magtag_quote_demo.py
     :linenos:
+
+Deep Sleep and wake up from Button press.
+
+.. literalinclude:: ../examples/magtag_btn_sleep_demo.py
+    :caption: examples/magtag_btn_sleep_demo.py
+    :linenos:

examples/magtag_btn_sleep_demo.py

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2023 Tim Cocks
+#
+# SPDX-License-Identifier: Unlicense
+
+import time
+import alarm
+import board
+from adafruit_magtag.magtag import MagTag
+
+IDLE_TIMEOUT = 10  # seconds idle, then sleep
+
+magtag = MagTag()
+
+magtag.add_text(
+    text_position=(
+        50,
+        (magtag.graphics.display.height // 2) - 1,
+    ),
+    text_scale=3,
+)
+
+magtag.set_text("Awake")
+
+button_colors = ((255, 0, 0), (255, 150, 0), (0, 255, 255), (180, 0, 255))
+button_tones = (1047, 1318, 1568, 2093)
+
+now = time.monotonic()
+last_action_time = now
+while True:
+    now = time.monotonic()
+    if now - last_action_time >= 10.0:
+
+        magtag.set_text("Sleeping")
+        magtag.peripherals.deinit()
+        time.sleep(2)
+        # go to sleep
+        pin_alarm = alarm.pin.PinAlarm(pin=board.D11, value=False, pull=True)
+
+        # Exit the program, and then deep sleep until the alarm wakes us.
+        alarm.exit_and_deep_sleep_until_alarms(pin_alarm)
+
+    for i, b in enumerate(magtag.peripherals.buttons):
+        if not b.value:
+            print("Button %c pressed" % chr((ord("A") + i)))
+            last_action_time = now
+            magtag.peripherals.neopixel_disable = False
+            magtag.peripherals.neopixels.fill(button_colors[i])
+            magtag.peripherals.play_tone(button_tones[i], 0.25)
+            break
+    else:
+        magtag.peripherals.neopixel_disable = True
+    time.sleep(0.01)