scrollkit 0.8.3__py3-none-any.whl

scrollkit/simulator/terminalio/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""CircuitPython terminalio compatibility module for SLDK simulator.
+
+Provides the default FONT for text rendering.
+"""
+
+import os
+from ..adafruit_bitmap_font import bitmap_font
+
+# Load the default font (viii.bdf - 8 pixels tall)
+_font_path = os.path.join(os.path.dirname(__file__), '..', 'fonts', 'viii.bdf')
+try:
+    FONT = bitmap_font.load_font(_font_path)
+except Exception as e:
+    print(f"Warning: Could not load default font from {_font_path}: {e}")
+    # Create a minimal fallback
+    FONT = None
+
+# For compatibility with existing code that imports the module
+__all__ = ['FONT']

scrollkit/utils/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger

scrollkit/utils/color_utils.py

@@ -0,0 +1,54 @@
+"""
+Color utilities for handling color conversions and manipulations.
+Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""
+
+# Color name to (r, g, b) tuple mapping, for quick prototyping/tooling. Distinct
+# from ColorUtils.colors below (Title-case names -> hex *strings*, used as
+# settings defaults) -- different names, different value format, both kept.
+NAMED_COLORS = {
+    'red': (255, 0, 0),
+    'green': (0, 255, 0),
+    'blue': (0, 0, 255),
+    'yellow': (255, 255, 0),
+    'purple': (128, 0, 128),
+    'cyan': (0, 255, 255),
+    'white': (255, 255, 255),
+    'orange': (255, 165, 0),
+    'pink': (255, 192, 203),
+    'magenta': (255, 0, 255),
+    'lime': (0, 255, 0),
+    'teal': (0, 128, 128),
+    'navy': (0, 0, 128),
+    'brown': (165, 42, 42),
+    'gray': (128, 128, 128),
+    'grey': (128, 128, 128),
+    'black': (0, 0, 0),
+}
+
+
+__all__ = ['ColorUtils', 'NAMED_COLORS']
+
+class ColorUtils:
+    """Utilities for handling colors and conversions"""
+    
+    # Color definitions as a class variable
+    colors = {
+        "Red": "0xff0000",
+        "Green": "0x00ff00",
+        "Blue": "0x0000ff",
+        "White": "0xffffff",
+        "Black": "0x000000",
+        "Purple": "0x800080",
+        "Yellow": "0xffff00",
+        "Orange": "0xffa500",
+        "Pink": "0xffc0cb",
+        "Old Lace": "0xfdf5e6"
+    }
+
+    # NOTE: the old static conversion helpers (to_rgb/from_rgb/scale_color/
+    # hex_str_to_rgb/pad_hex/hex_str_to_number/number_to_hex_string) were
+    # removed as dead code — zero callers anywhere, including tests and the
+    # app. The modern int-based color API is scrollkit.display.colors. This
+    # class survives only to carry the hex-string `colors` table the settings
+    # schema consumes.

scrollkit/utils/diagnostics.py

@@ -0,0 +1,227 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""On-device crash/boot diagnostics, persisted in ``microcontroller.nvm``.
+
+Why this exists: a field device can go black with no usable logs — a flash log
+fills and is wiped on every reboot, so a crash erases its own evidence. NVM
+survives BOTH soft resets and power loss and is independent of the filesystem, so
+a compact fixed-size record here lets an app:
+
+  * **break a reboot loop** from a deterministic fault (bad settings, an API
+    change that crashes every boot): after a few fault-resets with no clean run,
+    drop into *safe mode* (no fetch; keep the config web UI up) instead of
+    resetting forever;
+  * **explain "why it went black"** on a config web UI without a serial cable
+    (reset reason, last exception, consecutive failures, last success).
+
+NVM is wear-limited, so we write SPARINGLY: once per boot and only on state
+changes (first clean run, a crash) — never per refresh.
+
+The store takes an injectable ``backend`` (anything that behaves like a mutable
+``bytearray``) so the boot-loop logic is unit-tested on desktop; on hardware the
+backend is ``microcontroller.nvm``. On desktop with no NVM, ``open()`` returns a
+no-op store so callers never need platform checks.
+
+Usage::
+
+    from scrollkit.utils import diagnostics
+
+    diag = diagnostics.open()                       # NVM on device, no-op on desktop
+    diag.record_boot(diagnostics.read_reset_reason())
+    if diag.safe_mode:
+        ...                                        # skip the fetch; keep the UI up
+    diag.note_fetch_result(ok=True)                # on a healthy refresh
+"""
+
+# Fixed binary layout at the head of NVM. Tiny and stable; bump _VERSION if it
+# changes (a version/magic mismatch resets the record).
+_MAGIC = 0x7A
+_VERSION = 1
+
+_OFF_MAGIC = 0
+_OFF_VERSION = 1
+_OFF_BOOT_COUNT = 2          # 2 bytes, wraps
+_OFF_RAPID_BOOTS = 4         # 1 byte: boots since the last clean run
+_OFF_RESET_REASON = 5        # 1 byte: code from _REASON_CODES
+_OFF_CONSEC_FAILS = 6        # 1 byte: consecutive fetch failures (last known)
+_OFF_FLAGS = 7              # 1 byte: bit0 = entered safe mode last boot
+_OFF_MSG_LEN = 8           # 1 byte
+_OFF_MSG = 9               # ascii crash/exception text
+MSG_MAX = 180
+_SIZE = _OFF_MSG + MSG_MAX
+
+# After this many resets with no intervening clean run, enter safe mode.
+RAPID_BOOT_LIMIT = 4
+
+_FLAG_SAFE_MODE = 0x01
+
+# microcontroller.ResetReason names we care about -> small codes (and back, for
+# display). Stored as a code so we don't depend on the enum at read time.
+_REASON_NAMES = ("UNKNOWN", "POWER_ON", "BROWNOUT", "SOFTWARE",
+                 "DEEP_SLEEP_ALARM", "RESET_PIN", "WATCHDOG")
+
+
+__all__ = ['Diagnostics', 'open', 'read_reset_reason', 'MSG_MAX', 'RAPID_BOOT_LIMIT']
+
+class Diagnostics:
+    """Compact NVM-backed boot/crash record. All methods are failure-tolerant."""
+
+    def __init__(self, backend):
+        self._nvm = backend
+        # Per-boot snapshot, filled by record_boot().
+        self.boot_count = 0
+        self.rapid_boots = 0
+        self.reset_reason = "UNKNOWN"
+        self.safe_mode = False
+        self.last_message = ""
+        self.consecutive_failures = 0
+
+    # --- low-level helpers ---------------------------------------------------
+    def _read(self):
+        try:
+            n = self._nvm
+            if n is None or len(n) < _SIZE:
+                return None
+            if n[_OFF_MAGIC] != _MAGIC or n[_OFF_VERSION] != _VERSION:
+                return None
+            return bytes(n[0:_SIZE])
+        except Exception:
+            return None
+
+    def _write_byte(self, offset, value):
+        try:
+            self._nvm[offset] = value & 0xFF
+        except Exception:
+            pass
+
+    def _write_u16(self, offset, value):
+        try:
+            self._nvm[offset] = value & 0xFF
+            self._nvm[offset + 1] = (value >> 8) & 0xFF
+        except Exception:
+            pass
+
+    def _init_blank(self):
+        try:
+            self._nvm[_OFF_MAGIC] = _MAGIC
+            self._nvm[_OFF_VERSION] = _VERSION
+            for off in (_OFF_BOOT_COUNT, _OFF_BOOT_COUNT + 1, _OFF_RAPID_BOOTS,
+                        _OFF_RESET_REASON, _OFF_CONSEC_FAILS, _OFF_FLAGS,
+                        _OFF_MSG_LEN):
+                self._nvm[off] = 0
+        except Exception:
+            pass
+
+    # --- public API ----------------------------------------------------------
+    def record_boot(self, reset_reason_name="UNKNOWN"):
+        """Call once at the very start of boot. Increments counters, classifies
+        whether we're in a reboot loop, and returns ``self`` for chaining.
+
+        ``reset_reason_name`` is the ``microcontroller.cpu.reset_reason`` name
+        (the caller reads it; we just store the code so the web UI can show it)."""
+        raw = self._read()
+        if raw is None:
+            self._init_blank()
+            raw = self._read() or bytes(_SIZE)
+
+        self.boot_count = (raw[_OFF_BOOT_COUNT] | (raw[_OFF_BOOT_COUNT + 1] << 8)) + 1
+        # "Boots since the last clean run": every boot increments this; a healthy
+        # device zeroes it via note_clean_run() on its first good fetch, so it only
+        # climbs when boots keep happening with no clean run between them (a reboot
+        # loop). reset_reason is recorded for display but does NOT gate this count.
+        self.rapid_boots = raw[_OFF_RAPID_BOOTS] + 1
+        self.reset_reason = reset_reason_name
+        self.consecutive_failures = raw[_OFF_CONSEC_FAILS]
+        msg_len = min(raw[_OFF_MSG_LEN], MSG_MAX)
+        try:
+            self.last_message = bytes(raw[_OFF_MSG:_OFF_MSG + msg_len]).decode("ascii")
+        except Exception:
+            self.last_message = ""
+
+        self.safe_mode = self.rapid_boots > RAPID_BOOT_LIMIT
+
+        self._write_u16(_OFF_BOOT_COUNT, self.boot_count)
+        self._write_byte(_OFF_RAPID_BOOTS, min(self.rapid_boots, 255))
+        try:
+            self._write_byte(_OFF_RESET_REASON, _REASON_NAMES.index(reset_reason_name))
+        except Exception:
+            self._write_byte(_OFF_RESET_REASON, 0)
+        flags = _FLAG_SAFE_MODE if self.safe_mode else 0
+        self._write_byte(_OFF_FLAGS, flags)
+        return self
+
+    def note_clean_run(self):
+        """Call once the device is healthy (first successful fetch / stable run).
+        Zeroes the reboot-loop counter so transient single crashes never
+        accumulate into safe mode."""
+        self.rapid_boots = 0
+        self._write_byte(_OFF_RAPID_BOOTS, 0)
+
+    def note_fetch_result(self, ok, consecutive_failures=0):
+        """Record refresh outcome (state-change only — cheap). A success also
+        counts as a clean run."""
+        self.consecutive_failures = 0 if ok else consecutive_failures
+        self._write_byte(_OFF_CONSEC_FAILS, min(self.consecutive_failures, 255))
+        if ok:
+            self.note_clean_run()
+
+    def record_crash(self, message):
+        """Persist the last fatal exception text (truncated) before a reset."""
+        try:
+            text = "".join(c for c in str(message) if 32 <= ord(c) < 128)[:MSG_MAX]
+            data = text.encode("ascii")
+            self._write_byte(_OFF_MSG_LEN, len(data))
+            for i, b in enumerate(data):
+                self._nvm[_OFF_MSG + i] = b
+            self.last_message = text
+        except Exception:
+            pass
+
+    def summary(self):
+        """Dict for the config web UI / logs."""
+        return {
+            "boot_count": self.boot_count,
+            "reboot_streak": self.rapid_boots,
+            "reset_reason": self.reset_reason,
+            "safe_mode": self.safe_mode,
+            "consecutive_failures": self.consecutive_failures,
+            "last_error": self.last_message,
+        }
+
+
+class _NullDiagnostics(Diagnostics):
+    """No-op store for desktop / when NVM is unavailable."""
+    def __init__(self):
+        super().__init__(None)
+
+    def record_boot(self, reset_reason_name="UNKNOWN"):
+        return self
+
+    def note_clean_run(self):
+        pass
+
+    def note_fetch_result(self, ok, consecutive_failures=0):
+        pass
+
+    def record_crash(self, message):
+        pass
+
+
+def read_reset_reason():
+    """Return the microcontroller reset-reason NAME, or 'UNKNOWN' off-device."""
+    try:
+        import microcontroller
+        return str(microcontroller.cpu.reset_reason).rsplit(".", 1)[-1]
+    except Exception:
+        return "UNKNOWN"
+
+
+def open():
+    """Return a Diagnostics bound to NVM on hardware, else a no-op store."""
+    try:
+        import microcontroller
+        nvm = microcontroller.nvm
+        if nvm is not None and len(nvm) >= _SIZE:
+            return Diagnostics(nvm)
+    except Exception:
+        pass
+    return _NullDiagnostics()

scrollkit/utils/error_handler.py

@@ -0,0 +1,347 @@
+"""
+Error handling utility for logging errors and debug information.
+Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""
+import os
+import traceback
+
+try:
+    import storage
+except (ImportError, AttributeError):
+    # `storage` is a CircuitPython-only module. Bind it to None on desktop so the
+    # module attribute always exists (the detection branch below gates on
+    # `storage is not None`, and tests patch this name).
+    storage = None
+
+__all__ = ['ErrorHandler']
+
+class ErrorHandler:
+    """
+    Centralized error handling and logging facility.
+    Handles writing to log files with fallback to console output.
+    """
+    
+    # Class-level registry to track instances by filename
+    _instances = {}
+    
+    # Class-level mode setting
+    DEVELOPMENT = "development"
+    PRODUCTION = "production"
+    _mode = PRODUCTION  # Default to production mode
+
+    # Cap each log generation so logging can never fill the device's tiny flash
+    # (the field failure: unbounded append eventually fills storage and the app
+    # can't write settings/cache and goes dark). When the file reaches this size
+    # it is rotated to "<file>.old" (one generation kept), bounding total log
+    # storage to ~2x this value while preserving recent history.
+    MAX_LOG_BYTES = 16384
+
+    def __new__(cls, file_name, mode=None):
+        """Return one shared instance per log file.
+
+        The previous code faked a singleton inside __init__ by copying fields out of
+        the cached instance into a *newly allocated* object and returning that — so
+        every ``ErrorHandler("error_log")`` was a distinct object. When one detected
+        a read-only filesystem and set is_readonly=True, the others never saw it and
+        kept thrashing the filesystem on every write; mode/state diverged silently.
+        Holding identity in __new__ makes all callers share a single object.
+        """
+        inst = cls._instances.get(file_name)
+        if inst is None:
+            inst = super().__new__(cls)
+            cls._instances[file_name] = inst
+        return inst
+
+    def __init__(self, file_name, mode=None):
+        """
+        Initialize the error handler with read-only filesystem detection
+
+        Args:
+            file_name: The name of the log file
+            mode: Either 'development' or 'production' (optional, uses class default if not specified)
+        """
+        # Shared singleton: run setup exactly once per file. A later construction may
+        # still update the mode when the caller passes one explicitly (an explicit
+        # override wins); otherwise first-construction state stands.
+        if getattr(self, "_initialized", False):
+            if mode is not None:
+                self.mode = mode
+            return
+        self._initialized = True
+
+        # Continue with normal initialization for new instance
+        self.fileName = file_name
+        # Set instance mode - use parameter if provided, otherwise use class default
+        self.mode = mode if mode else ErrorHandler._mode
+        # Start with the assumption that the filesystem is read-only
+        # We'll only set it to writable if we can successfully write to it
+        self.is_readonly = True
+
+        # First check if we can directly detect read-only status via storage module
+        if storage is not None:
+            try:
+                # Get mount location
+                mount_path = '/'
+                try:
+                    # Try to get the mount path for the file's directory
+                    dir_path = os.path.dirname(file_name)
+                    if dir_path and os.path.exists(dir_path):
+                        mount_path = dir_path
+                except OSError:
+                    pass
+                    
+                # Check if storage shows readonly
+                self.is_readonly = storage.getmount(mount_path).readonly
+                print(f"Filesystem read-only status from storage: {self.is_readonly}")
+                
+                # If storage says it's read-only, trust that and skip the write test
+                if self.is_readonly:
+                    print("Filesystem is read-only according to storage module")
+                    print("ErrorHandler initialized - read-only filesystem")  # Exact match for test
+                    return
+            except (AttributeError, OSError):
+                # Continue with write test if storage check fails
+                print("Storage module check failed, will try write test")
+
+        # Preserve crash evidence across reboots. The old code deleted the log here
+        # AND truncated it with a 'w' write-test below, so a crash -> reboot erased
+        # exactly the log that would explain the crash (why field failures were
+        # undiagnosable). Only DEVELOPMENT starts each run with a fresh log.
+        if self.mode == ErrorHandler.DEVELOPMENT:
+            try:
+                if self.file_exists(file_name):
+                    print(f"Deleting existing log file: {file_name}")
+                    os.remove(file_name)
+            except OSError:
+                # Can't delete, assume readonly
+                self.is_readonly = True
+                print(f"Failed to delete existing log file: {file_name}")
+
+        # Verify writability WITHOUT truncating: append-open creates the file if it
+        # is missing and leaves any existing contents intact (so PRODUCTION keeps
+        # the prior session's log for post-mortem).
+        try:
+            with open(self.fileName, 'a'):
+                pass
+            self.is_readonly = False
+        except OSError as e:
+            # If any error occurs during write/create, filesystem is read-only
+            self.is_readonly = True
+            print(f"Write test failed: {str(e)}")
+
+        # Log system state at initialization based on final determination
+        if self.is_readonly:
+            print("ErrorHandler initialized - read-only filesystem")
+        else:
+            print("ErrorHandler initialized - writable filesystem")
+
+    @classmethod
+    def set_mode(cls, mode):
+        """
+        Set the global mode for all new ErrorHandler instances
+        
+        Args:
+            mode: Either 'development' or 'production'
+        """
+        if mode in [cls.DEVELOPMENT, cls.PRODUCTION]:
+            cls._mode = mode
+        else:
+            raise ValueError(f"Invalid mode: {mode}. Must be either '{cls.DEVELOPMENT}' or '{cls.PRODUCTION}'")
+    
+    @classmethod
+    def get_mode(cls):
+        """
+        Get the current global mode
+        
+        Returns:
+            The current mode string
+        """
+        return cls._mode
+
+    @staticmethod
+    def filter_non_ascii(text):
+        """
+        Filter out non-ASCII characters from a string
+        
+        Args:
+            text: The text to filter
+            
+        Returns:
+            A string with only ASCII characters
+        """
+        if text is None:
+            return ""
+        return "".join(c for c in str(text) if ord(c) < 128)
+
+    @staticmethod
+    def file_exists(file_name):
+        """
+        Check if a file exists
+        
+        Args:
+            file_name: The name of the file to check
+            
+        Returns:
+            True if the file exists, False otherwise
+        """
+        file_exists = True
+        try:
+            status = os.stat(file_name)
+        except OSError:
+            file_exists = False
+        return file_exists
+
+    def error(self, e, str_description):
+        """
+        Log an error with a description and stack trace
+
+        Args:
+            e: The exception that occurred
+            str_description: A description of the error
+        """
+        # Handle the case where e is None (no exception but error message)
+        if e is None:
+            except_str = str_description
+            st_str = ""
+        else:
+            except_str = str_description + ":" + str(e)
+            try:
+                st = traceback.format_exception(e)
+                st_str = "stack trace:"
+                for line in st:
+                    st_str = st_str + line
+            except Exception:
+                # Fallback for cases where traceback.format_exception fails
+                st_str = "stack trace unavailable"
+
+        # Filter out non-ASCII characters to prevent UnicodeEncodeError
+        filtered_except_str = self.filter_non_ascii(except_str)
+        filtered_st_str = self.filter_non_ascii(st_str)
+
+        # Always print errors to console for visibility
+        print(filtered_except_str)
+        if filtered_st_str:
+            print(filtered_st_str)
+
+        # Only attempt to write to file if filesystem is writable. Errors ARE
+        # persisted in both modes (they're the post-mortem); rotation keeps the
+        # file bounded so even an error storm can't fill flash.
+        if not self.is_readonly:
+            self._rotate_if_needed()
+            try:
+                with open(self.fileName, 'a') as file:
+                    file.write(filtered_except_str + "\n")
+                    if filtered_st_str:
+                        file.write(filtered_st_str + "\n")
+            except OSError:
+                # If write fails unexpectedly, update readonly state
+                self.is_readonly = True
+                # Only print this message once when we first detect a failure
+                print("Filesystem detected as read-only, logs will be displayed on console only")
+
+    def debug(self, message):
+        """
+        Log a debug message
+        
+        Args:
+            message: The debug message to log
+        """
+        print(message)
+        # Only write debug messages to file in development mode
+        if self.mode == ErrorHandler.DEVELOPMENT:
+            self.write_to_file(message)
+
+    def _rotate_if_needed(self):
+        """Rotate the log to '<file>.old' once it reaches MAX_LOG_BYTES, so logging
+        can never fill flash. Keeps one prior generation."""
+        if self.is_readonly:
+            return
+        try:
+            size = os.stat(self.fileName)[6]   # st_size
+        except OSError:
+            return
+        if size < self.MAX_LOG_BYTES:
+            return
+        backup = self.fileName + ".old"
+        try:
+            try:
+                os.remove(backup)              # drop the older generation
+            except OSError:
+                pass
+            os.rename(self.fileName, backup)
+        except OSError:
+            # Rename failed (transient FS hiccup). Do NOT blind-truncate here: the
+            # old code did `open(file, 'w')`, destroying exactly the recent crash
+            # evidence this log exists to preserve. Prefer a tail-preserving trim
+            # that keeps the most recent bytes; if even that fails, skip rotation
+            # this cycle (keep appending, accept temporary oversize) and leave a
+            # one-line marker. rename is retried next cycle and usually succeeds.
+            if not self._tail_trim():
+                try:
+                    with open(self.fileName, 'a') as f:
+                        f.write("[log rotation failed; not truncated]\n")
+                except OSError:
+                    self.is_readonly = True
+
+    def _tail_trim(self):
+        """Rewrite the log keeping only its most recent bytes — the fallback for when
+        rename-based rotation is unavailable, preserving recent crash evidence while
+        still bounding size. Returns True on success, False if seek/read/rewrite is
+        not reliable on this filesystem (the caller then leaves the file intact
+        rather than destroying it). Binary mode so end-relative seeks work on both
+        CPython and CircuitPython."""
+        keep = self.MAX_LOG_BYTES // 2
+        try:
+            with open(self.fileName, 'rb') as f:
+                try:
+                    f.seek(-keep, 2)           # last `keep` bytes (whence 2 = end)
+                except (OSError, ValueError):
+                    f.seek(0)                  # file smaller than keep / no end-seek
+                tail = f.read()
+            with open(self.fileName, 'wb') as f:
+                f.write(b"[log trimmed to recent history]\n")
+                f.write(tail)
+            return True
+        except (OSError, ValueError):
+            return False
+
+    def write_to_file(self, message):
+        """
+        Write a message to the log file
+
+        Args:
+            message: The message to write
+        """
+        # Only attempt to write if filesystem is writable
+        if self.is_readonly:
+            # In read-only mode, we'll just print to console without error messages
+            # We don't print "Error writing to log file" as that confuses users
+            return
+
+        self._rotate_if_needed()
+        try:
+            # Filter out non-ASCII characters to prevent UnicodeEncodeError
+            filtered_message = self.filter_non_ascii(message)
+
+            with open(self.fileName, 'a') as file:
+                file.write(filtered_message + "\n")
+        except OSError:
+            # If write fails unexpectedly, update readonly state
+            self.is_readonly = True
+            # Only print this message once when we first detect a failure
+            print("Filesystem detected as read-only, logs will be displayed on console only")
+
+    def info(self, message):
+        """
+        Log an informational message
+        
+        Args:
+            message: The informational message to log
+        """
+        print(message)
+        # Info is high-frequency (every fetch attempt/success). Persisting it to
+        # flash on every refresh fills the device's tiny storage over days, so write
+        # it only in DEVELOPMENT; PRODUCTION keeps info on the console. Errors are
+        # still persisted in both modes (see error()).
+        if self.mode == ErrorHandler.DEVELOPMENT:
+            self.write_to_file(message)