rpi-app-framework 0.1.2__tar.gz

rpi_app_framework-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John Singer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rpi_app_framework-0.1.2/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: rpi-app-framework
+Version: 0.1.2
+Summary: A Python framework for building applications on all Raspberry Pi versions, including Pico.
+Home-page: https://github.com/yourusername/rpi-app-framework
+Author: Your Name
+Author-email: John Singer <john@singerlinks.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jsinger0420/rpi-app-framework
+Project-URL: Repository, https://github.com/jsinger0420/rpi-app-framework.git
+Project-URL: Documentation, https://github.com/jsinger0420/rpi-app-framework/wiki
+Project-URL: Bug Tracker, https://github.com/jsinger0420/rpi-app-framework/issues
+Keywords: raspberry-pi,pico,framework,app-development,iot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pi
+Requires-Dist: RPi.GPIO>=0.7.0; extra == "pi"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+RPi App Framework
+Modular framework for all Raspberry Pi models (Pico 2 W with MicroPython/Thonny, full RPi 1-5 with Python).
+Installation
+For MicroPython/Pico (Thonny):
+
+Copy the rpi_app_framework folder to /lib on your Pico.
+
+For full Python/RPi:
+
+pip install rpi-app-framework
+
+Usage
+Create a main.py to start your app:
+# examples/simple_demo.py
+from rpi_app_framework import RPIApp, PiHardwareAdapter
+import time
+
+class SimpleDemo(RPIApp):
+    """
+    Minimal demo that shows:
+      • Board model detection
+      • CPU temperature monitoring
+      • On-board LED blinking
+    Works on Pico 2 W and all full-size Raspberry Pi models.
+    """
+
+    def setup(self):
+        # Initialise the hardware adapter
+        self.hw = PiHardwareAdapter(log_func=self.log)
+
+        # Use the onboard LED (works on Pico and full RPi)
+        self.status_led = self.hw.led("LED" if "Pico" in self.hw.model else 13)
+
+        # Log startup info
+        self.log(f"Running on: {self.hw.model}")
+        self.log(f"Initial CPU temperature: {self.hw.cpu_temperature}°C")
+
+    def run(self):
+        while self.running:
+            # Blink the LED
+            self.status_led.value(1)
+            time.sleep(0.5)
+            self.status_led.value(0)
+
+            # Log temperature every 5 seconds
+            self.log(f"CPU temperature: {self.hw.cpu_temp}°C")
+            time.sleep(4.5)
+
+if __name__ == "__main__":
+    SimpleDemo(max_log_files=10).start()
+
+Compatibility
+
+Pico 2 W (MicroPython): Uses machine for pins/PWM.
+Full RPi (Python): Uses RPi.GPIO and gpiozero for pins/PWM.
+
+Features
+
+RPIApp: Base class for app lifecycle and logging.
+DeviceManager: Base for hardware managers with logging.
+LEDSimple: Controls LEDs (on/off/blink).
+WiFiManager: Manages WiFi connections (Pico only).
+MotorDriverTB6612FNG: Controls dual DC motors.
+MicrodotManager: Runs a lightweight web server.
+
+For example applications see projects at www.singerlinks.com

rpi_app_framework-0.1.2/README.md

@@ -0,0 +1,66 @@
+RPi App Framework
+Modular framework for all Raspberry Pi models (Pico 2 W with MicroPython/Thonny, full RPi 1-5 with Python).
+Installation
+For MicroPython/Pico (Thonny):
+
+Copy the rpi_app_framework folder to /lib on your Pico.
+
+For full Python/RPi:
+
+pip install rpi-app-framework
+
+Usage
+Create a main.py to start your app:
+# examples/simple_demo.py
+from rpi_app_framework import RPIApp, PiHardwareAdapter
+import time
+
+class SimpleDemo(RPIApp):
+    """
+    Minimal demo that shows:
+      • Board model detection
+      • CPU temperature monitoring
+      • On-board LED blinking
+    Works on Pico 2 W and all full-size Raspberry Pi models.
+    """
+
+    def setup(self):
+        # Initialise the hardware adapter
+        self.hw = PiHardwareAdapter(log_func=self.log)
+
+        # Use the onboard LED (works on Pico and full RPi)
+        self.status_led = self.hw.led("LED" if "Pico" in self.hw.model else 13)
+
+        # Log startup info
+        self.log(f"Running on: {self.hw.model}")
+        self.log(f"Initial CPU temperature: {self.hw.cpu_temperature}°C")
+
+    def run(self):
+        while self.running:
+            # Blink the LED
+            self.status_led.value(1)
+            time.sleep(0.5)
+            self.status_led.value(0)
+
+            # Log temperature every 5 seconds
+            self.log(f"CPU temperature: {self.hw.cpu_temp}°C")
+            time.sleep(4.5)
+
+if __name__ == "__main__":
+    SimpleDemo(max_log_files=10).start()
+
+Compatibility
+
+Pico 2 W (MicroPython): Uses machine for pins/PWM.
+Full RPi (Python): Uses RPi.GPIO and gpiozero for pins/PWM.
+
+Features
+
+RPIApp: Base class for app lifecycle and logging.
+DeviceManager: Base for hardware managers with logging.
+LEDSimple: Controls LEDs (on/off/blink).
+WiFiManager: Manages WiFi connections (Pico only).
+MotorDriverTB6612FNG: Controls dual DC motors.
+MicrodotManager: Runs a lightweight web server.
+
+For example applications see projects at www.singerlinks.com

rpi_app_framework-0.1.2/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rpi-app-framework"
+version = "0.1.2"
+description = "A Python framework for building applications on all Raspberry Pi versions, including Pico."
+readme = "README.md"
+requires-python = ">=3.7"
+license = "MIT"
+authors = [
+    {name = "John Singer", email = "john@singerlinks.com"}
+]
+keywords = ["raspberry-pi", "pico", "framework", "app-development", "iot"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: System :: Hardware"
+]
+dependencies = []
+
+[project.optional-dependencies]
+pi = [
+    "RPi.GPIO>=0.7.0"
+]
+test = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0"
+]
+dev = [
+    "black>=23.0",
+    "isort>=5.0",
+    "flake8>=6.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/jsinger0420/rpi-app-framework"
+Repository = "https://github.com/jsinger0420/rpi-app-framework.git"
+Documentation = "https://github.com/jsinger0420/rpi-app-framework/wiki"
+"Bug Tracker" = "https://github.com/jsinger0420/rpi-app-framework/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = {find = {where = ["src"]}}
+
+[tool.setuptools.package-data]
+"rpi_app_framework" = ["*.txt", "*.md"]

rpi_app_framework-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rpi_app_framework-0.1.2/setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup, find_packages
+import os
+
+setup(
+    name="rpi-app-framework",
+    version="0.1.0",
+    author="Your Name",
+    author_email="your.email@example.com",
+    description="Modular framework for all Raspberry Pi models with hardware managers (LED, WiFi, Motor, Web)",
+    long_description=open("README.md").read() if os.path.exists("README.md") else "A cross-compatible framework for RPi Pico and full RPi apps.",
+    long_description_content_type="text/markdown",
+    url="https://github.com/yourusername/rpi-app-framework",
+    packages=find_packages(),  # Auto-discovers rpi_app_framework/
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: POSIX :: Linux",
+        "Development Status :: 4 - Beta",
+        "Topic :: System :: Hardware",
+    ],
+    python_requires=">=3.6",
+    install_requires=[
+        "RPi.GPIO; sys_platform == 'linux'",  # For full RPi GPIO
+        "gpiozero; sys_platform == 'linux'",  # For PWM/LED on full RPi
+    ],
+    extras_require={
+        "web": ["microdot"],  # For MicrodotManager
+    },
+)

rpi_app_framework-0.1.2/src/rpi_app_framework/__init__.py

@@ -0,0 +1,10 @@
+from .rpi_app import RPIApp
+from .device_manager import DeviceManager
+from .led_simple import LEDSimple
+from .wifi_manager import WiFiManager
+from .motor_driver_tb6612 import MotorDriverTB6612FNG
+from .microdot_manager import MicrodotManager
+from .hardware import PiHardwareAdapter
+
+__version__ = "0.1.1"
+__all__ = ['RPIApp', 'DeviceManager', 'LEDSimple', 'WiFiManager', 'MotorDriverTB6612FNG', 'MicrodotManager','PiHardwareAdapter']

rpi_app_framework-0.1.2/src/rpi_app_framework/device_manager.py

@@ -0,0 +1,84 @@
+# Conditional imports for cross-platform compatibility
+try:
+    from machine import Pin, PWM
+    MICROPYTHON = True
+except ImportError:
+    import RPi.GPIO as GPIO
+    from gpiozero import LED, PWMOutputDevice as PWMLED
+    MICROPYTHON = False
+
+class DeviceManager:
+    """
+    Abstract base class for device managers.
+    Provides common logging functionality and device naming with validation.
+    Supports Pico (MicroPython) and full RPi (Python) via conditional imports.
+    """
+
+    def __init__(self, name=None, log_func=None):
+        """
+        Initialize the DeviceManager instance.
+
+        :param name: Optional custom name for the device instance (defaults to class name).
+                     Must be a non-empty string, max 50 characters, alphanumeric with spaces/underscores/dashes.
+        :param log_func: Optional function to log messages (e.g., app's log method).
+        :raises ValueError: If name is invalid.
+        """
+        self.logging_enabled = True  # Default to logging enabled
+        self.log_func = log_func
+        self._validate_name(name)
+        self._name = name or self.__class__.__name__  # Use provided name or class name
+
+    def _validate_name(self, name):
+        """
+        Validate the device name.
+
+        :param name: The name to validate.
+        :raises ValueError: If name is invalid (not a string, empty, too long, or contains invalid characters).
+        """
+        if name is None:
+            return  # Will default to class name, which is valid
+        if not isinstance(name, str):
+            raise ValueError("Device name must be a string")
+        if len(name.strip()) == 0:
+            raise ValueError("Device name cannot be empty")
+        if len(name) > 50:
+            raise ValueError("Device name must be 50 characters or fewer")
+        # Allow alphanumeric, spaces, underscores, dashes; no other special chars for log/file safety
+        import re
+        if not re.match(r'^[a-zA-Z0-9 _\-]+$', name):
+            raise ValueError("Device name can only contain alphanumeric characters, spaces, underscores, and dashes")
+
+    @property
+    def name(self):
+        """
+        Get the device name.
+
+        :return: The name of the device.
+        """
+        return self._name
+
+    def enable_logging(self):
+        """
+        Enable logging for the device.
+        """
+        self.logging_enabled = True
+
+    def disable_logging(self):
+        """
+        Disable logging for the device.
+        """
+        self.logging_enabled = False
+
+    def _log(self, message):
+        """
+        Internal method to log a message if logging is enabled.
+        Prefixes the message with the device name.
+
+        :param message: The message to log.
+        """
+        if self.logging_enabled:
+            prefixed_message = f"[{self.name}] {message}"
+            if self.log_func:
+                self.log_func(prefixed_message)
+            else:
+                print(prefixed_message)

rpi_app_framework-0.1.2/src/rpi_app_framework/hardware.py

@@ -0,0 +1,132 @@
+# rpi_app_framework/pi_hardware_adapter.py
+from device_manager import DeviceManager
+
+try:
+    from machine import Pin, PWM
+    MICROPYTHON = True
+except ImportError:
+    import RPi.GPIO as GPIO
+    from gpiozero import LED, PWMOutputDevice
+    GPIO.setmode(GPIO.BCM)
+    MICROPYTHON = False
+
+import subprocess
+import re
+
+
+class PiHardwareAdapter(DeviceManager):
+    """
+    Unified hardware adapter for all Raspberry Pi models.
+    Provides:
+      • Pin factory (digital out/in, PWM)
+      • Board model detection
+      • CPU temperature
+    Works on Pico 2 W (MicroPython) and full-size Raspberry Pi (Python).
+    """
+
+    def __init__(self, name="PiHardwareAdapter", log_func=None):
+        super().__init__(name=name, log_func=log_func)
+        self._model = self._detect_model()
+        self._log(f"Hardware: {self._model}")
+
+    def _detect_model(self) -> str:
+        if MICROPYTHON:
+            return "Raspberry Pi Pico 2 W"
+        try:
+            with open("/proc/device-tree/model", "r") as f:
+                model = f.read().strip("\x00")
+                return model or "Raspberry Pi (unknown)"
+        except Exception:
+            return "Raspberry Pi (detection failed)"
+
+    @property
+    def model(self) -> str:
+        """Read-only: detected board model."""
+        return self._model
+
+    @property
+    def cpu_temperature(self) -> float:
+        """Read-only: CPU/core temperature in °C."""
+        if MICROPYTHON:
+            # RP2040 built-in sensor
+            try:
+                sensor = machine.ADC(4)
+                reading = sensor.read_u16()
+                voltage = reading * 3.3 / 65535
+                temp = 27 - (voltage - 0.706) / 0.001721
+                return round(temp, 2)
+            except Exception as e:
+                raise RuntimeError(f"Pico temp sensor error: {e}")
+
+        # Full-size RPi
+        try:
+            out = subprocess.check_output(["vcgencmd", "measure_temp"], text=True)
+            m = re.search(r"temp=([\d.]+)", out)
+            if m:
+                return float(m.group(1))
+        except Exception:
+            pass
+        try:
+            with open("/sys/class/thermal/thermal_zone0/temp") as f:
+                return round(int(f.read().strip()) / 1000.0, 2)
+        except Exception:
+            raise RuntimeError("CPU temperature unavailable")
+
+    @property
+    def cpu_temp(self) -> float:
+        """Alias for cpu_temperature."""
+        return self.cpu_temperature
+
+    # ——— Pin Abstraction ———
+
+    def digital_out(self, pin, value=None):
+        """Return a digital output pin object (or set value directly)."""
+        if MICROPYTHON:
+            p = Pin(pin, Pin.OUT)
+            if value is not None:
+                p.value(value)
+            return p
+        else:
+            GPIO.setup(pin, GPIO.OUT)
+            if value is not None:
+                GPIO.output(pin, value)
+            return lambda v=None: GPIO.output(pin, v) if v is not None else None
+
+    def digital_in(self, pin, pull=None):
+        """Return a digital input pin (with optional pull-up/down)."""
+        if MICROPYTHON:
+            mode = Pin.IN
+            if pull == "up":
+                mode = Pin.IN | Pin.PULL_UP
+            elif pull == "down":
+                mode = Pin.IN | Pin.PULL_DOWN
+            return Pin(pin, mode)
+        else:
+            pull_mode = GPIO.PUD_UP if pull == "up" else GPIO.PUD_DOWN if pull == "down" else GPIO.PUD_OFF
+            GPIO.setup(pin, GPIO.IN, pull_up_down=pull_mode)
+            return lambda: GPIO.input(pin)
+
+    def pwm(self, pin, freq=1000, duty=0):
+        """Return a PWM output object."""
+        if MICROPYTHON:
+            p = PWM(Pin(pin))
+            p.freq(freq)
+            p.duty_u16(int(duty * 655.35))  # 0–100 → 0–65535
+            return p
+        else:
+            pwm_obj = PWMOutputDevice(pin, frequency=freq)
+            pwm_obj.value = duty / 100.0
+            return pwm_obj
+
+    def led(self, pin):
+        """Convenient factory for an LED (digital out)."""
+        if MICROPYTHON:
+            return self.digital_out(pin)
+        else:
+            return LED(pin)
+
+    def cleanup(self):
+        """Clean up GPIO resources (full RPi only)."""
+        if not MICROPYTHON:
+            GPIO.cleanup()
+            self._log("GPIO cleaned up")

rpi_app_framework-0.1.2/src/rpi_app_framework/led_simple.py

@@ -0,0 +1,83 @@
+# Conditional imports for cross-platform compatibility
+try:
+    from machine import Pin
+    MICROPYTHON = True
+except ImportError:
+    import RPi.GPIO as GPIO
+    from gpiozero import LED
+    MICROPYTHON = False
+
+from .device_manager import DeviceManager
+import time
+
+class LEDSimple(DeviceManager):
+    """
+    Simple LED manager without PWM support.
+    Inherits from DeviceManager for logging and naming.
+    Provides basic on/off and blink functionality.
+    Works on Pico (MicroPython) or full RPi (Python).
+    """
+
+    def __init__(self, pin="LED", name=None, log_func=None):
+        """
+        Initialize the LEDSimple instance.
+
+        :param pin: Pin to use for the LED (default: "LED").
+        :param name: Optional custom name for this LED instance.
+        :param log_func: Optional function to log messages (e.g., app's log method).
+        """
+        super().__init__(name=name, log_func=log_func)
+        if MICROPYTHON:
+            self.led = Pin(pin, Pin.OUT)
+        else:
+            self.led_pin = int(pin)
+            GPIO.setmode(GPIO.BCM)
+            GPIO.setup(self.led_pin, GPIO.OUT)
+            self.led = LED(self.led_pin)  # Use gpiozero for easy control
+        self.off()  # Ensure LED is off initially
+
+    def on(self):
+        """
+        Turn the LED on.
+        """
+        if MICROPYTHON:
+            self.led.value(1)
+        else:
+            self.led.on()
+        self._log("LED turned on")
+
+    def off(self):
+        """
+        Turn the LED off.
+        """
+        if MICROPYTHON:
+            self.led.value(0)
+        else:
+            self.led.off()
+        self._log("LED turned off")
+
+    def toggle(self):
+        """
+        Toggle the LED state (on to off or off to on).
+        """
+        if MICROPYTHON:
+            self.led.toggle()
+            state = "on" if self.led.value() else "off"
+        else:
+            self.led.toggle()
+            state = "on" if self.led.is_active else "off"
+        self._log(f"LED toggled to {state}")
+
+    def blink(self, duration=0.5, count=1):
+        """
+        Blink the LED a specified number of times.
+
+        :param duration: Duration of each blink in seconds (default: 0.5).
+        :param count: Number of blinks (default: 1).
+        """
+        for _ in range(count):
+            self.on()
+            time.sleep(duration)
+            self.off()
+            time.sleep(duration)
+        self._log(f"LED blinked {count} times with duration {duration}s")

rpi_app_framework-0.1.2/src/rpi_app_framework/microdot_manager.py

@@ -0,0 +1,81 @@
+# Conditional imports for cross-platform compatibility
+try:
+    from microdot_asyncio import Microdot
+    MICROPYTHON = True
+except ImportError:
+    from microdot import Microdot  # Full Python version
+    MICROPYTHON = False
+
+from .device_manager import DeviceManager
+import asyncio
+
+class MicrodotManager(DeviceManager):
+    """
+    Manager class for running a Microdot web server on Raspberry Pi (Pico 2 W or full RPi).
+    Inherits from DeviceManager for logging and naming.
+    Assumes WiFi is already connected (e.g., via WiFiManager).
+    Supports adding routes and running the server asynchronously.
+    """
+
+    def __init__(self, name="Web Server", log_func=None, port=80):
+        """
+        Initialize the MicrodotManager instance.
+
+        :param name: Optional custom name for this manager instance (default: "Web Server").
+        :param log_func: Optional function to log messages (e.g., app's log method).
+        :param port: Port to run the web server on (default: 80).
+        """
+        super().__init__(name=name, log_func=log_func)
+        self.app = Microdot()
+        self.port = port
+        self._log(f"Microdot web server initialized on port {port}")
+
+    def setup(self):
+        """
+        Setup method for MicrodotManager.
+        Can be overridden to add routes or configure the server.
+        """
+        self._log("MicrodotManager setup complete")
+
+    def add_route(self, path, handler, methods=['GET']):
+        """
+        Add a route to the web server.
+
+        :param path: URL path for the route (e.g., '/status').
+        :param handler: Function to handle the route (receives request object).
+        :param methods: List of HTTP methods (e.g., ['GET', 'POST']).
+        """
+        try:
+            self.app.route(path, methods=methods)(handler)
+            self._log(f"Added route: {path} ({methods})")
+        except Exception as e:
+            self._log(f"Error adding route {path}: {e}")
+            raise
+
+    async def run_server_async(self):
+        """
+        Run the Microdot server asynchronously.
+        Suitable for MicroPython's asyncio or full Python.
+        """
+        try:
+            if MICROPYTHON:
+                await self.app.start_server(port=self.port)
+            else:
+                self.app.run(port=self.port)  # Full Python runs synchronously
+            self._log(f"Web server running on port {self.port}")
+        except Exception as e:
+            self._log(f"Error running web server: {e}")
+            raise
+
+    def run(self):
+        """
+        Synchronous wrapper to run the server (for compatibility).
+        Starts the async server using asyncio.
+        """
+        try:
+            asyncio.run(self.run_server_async())
+        except KeyboardInterrupt:
+            self._log("Web server stopped by user")
+        except Exception as e:
+            self._log(f"Error in web server: {e}")
+            raise