Updated docs, improved examples

Author: makermelissa

README.rst

@@ -30,40 +30,49 @@ Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading
 `the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_.
 
-Installing from PyPI
-=====================
-.. note:: This library is not available on PyPI yet. Install documentation is included
-   as a standard element. Stay tuned for PyPI availability!
-
-.. todo:: Remove the above note if PyPI version is/will be available at time of release.
-   If the library is not planned for PyPI, remove the entire 'Installing from PyPI' section.
-
-On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
-PyPI <https://pypi.org/project/adafruit-circuitpython-magtag/>`_. To install for current user:
-
-.. code-block:: shell
-
-    pip3 install adafruit-circuitpython-magtag
-
-To install system-wide (this may be required in some cases):
-
-.. code-block:: shell
-
-    sudo pip3 install adafruit-circuitpython-magtag
-
-To install in a virtual environment in your current project:
-
-.. code-block:: shell
-
-    mkdir project-name && cd project-name
-    python3 -m venv .env
-    source .env/bin/activate
-    pip3 install adafruit-circuitpython-magtag
 
 Usage Example
 =============
 
-.. todo:: Add a quick, simple example. It and other examples should live in the examples folder and be included in docs/examples.rst.
+.. code:: python
+
+    # SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+    #
+    # SPDX-License-Identifier: Unlicense
+    import time
+    import terminalio
+    from adafruit_magtag.magtag import MagTag
+
+    magtag = MagTag()
+
+    magtag.add_text(
+        text_font=terminalio.FONT,
+        text_position=(
+            50,
+            (magtag.graphics.display.height // 2) - 1,
+        ),
+        text_scale=3,
+    )
+
+    magtag.set_text("Hello World")
+
+    buttons = magtag.peripherals.buttons
+    button_colors = ((255, 0, 0), (255, 150, 0), (0, 255, 255), (180, 0, 255))
+    button_tones = (1047, 1318, 1568, 2093)
+    timestamp = time.monotonic()
+
+    while True:
+        for i, b in enumerate(buttons):
+            if not b.value:
+                print("Button %c pressed" % chr((ord("A") + i)))
+                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)
+
 
 Contributing
 ============

adafruit_magtag/graphics.py

@@ -46,7 +46,7 @@ class Graphics:
     """
 
     # pylint: disable=too-many-instance-attributes, too-many-locals, too-many-branches, too-many-statements
-    def __init__(self, *, default_bg=None, auto_refresh=True, debug=False):
+    def __init__(self, *, default_bg=0xFFFFFF, auto_refresh=True, debug=False):
 
         self._debug = debug
         if not hasattr(board, "DISPLAY"):
@@ -139,7 +139,6 @@ def set_background(self, file_or_color, position=None):
         self._bg_group.append(self._bg_sprite)
         if self.auto_refresh:
             self.display.refresh()
-            sleep(5)
         gc.collect()
 
     def qrcode(

adafruit_magtag/magtag.py

@@ -65,7 +65,7 @@ def __init__(
         headers=None,
         json_path=None,
         regexp_path=None,
-        default_bg=None,
+        default_bg=0xFFFFFF,
         status_neopixel=None,
         json_transform=None,
         debug=False,
@@ -74,6 +74,7 @@ def __init__(
         self._debug = debug
         self.graphics = Graphics(
             default_bg=default_bg,
+            auto_refresh=False,
             debug=debug,
         )
         self.display = self.graphics.display

docs/api.rst

@@ -1,8 +1,19 @@
 
-.. If you created a package, create one automodule per module in the package.
 
-.. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)
-.. use this format as the module name: "adafruit_foo.foo"
+.. automodule:: adafruit_magtag.fakerequests
+   :members:
+
+.. automodule:: adafruit_magtag.graphics
+   :members:
+
+.. automodule:: adafruit_magtag.magtag
+   :members:
+
+.. automodule:: adafruit_magtag.network
+   :members:
+
+.. automodule:: adafruit_magtag.wifi_module
+   :members:
 
-.. automodule:: adafruit_magtag
+.. automodule:: adafruit_magtag.peripherals
    :members:

docs/conf.py

@@ -25,7 +25,7 @@
 # Uncomment the below if you use native CircuitPython modules such as
 # digitalio, micropython and busio. List the modules you use. Without it, the
 # autodoc module docs will fail to generate with a warning.
-# autodoc_mock_imports = ["digitalio", "busio"]
+autodoc_mock_imports = ["supervisor", "rtc", "ssl", "wifi", "socketpool", "secrets"]
 
 
 intersphinx_mapping = {

docs/examples.rst

@@ -6,3 +6,10 @@ Ensure your device works with this simple test.
 .. literalinclude:: ../examples/magtag_simpletest.py
     :caption: examples/magtag_simpletest.py
     :linenos:
+
+Other Demos
+------------
+
+.. literalinclude:: ../examples/bitcoin_demo.py
+    :caption: examples/bitcoin_demo.py
+    :linenos:

docs/index.rst

@@ -23,14 +23,12 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
-.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
+    * Adafruit MagTag <https://learn.adafruit.com/adafruit-magtag>
 
 .. toctree::
     :caption: Related Products
 
-.. todo:: Add any product links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
+    * Adafruit MagTag <https://www.adafruit.com/product/4800>
 
 .. toctree::
     :caption: Other Links

examples/bitcoin_demo.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+import time
+import terminalio
+from adafruit_magtag.magtag import MagTag
+
+# Set up where we'll be fetching data from
+DATA_SOURCE = "https://api.coindesk.com/v1/bpi/currentprice.json"
+DATA_LOCATION = ["bpi", "USD", "rate_float"]
+
+def text_transform(val):
+    return "Bitcoin: $%d" % val
+
+magtag = MagTag(
+    url=DATA_SOURCE, json_path=DATA_LOCATION,
+)
+
+magtag.network.connect()
+
+magtag.add_text(
+    text_font=terminalio.FONT,
+    text_position=(
+        10,
+        (magtag.graphics.display.height // 2) - 1,
+    ),
+    text_scale=3,
+    text_transform=text_transform,
+)
+
+magtag.preload_font(b"$012345789")  # preload numbers
+magtag.preload_font((0x00A3, 0x20AC))  # preload gbp/euro symbol
+
+timestamp = time.monotonic()
+
+while True:
+    if (time.monotonic() - timestamp) > 5:  # once a second...
+        try:
+            value = magtag.fetch()
+            print("Response is", value)
+        except (ValueError, RuntimeError) as e:
+            print("Some error occured, retrying! -", e)
+        timestamp = time.monotonic()
+
+    time.sleep(0.01)

examples/bitcoin_peripheral_demo.py

@@ -1,3 +1,36 @@
 # SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
 #
 # SPDX-License-Identifier: Unlicense
+import time
+import terminalio
+from adafruit_magtag.magtag import MagTag
+
+magtag = MagTag()
+
+magtag.add_text(
+    text_font=terminalio.FONT,
+    text_position=(
+        50,
+        (magtag.graphics.display.height // 2) - 1,
+    ),
+    text_scale=3,
+)
+
+magtag.set_text("Hello World")
+
+buttons = magtag.peripherals.buttons
+button_colors = ((255, 0, 0), (255, 150, 0), (0, 255, 255), (180, 0, 255))
+button_tones = (1047, 1318, 1568, 2093)
+timestamp = time.monotonic()
+
+while True:
+    for i, b in enumerate(buttons):
+        if not b.value:
+            print("Button %c pressed" % chr((ord("A") + i)))
+            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)