scrollkit 0.8.3__py3-none-any.whl

scrollkit/utils/system_utils.py

@@ -0,0 +1,245 @@
+"""
+System utilities for hardware and system operations.
+Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+
+Time-setting is deliberately resilient rather than precise: for these displays
+"close enough" is fine, but the clock must get set even on hostile networks.
+``set_system_clock`` cascades through independent sources:
+
+  1. NTP across several reliable servers (the gold standard) — but a single shot
+     at pool.ntp.org is unreliable (random dead/slow pool members) and NTP needs
+     outbound UDP/123, which guest wifi / captive portals / some ISPs block.
+  2. The HTTP ``Date`` response header from a reachable host — works wherever
+     HTTPS works, i.e. exactly the networks that block NTP. Accurate to ~1s.
+"""
+import sys  # noqa: F401  (kept for parity with the embedded build)
+import time
+import asyncio  # noqa: F401
+
+# Import hardware-specific modules or mock them
+try:
+    import rtc
+    import microcontroller  # noqa: F401
+    HAS_HARDWARE = True
+except ModuleNotFoundError:
+    # Mocking the unavailable modules in non-embedded environments
+    from adafruit_datetime import datetime
+
+    class rtc:
+        class RTC:
+            def __init__(self):
+                self.datetime = datetime()
+
+    HAS_HARDWARE = False
+
+# Try to import adafruit_ntp, with fallback if not available
+try:
+    import adafruit_ntp
+    HAS_NTP = True
+except Exception:
+    HAS_NTP = False
+
+
+# NTP servers tried in order. A single query to pool.ntp.org is unreliable in the
+# field: it resolves to a RANDOM pool member, many of which are dead, slow
+# (10-20s), or rate-limiting ("aggressive denial"). So we lead with single-operator
+# anycast servers that don't have that problem and fall through to the pool last.
+# Override via the `servers` argument.
+DEFAULT_NTP_SERVERS = ("time.cloudflare.com", "time.google.com", "pool.ntp.org")
+
+# HTTPS hosts to read the 'Date' response header from when NTP is unreachable.
+# Any HTTPS host returns a Date header; these are highly available. If your app
+# already fetches from a reliable host, pass it via `http_date_hosts` to avoid an
+# extra dependency.
+DEFAULT_HTTP_DATE_HOSTS = ("https://time.cloudflare.com", "https://www.google.com")
+
+_MONTHS = {"Jan": 1, "Feb": 2, "Mar": 3, "Apr": 4, "May": 5, "Jun": 6,
+           "Jul": 7, "Aug": 8, "Sep": 9, "Oct": 10, "Nov": 11, "Dec": 12}
+
+
+__all__ = ['set_system_clock', 'set_system_clock_ntp', 'DEFAULT_NTP_SERVERS', 'DEFAULT_HTTP_DATE_HOSTS']
+
+async def set_system_clock_ntp(socket_pool, tz_offset=None, servers=None,
+                               socket_timeout=5):
+    """
+    Set device time using NTP, trying several servers until one responds.
+
+    NTP is the right technique for these devices, but a single shot at
+    pool.ntp.org fails often in the field (random dead/slow pool members). This
+    tries a list of independent, reliable servers and uses the first that answers,
+    with a short per-server timeout so a dead server fails fast.
+
+    Args:
+        socket_pool: SocketPool instance for NTP (must have getaddrinfo).
+        tz_offset: Timezone offset in hours (defaults to US Eastern, -5).
+        servers: Iterable of NTP server hostnames to try in order
+            (defaults to DEFAULT_NTP_SERVERS).
+        socket_timeout: Per-server timeout in seconds (default 5).
+
+    Returns:
+        True if any server set the clock, False if every server failed.
+    """
+    from scrollkit.utils.error_handler import ErrorHandler
+    logger = ErrorHandler("error_log")
+
+    if not HAS_NTP or not HAS_HARDWARE:
+        logger.info("NTP module not available or hardware not supported")
+        return False
+
+    # Validate socket_pool is a proper socket pool object
+    if socket_pool is None or not hasattr(socket_pool, 'getaddrinfo'):
+        logger.error(None, "Invalid socket pool provided for NTP, socket pool must have getaddrinfo")
+        return False
+
+    # Timezone offset: default to EST (-5 hours)
+    if tz_offset is None:
+        tz_offset = -5
+
+    for server in (servers if servers is not None else DEFAULT_NTP_SERVERS):
+        try:
+            logger.info(f"Getting time from NTP server {server} (tz_offset {tz_offset})")
+            ntp = adafruit_ntp.NTP(socket_pool, server=server, tz_offset=tz_offset,
+                                   socket_timeout=socket_timeout)
+            current_time = ntp.datetime
+
+            # Convert to a tuple for the RTC module
+            datetime_tuple = (
+                current_time.tm_year,    # Year
+                current_time.tm_mon,     # Month
+                current_time.tm_mday,    # Day
+                current_time.tm_hour,    # Hour
+                current_time.tm_min,     # Minute
+                current_time.tm_sec,     # Second
+                current_time.tm_wday,    # Day of week (0-6)
+                -1,                      # Day of year (not necessary)
+                -1                       # DST flag (not necessary)
+            )
+
+            rtc.RTC().datetime = datetime_tuple
+            logger.info(f"System clock set to {datetime_tuple} via NTP ({server})")
+            return True
+
+        except Exception as e:
+            logger.error(e, f"NTP server {server} failed, trying next")
+            # Reclaim the failed NTP object (and any socket/SSL allocations it
+            # held) before trying the next server. On the RAM-constrained ESP32-S3
+            # this curbs heap fragmentation across the failover loop — cheap
+            # insurance on a once-at-boot path. No-op cost on desktop.
+            import gc
+            gc.collect()
+            continue
+
+    logger.error(None, "All NTP servers failed to respond")
+    return False
+
+
+def _parse_http_date(date_header):
+    """Parse an RFC 1123 HTTP 'Date' header (always UTC) into a UTC time tuple.
+
+    e.g. 'Wed, 21 Oct 2025 07:28:00 GMT' -> (2025, 10, 21, 7, 28, 0).
+    Returns None if it can't be parsed.
+    """
+    try:
+        parts = date_header.split(" ")
+        # ['Wed,', '21', 'Oct', '2025', '07:28:00', 'GMT']
+        day = int(parts[1])
+        month = _MONTHS[parts[2]]
+        year = int(parts[3])
+        hour, minute, second = (int(x) for x in parts[4].split(":"))
+        return (year, month, day, hour, minute, second)
+    except (ValueError, KeyError, IndexError):
+        return None
+
+
+def _utc_to_local_tuple(utc, tz_offset):
+    """Shift a (Y, M, D, h, m, s) UTC tuple by tz_offset hours into an RTC tuple.
+
+    Uses time.mktime/localtime, which on CircuitPython operate in UTC (no timezone
+    database), so this yields the correct local wall-clock for the given offset and
+    normalizes any day/month rollover. Returns None on overflow/parse error.
+    """
+    try:
+        year, month, day, hour, minute, second = utc
+        epoch = time.mktime((year, month, day, hour, minute, second, 0, -1, -1))
+        lt = time.localtime(epoch + int(tz_offset * 3600))
+        return (lt.tm_year, lt.tm_mon, lt.tm_mday, lt.tm_hour,
+                lt.tm_min, lt.tm_sec, lt.tm_wday, -1, -1)
+    except (OverflowError, OSError, ValueError):
+        return None
+
+
+async def _set_clock_from_http_date(http_client, tz_offset, hosts, logger):
+    """Set the RTC from the HTTP 'Date' response header of a reachable host.
+
+    Works on networks that block NTP (UDP/123) but allow HTTPS. ~1s accurate.
+    Returns the datetime tuple that was set, or None if no host answered.
+    """
+    for url in hosts:
+        try:
+            resp = await http_client.get(url)
+            headers = getattr(resp, "headers", None) or {}
+            date_hdr = headers.get("Date") or headers.get("date")
+            if not date_hdr:
+                logger.info(f"No Date header from {url}")
+                continue
+            utc = _parse_http_date(date_hdr)
+            if utc is None:
+                logger.error(None, f"Could not parse Date header from {url}: {date_hdr}")
+                continue
+            dt = _utc_to_local_tuple(utc, tz_offset)
+            if dt is None:
+                continue
+            if HAS_HARDWARE:
+                rtc.RTC().datetime = dt
+            logger.info(f"System clock set to {dt} via HTTP Date header ({url})")
+            return dt
+        except Exception as e:
+            logger.error(e, f"HTTP time from {url} failed")
+            continue
+    return None
+
+
+async def set_system_clock(http_client, socket_pool=None, tz_offset=None,
+                           http_date_hosts=None):
+    """
+    Set the device clock as reliably as possible (accuracy is not critical).
+
+    Cascades through independent sources, first that answers wins:
+      1. NTP across several reliable servers (needs UDP/123 open).
+      2. The HTTP 'Date' response header (works where NTP is blocked).
+
+    Args:
+        http_client: HTTP client used for the Date-header fallback.
+        socket_pool: Optional socket pool for NTP.
+        tz_offset: Timezone offset in hours (defaults to US Eastern, -5).
+        http_date_hosts: Optional list of HTTPS hosts for the Date-header
+            fallback (defaults to DEFAULT_HTTP_DATE_HOSTS). Prefer a host you
+            already fetch from.
+
+    Returns:
+        The datetime tuple that was set, or None if every source failed.
+    """
+    from scrollkit.utils.error_handler import ErrorHandler
+    logger = ErrorHandler("error_log")
+
+    if tz_offset is None:
+        tz_offset = -5
+
+    # 1. NTP (multi-server failover) — accurate, but needs UDP/123 open.
+    if HAS_NTP and socket_pool is not None:
+        logger.info("Setting time via NTP...")
+        try:
+            if await set_system_clock_ntp(socket_pool, tz_offset=tz_offset):
+                logger.info("System clock set via NTP")
+                return rtc.RTC().datetime
+        except Exception as e:
+            logger.error(e, "NTP failed; falling back to the HTTP Date header")
+
+    # 2. HTTP 'Date' header — survives networks that block NTP.
+    logger.info("Setting time via the HTTP Date header...")
+    hosts = http_date_hosts if http_date_hosts is not None else DEFAULT_HTTP_DATE_HOSTS
+    dt = await _set_clock_from_http_date(http_client, tz_offset, hosts, logger)
+    if dt is None:
+        logger.error(None, "Failed to set system clock - no time source reachable "
+                           "(NTP and HTTP Date both failed)")
+    return dt

scrollkit/utils/url_utils.py

@@ -0,0 +1,46 @@
+"""
+URL utilities for handling URL encoding and decoding.
+Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""
+
+
+__all__ = ['url_decode', 'load_credentials']
+
+def url_decode(input_string):
+    """
+    Decode URL-encoded strings
+    
+    Args:
+        input_string: The URL-encoded string to decode
+        
+    Returns:
+        The decoded string
+    """
+    input_string = input_string.replace('+', ' ')
+    hex_chars = "0123456789abcdef"
+    result = ""
+    i = 0
+    while i < len(input_string):
+        if input_string[i] == "%" and i < len(input_string) - 2:
+            hex_value = input_string[i + 1:i + 3].lower()
+            if all(c in hex_chars for c in hex_value):
+                result += chr(int(hex_value, 16))
+                i += 3
+                continue
+        result += input_string[i]
+        i += 1
+    return result
+
+
+def load_credentials():
+    """
+    Load WiFi credentials from secrets.py
+    
+    Returns:
+        A tuple of (ssid, password)
+    """
+    try:
+        from secrets import secrets
+        return secrets['ssid'], secrets['password']
+    except ImportError:
+        return "", ""

scrollkit/web/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""ScrollKit web — default settings UI on native adafruit_httpserver."""
+
+from .settings_server import SettingsWebServer
+
+__all__ = ["SettingsWebServer"]

scrollkit/web/settings_server.py

@@ -0,0 +1,328 @@
+"""Default settings web UI for ScrollKit apps — native ``adafruit_httpserver``.
+
+``SettingsWebServer`` reads ``SettingsManager._schema`` (populated by
+``SettingsManager.define()``) and auto-generates an HTML settings form.
+No app-level web code is required: just call ``define()`` on the settings
+object and the base class wires the server up automatically.
+
+The same server object runs on desktop CPython (stdlib ``socket`` as the
+pool) and on the MatrixPortal S3 (``socketpool.SocketPool(wifi.radio)``).
+``adafruit_httpserver`` is lazy-imported inside ``_build_server()`` so the
+module is safe to import on memory-constrained CircuitPython before the
+memory gate in ``_web_server_process()`` clears.
+
+Routes:
+    GET  /      — render the settings form
+    POST /save  — persist settings, call ``app.notify_settings_changed()``
+                  (a flag the display loop applies at its next frame — this
+                  server never mutates display/queue state itself), redirect
+                  303 to /
+
+Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""
+from __future__ import annotations
+
+_SEE_OTHER = (303, "See Other")
+_POLL_INTERVAL = 0.05   # seconds between poll() calls (~20×/s, matches display loop)
+
+
+__all__ = ['SettingsWebServer']
+
+# adafruit_httpserver does not URL-decode form values. The shared
+# CircuitPython-safe decoder lives in utils — one implementation, not two.
+from ..utils.url_utils import url_decode as _url_decode
+
+
+# --------------------------------------------------------------------------- #
+# HTML helpers
+# --------------------------------------------------------------------------- #
+
+def _esc(text):
+    return (str(text).replace("&", "&amp;").replace("<", "&lt;")
+            .replace(">", "&gt;").replace('"', "&quot;"))
+
+
+_PAGE_HEADER = """<!DOCTYPE html>
+<html><head><meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Settings</title>
+<style>
+body{font-family:sans-serif;max-width:480px;margin:40px auto;padding:0 16px;background:#f5f5f5}
+h1{font-size:1.2em;margin-bottom:24px;color:#222}
+.field{margin-bottom:16px}
+label{display:block;font-size:.85em;color:#555;margin-bottom:4px}
+input[type=text],input[type=number],select{
+  width:100%;padding:8px;border:1px solid #ccc;border-radius:4px;
+  box-sizing:border-box;font-size:1em;background:#fff}
+input[type=range]{width:100%;vertical-align:middle}
+.range-row{display:flex;gap:8px;align-items:center}
+.range-val{min-width:2.5em;text-align:right;color:#333;font-size:.9em}
+input[type=color]{width:48px;height:32px;border:1px solid #ccc;
+  border-radius:4px;padding:2px;cursor:pointer}
+.checkbox-row{display:flex;align-items:center;gap:8px;cursor:pointer}
+.checkbox-row input{width:16px;height:16px}
+button{background:#333;color:#fff;border:none;padding:10px 28px;
+  border-radius:4px;font-size:1em;cursor:pointer;margin-top:8px}
+button:hover{background:#555}
+</style></head>
+<body><h1>Settings</h1>
+<form method="POST" action="/save">
+"""
+
+_PAGE_FOOTER = """<button type="submit">Save</button>
+</form></body></html>
+"""
+
+
+def _color_to_html(value):
+    """Convert stored color value (int or hex string) to #rrggbb for HTML."""
+    if isinstance(value, int):
+        return "#{:06x}".format(value & 0xFFFFFF)
+    if isinstance(value, str):
+        if value.startswith("#"):
+            return value
+        if value.startswith("0x") or value.startswith("0X"):
+            return "#" + value[2:].lower()
+    return "#ffffff"
+
+
+# --------------------------------------------------------------------------- #
+# SettingsWebServer
+# --------------------------------------------------------------------------- #
+
+class SettingsWebServer:
+    """Auto-generating settings web server driven by ``SettingsManager._schema``.
+
+    Implements the ``ScrollKitApp`` web contract:
+    ``await start()`` → bool, ``get_server_url()`` → str,
+    ``await run_forever()``, ``await stop()``.
+    """
+
+    def __init__(self, settings_manager, app=None, host="0.0.0.0", port=80):
+        self._sm = settings_manager
+        self._app = app
+        self._host = host
+        self._port = port
+        self._server = None
+        self._running = False
+        self._server_url = ""
+
+    # ------------------------------------------------------------------ #
+    # Internal: build server + routes (lazy adafruit_httpserver import)
+    # ------------------------------------------------------------------ #
+
+    def _build_server(self):
+        import sys
+        import socket as _stdlib_socket
+        from adafruit_httpserver import Server, Response, Redirect, GET, POST
+
+        is_cp = (hasattr(sys, "implementation")
+                 and sys.implementation.name == "circuitpython")
+
+        if is_cp:
+            import socketpool
+            import wifi
+            pool = socketpool.SocketPool(wifi.radio)
+            display_host = str(wifi.radio.ipv4_address)
+        else:
+            pool = _stdlib_socket
+            display_host = self._host if self._host != "0.0.0.0" else "localhost"
+
+        self._server = Server(pool, root_path=None, debug=False)
+        self._server_url = "http://{}:{}/".format(display_host, self._port)
+
+        # Capture references for route closures.
+        _self = self
+        sm = self._sm
+        app = self._app
+
+        @self._server.route("/", [GET])
+        def _index(request):
+            return Response(request, _self._render_form(), content_type="text/html")
+
+        @self._server.route("/save", [POST])
+        def _save(request):
+            _self._apply(request, sm, app)
+            return Redirect(request, "/", status=_SEE_OTHER)
+
+    # ------------------------------------------------------------------ #
+    # Internal: form rendering
+    # ------------------------------------------------------------------ #
+
+    def _render_form(self):
+        sm = self._sm
+        parts = [_PAGE_HEADER]
+
+        for field in sm._schema:
+            key = field["key"]
+            ftype = field["type"]
+            label = _esc(field["label"])
+            value = sm.get(key, field["default"])
+
+            if ftype == "checkbox":
+                checked = " checked" if value else ""
+                parts.append(
+                    '<div class="field"><label class="checkbox-row">'
+                    '<input type="checkbox" name="%s" value="1"%s>'
+                    ' %s</label></div>' % (key, checked, label)
+                )
+
+            elif ftype == "color":
+                html_val = _color_to_html(value)
+                parts.append(
+                    '<div class="field"><label>%s</label>'
+                    '<input type="color" name="%s" value="%s"></div>'
+                    % (label, key, html_val)
+                )
+
+            elif ftype == "range":
+                val_str = str(value)
+                mn = "" if field["min"] is None else str(field["min"])
+                mx = "" if field["max"] is None else str(field["max"])
+                st = "1" if field["step"] is None else str(field["step"])
+                parts.append(
+                    '<div class="field"><label>%s</label>'
+                    '<div class="range-row">'
+                    '<input type="range" name="%s" min="%s" max="%s" step="%s"'
+                    ' value="%s" oninput="this.nextElementSibling.textContent=this.value">'
+                    '<span class="range-val">%s</span>'
+                    '</div></div>'
+                    % (label, key, mn, mx, st, val_str, val_str)
+                )
+
+            elif ftype == "select":
+                opts = []
+                for o in (field["options"] or []):
+                    sel = " selected" if o == value else ""
+                    opts.append('<option%s>%s</option>' % (sel, _esc(o)))
+                parts.append(
+                    '<div class="field"><label>%s</label>'
+                    '<select name="%s">%s</select></div>'
+                    % (label, key, "".join(opts))
+                )
+
+            elif ftype == "number":
+                mn = ("" if field["min"] is None
+                      else ' min="%s"' % field["min"])
+                mx = ("" if field["max"] is None
+                      else ' max="%s"' % field["max"])
+                st = ("" if field["step"] is None
+                      else ' step="%s"' % field["step"])
+                parts.append(
+                    '<div class="field"><label>%s</label>'
+                    '<input type="number" name="%s"%s%s%s value="%s"></div>'
+                    % (label, key, mn, mx, st, str(value))
+                )
+
+            else:  # text
+                parts.append(
+                    '<div class="field"><label>%s</label>'
+                    '<input type="text" name="%s" value="%s"></div>'
+                    % (label, key, _esc(str(value)))
+                )
+
+        parts.append(_PAGE_FOOTER)
+        return "".join(parts)
+
+    # ------------------------------------------------------------------ #
+    # Internal: apply POSTed form to settings
+    # ------------------------------------------------------------------ #
+
+    def _apply(self, request, sm, app):
+        fd = getattr(request, "form_data", None)
+
+        # Collect present keys so absent checkboxes can be detected.
+        form_keys = set()
+        if fd is not None:
+            try:
+                for k in fd.keys():
+                    form_keys.add(k)
+            except Exception:
+                pass
+
+        def _get(key):
+            if fd is None:
+                return None
+            try:
+                v = fd.get(key)
+                if isinstance(v, bytes):
+                    v = v.decode("utf-8", "replace")
+                if isinstance(v, str):
+                    v = _url_decode(v)
+                return v
+            except Exception:
+                return None
+
+        for field in sm._schema:
+            key = field["key"]
+            ftype = field["type"]
+
+            if ftype == "checkbox":
+                sm.set(key, key in form_keys)
+                continue
+
+            raw = _get(key)
+            if raw is None:
+                continue
+
+            if ftype == "color":
+                try:
+                    value = int(raw.lstrip("#"), 16)
+                except (ValueError, AttributeError):
+                    continue
+
+            elif ftype in ("range", "number"):
+                try:
+                    if isinstance(field["default"], float):
+                        value = float(raw)
+                    else:
+                        value = int(float(raw))
+                except (ValueError, TypeError):
+                    continue
+
+            else:  # text, select
+                value = raw
+
+            sm.set(key, value)
+
+        sm.save_settings()
+
+        # The web server must never mutate display/queue state itself (see
+        # notify_settings_changed()) — it may only write settings and flag the
+        # main display loop to apply them at a safe frame boundary.
+        if app is not None and hasattr(app, "notify_settings_changed"):
+            app.notify_settings_changed()
+
+    # ------------------------------------------------------------------ #
+    # ScrollKitApp web contract
+    # ------------------------------------------------------------------ #
+
+    async def start(self):
+        try:
+            self._build_server()
+            self._server.start(self._host, self._port)
+            self._running = True
+            return True
+        except Exception as e:
+            print("SettingsWebServer start failed:", e)
+            return False
+
+    def get_server_url(self):
+        return self._server_url
+
+    async def run_forever(self):
+        import asyncio
+        while self._running:
+            try:
+                self._server.poll()
+            except OSError as e:
+                print("settings server poll error:", e)
+            await asyncio.sleep(_POLL_INTERVAL)
+
+    async def stop(self):
+        self._running = False
+        try:
+            if self._server is not None:
+                self._server.stop()
+        except Exception:
+            pass