rpi-app-framework 0.1.2__py3-none-any.whl

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/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/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/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/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

rpi_app_framework/motor_driver_tb6612.py

@@ -0,0 +1,288 @@
+# Conditional imports for cross-platform compatibility
+try:
+    from machine import Pin, PWM
+    MICROPYTHON = True
+except ImportError:
+    import RPi.GPIO as GPIO
+    from gpiozero import PWMOutputDevice as PWMLED
+    MICROPYTHON = False
+
+from .device_manager import DeviceManager
+import time
+
+class MotorDriverTB6612FNG(DeviceManager):
+    """
+    Device manager for TB6612FNG Dual DC Motor Driver.
+    Supports two DC motors with PWM speed control and direction.
+    Inherits from DeviceManager for logging and naming.
+    Allows individual names for each motor.
+    Provides unified methods using motor names.
+    Tracks current speed and direction for increase/decrease speed.
+    Includes start/stop methods for specific motors and enable/disable for the driver.
+    """
+
+    def __init__(self, pwma_pin, ain1_pin, ain2_pin, pwmb_pin, bin1_pin, bin2_pin, stby_pin, motor_a_name="Motor A", motor_b_name="Motor B", name=None, log_func=None, freq=1000):
+        """
+        Initialize the MotorDriverTB6612FNG instance.
+
+        :param pwma_pin: PWM pin for Motor A (int or str).
+        :param ain1_pin: Direction pin 1 for Motor A (int or str).
+        :param ain2_pin: Direction pin 2 for Motor A (int or str).
+        :param pwmb_pin: PWM pin for Motor B (int or str).
+        :param bin1_pin: Direction pin 1 for Motor B (int or str).
+        :param bin2_pin: Direction pin 2 for Motor B (int or str).
+        :param stby_pin: Standby pin (int or str).
+        :param motor_a_name: Name for Motor A (default: "Motor A").
+        :param motor_b_name: Name for Motor B (default: "Motor B").
+        :param name: Optional custom name for this driver instance.
+        :param log_func: Optional function to log messages.
+        :param freq: PWM frequency in Hz (default: 1000).
+        :raises ValueError: If pins are invalid for Pico 2 W or names are invalid.
+        """
+        super().__init__(name=name, log_func=log_func)
+        self._validate_names(motor_a_name, motor_b_name)
+        self.motor_a_name = motor_a_name
+        self.motor_b_name = motor_b_name
+        self._validate_pins([pwma_pin, ain1_pin, ain2_pin, pwmb_pin, bin1_pin, bin2_pin, stby_pin])
+        
+        if MICROPYTHON:
+            self.pwma = PWM(Pin(pwma_pin))
+            self.pwma.freq(freq)
+            self.ain1 = Pin(ain1_pin, Pin.OUT)
+            self.ain2 = Pin(ain2_pin, Pin.OUT)
+            self.pwmb = PWM(Pin(pwmb_pin))
+            self.pwmb.freq(freq)
+            self.bin1 = Pin(bin1_pin, Pin.OUT)
+            self.bin2 = Pin(bin2_pin, Pin.OUT)
+            self.stby = Pin(stby_pin, Pin.OUT)
+        else:
+            GPIO.setmode(GPIO.BCM)
+            self.pwma_pin = int(pwma_pin)
+            self.ain1_pin = int(ain1_pin)
+            self.ain2_pin = int(ain2_pin)
+            self.pwmb_pin = int(pwmb_pin)
+            self.bin1_pin = int(bin1_pin)
+            self.bin2_pin = int(bin2_pin)
+            self.stby_pin = int(stby_pin)
+            GPIO.setup([self.ain1_pin, self.ain2_pin, self.bin1_pin, self.bin2_pin, self.stby_pin], GPIO.OUT)
+            self.pwma = PWMLED(self.pwma_pin)
+            self.pwmb = PWMLED(self.pwmb_pin)
+            self.ain1 = GPIO.PWM(self.ain1_pin, freq)
+            self.ain2 = GPIO.PWM(self.ain2_pin, freq)
+            self.bin1 = GPIO.PWM(self.bin1_pin, freq)
+            self.bin2 = GPIO.PWM(self.bin2_pin, freq)
+            self.stby = GPIO.PWM(self.stby_pin, freq)
+
+        self.stby.value(0)  # Start disabled
+
+        # Track current speed and direction for each motor
+        self.motor_a_speed = 0
+        self.motor_a_direction = None  # 'forward', 'backward', or None
+        self.motor_b_speed = 0
+        self.motor_b_direction = None  # 'forward', 'backward', or None
+
+        self._log("TB6612FNG initialized (disabled)")
+
+    def _validate_names(self, motor_a_name, motor_b_name):
+        """
+        Validate motor names.
+
+        :param motor_a_name: Name for Motor A.
+        :param motor_b_name: Name for Motor B.
+        :raises ValueError: If names are invalid.
+        """
+        for name in [motor_a_name, motor_b_name]:
+            if not isinstance(name, str) or len(name.strip()) == 0 or len(name) > 50:
+                raise ValueError("Motor name must be a non-empty string up to 50 characters")
+
+    def _validate_pins(self, pins):
+        """
+        Validate pins for Raspberry Pi Pico 2 W or full RPi.
+
+        :param pins: List of pins to validate.
+        :raises ValueError: If any pin is invalid.
+        """
+        for pin in pins:
+            if MICROPYTHON and pin == "LED":
+                continue  # Onboard LED is valid for Pico
+            try:
+                pin_num = int(pin)
+                if MICROPYTHON and not 0 <= pin_num <= 29:
+                    raise ValueError("Invalid pin number for Pico")
+                elif not MICROPYTHON and not 1 <= pin_num <= 40:
+                    raise ValueError("Invalid pin number for full RPi")
+            except (ValueError, TypeError):
+                raise ValueError("Pin must be an integer (0-29 for Pico, 1-40 for RPi) or 'LED' for Pico")
+
+    def enable(self):
+        """
+        Enable the motor driver (set STBY high).
+        Allows both motors to operate.
+        """
+        if MICROPYTHON:
+            self.stby.value(1)
+        else:
+            GPIO.output(self.stby_pin, GPIO.HIGH)
+        self._log("Motor driver enabled")
+
+    def disable(self):
+        """
+        Disable the motor driver (set STBY low).
+        Stops both motors and prevents operation.
+        """
+        if MICROPYTHON:
+            self.pwma.duty_u16(0)
+            self.pwmb.duty_u16(0)
+            self.stby.value(0)
+        else:
+            self.pwma.value = 0
+            self.pwmb.value = 0
+            GPIO.output(self.stby_pin, GPIO.LOW)
+        self.motor_a_speed = 0
+        self.motor_a_direction = None
+        self.motor_b_speed = 0
+        self.motor_b_direction = None
+        self._log("Motor driver disabled")
+
+    def start(self, motor_name):
+        """
+        Start the specified motor (sets it to forward at default speed).
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :raises ValueError: If motor_name is invalid.
+        """
+        pwm, _, _, actual_name, speed_attr, dir_attr = self._get_motor_functions(motor_name)
+        self.enable()  # Ensure driver is enabled
+        self.forward(motor_name, speed=50)  # Default to 50% speed forward
+        self._log(f"{actual_name} started (forward at 50%)")
+
+    def stop(self, motor_name):
+        """
+        Stop the specified motor.
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :raises ValueError: If motor_name is invalid.
+        """
+        pwm, _, _, actual_name, speed_attr, dir_attr = self._get_motor_functions(motor_name)
+        if MICROPYTHON:
+            pwm.duty_u16(0)
+        else:
+            pwm.value = 0
+        setattr(self, speed_attr, 0)
+        setattr(self, dir_attr, None)
+        self._log(f"{actual_name} stopped")
+
+    def _get_motor_functions(self, motor_name):
+        """
+        Get motor functions based on name.
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :raises ValueError: If motor_name is invalid.
+        :return: Tuple (pwm, dir1, dir2, name, speed_attr, dir_attr).
+        """
+        if motor_name == self.motor_a_name:
+            return (self.pwma, self.ain1, self.ain2, self.motor_a_name, 'motor_a_speed', 'motor_a_direction')
+        elif motor_name == self.motor_b_name:
+            return (self.pwmb, self.bin1, self.bin2, self.motor_b_name, 'motor_b_speed', 'motor_b_direction')
+        else:
+            raise ValueError(f"Invalid motor name: {motor_name}. Must be '{self.motor_a_name}' or '{self.motor_b_name}'")
+
+    def forward(self, motor_name, speed=100):
+        """
+        Set the specified motor to forward direction with speed.
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :param speed: Speed from 0 to 100 (default: 100).
+        :raises ValueError: If motor_name is invalid or speed is out of range.
+        """
+        if not 0 <= speed <= 100:
+            raise ValueError("Speed must be between 0 and 100")
+        pwm, dir1, dir2, actual_name, speed_attr, dir_attr = self._get_motor_functions(motor_name)
+        if MICROPYTHON:
+            dir1.value(1)
+            dir2.value(0)
+            pwm.duty_u16(int((speed / 100.0) * 65535))
+        else:
+            GPIO.output(dir1, GPIO.HIGH)
+            GPIO.output(dir2, GPIO.LOW)
+            pwm.value = speed / 100.0
+        setattr(self, speed_attr, speed)
+        setattr(self, dir_attr, 'forward')
+        self._log(f"{actual_name} forward at {speed}%")
+
+    def backward(self, motor_name, speed=100):
+        """
+        Set the specified motor to backward direction with speed.
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :param speed: Speed from 0 to 100 (default: 100).
+        :raises ValueError: If motor_name is invalid or speed is out of range.
+        """
+        if not 0 <= speed <= 100:
+            raise ValueError("Speed must be between 0 and 100")
+        pwm, dir1, dir2, actual_name, speed_attr, dir_attr = self._get_motor_functions(motor_name)
+        if MICROPYTHON:
+            dir1.value(0)
+            dir2.value(1)
+            pwm.duty_u16(int((speed / 100.0) * 65535))
+        else:
+            GPIO.output(dir1, GPIO.LOW)
+            GPIO.output(dir2, GPIO.HIGH)
+            pwm.value = speed / 100.0
+        setattr(self, speed_attr, speed)
+        setattr(self, dir_attr, 'backward')
+        self._log(f"{actual_name} backward at {speed}%")
+
+    def stop_motor(self, motor_name):
+        """
+        Stop the specified motor (alias for stop method, for clarity).
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :raises ValueError: If motor_name is invalid.
+        """
+        self.stop(motor_name)
+
+    def increase_speed(self, motor_name, amount=10):
+        """
+        Increase the speed of the specified motor by the given amount.
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :param amount: Amount to increase speed by (default: 10).
+        :raises ValueError: If motor_name is invalid or amount is out of range.
+        """
+        if not 0 < amount <= 100:
+            raise ValueError("Amount must be positive and <= 100")
+        pwm, _, _, actual_name, speed_attr, dir_attr = self._get_motor_functions(motor_name)
+        current_speed = getattr(self, speed_attr)
+        new_speed = min(100, current_speed + amount)
+        if new_speed > 0 and getattr(self, dir_attr) is not None:
+            # Apply new speed in current direction
+            if getattr(self, dir_attr) == 'forward':
+                self.forward(motor_name, new_speed)
+            else:
+                self.backward(motor_name, new_speed)
+        else:
+            self._log(f"{actual_name} speed increase skipped (no direction or already stopped)")
+
+    def decrease_speed(self, motor_name, amount=10):
+        """
+        Decrease the speed of the specified motor by the given amount.
+
+        :param motor_name: The motor name ("Motor A" or "Motor B").
+        :param amount: Amount to decrease speed by (default: 10).
+        :raises ValueError: If motor_name is invalid or amount is out of range.
+        """
+        if not 0 < amount <= 100:
+            raise ValueError("Amount must be positive and <= 100")
+        pwm, _, _, actual_name, speed_attr, dir_attr = self._get_motor_functions(motor_name)
+        current_speed = getattr(self, speed_attr)
+        new_speed = max(0, current_speed - amount)
+        if new_speed > 0 and getattr(self, dir_attr) is not None:
+            # Apply new speed in current direction
+            if getattr(self, dir_attr) == 'forward':
+                self.forward(motor_name, new_speed)
+            else:
+                self.backward(motor_name, new_speed)
+        else:
+            self.stop(motor_name)
+            self._log(f"{actual_name} speed decreased to 0, stopped")

rpi_app_framework/rpi_app.py

@@ -0,0 +1,186 @@
+# Conditional imports for cross-platform compatibility
+try:
+    from machine import Pin
+    MICROPYTHON = True
+except ImportError:
+    import RPi.GPIO as GPIO
+    MICROPYTHON = False
+
+import time
+import os
+
+class RPIApp:
+    """
+    Generic base class for RPi applications (Pico 2 W or full RPi).
+    Provides common functionality like logging and application lifecycle management.
+    """
+
+    def __init__(self, app_name="RPIApp", max_log_files=10, enable_file_logging=True):
+        """
+        Initialize the RPIApp instance.
+
+        :param app_name: Name of the application (default: "RPIApp").
+        :param max_log_files: Maximum number of log files to keep (default: 10).
+        :param enable_file_logging: Whether to enable logging to file (default: True).
+                                    If False, logs only print to console.
+        """
+        self.running = False  # Reintroduce running flag
+        self._app_name = app_name  # Private application name
+        self._max_log_files = max_log_files  # Maximum number of log files to keep
+        self.enable_file_logging = enable_file_logging
+        if self.enable_file_logging:
+            # Ensure LOGFILES directory exists
+            try:
+                os.mkdir("LOGFILES")
+            except OSError:
+                pass  # Directory already exists
+            # Ensure app-specific log subdirectory exists
+            app_log_dir = f"LOGFILES/{app_name}"
+            try:
+                os.mkdir(app_log_dir)
+            except OSError:
+                pass  # Directory already exists
+            # Generate log file name with app_name and date/time in app-specific folder
+            t = time.localtime()
+            self.log_file = f"{app_log_dir}/{app_name}_{t[0]:04d}{t[1]:02d}{t[2]:02d}_{t[3]:02d}{t[4]:02d}{t[5]:02d}.log"
+            # Delete oldest log files to keep max_log_files or fewer
+            self._manage_log_files()
+        else:
+            self.log_file = None
+
+    def _manage_log_files(self):
+        """
+        Manage log files by deleting the oldest ones to keep only max_log_files.
+        This is an internal method and should not be called directly.
+        """
+        if not self.enable_file_logging:
+            return
+        try:
+            app_log_dir = f"LOGFILES/{self._app_name}"
+            # List all files in the app-specific log directory
+            files = os.listdir(app_log_dir)
+            # Filter log files starting with app_name
+            log_files = [f for f in files if f.startswith(self._app_name) and f.endswith('.log')]
+            # Sort files by name (timestamp ensures chronological order)
+            log_files.sort()
+            # Keep only the max_log_files most recent log files
+            while len(log_files) > self._max_log_files:
+                oldest_file = log_files.pop(0)  # Remove the oldest file
+                try:
+                    os.remove(f"{app_log_dir}/{oldest_file}")
+                    self.log(f"Deleted old log file: {oldest_file}")
+                except Exception as e:
+                    print(f"Failed to delete log file {app_log_dir}/{oldest_file}: {e}")
+        except Exception as e:
+            print(f"Error managing log files: {e}")
+
+    @property
+    def app_name(self):
+        """
+        Get the application name.
+
+        :return: The name of the application.
+        """
+        return self._app_name
+
+    def start(self):
+        """
+        Start the application.
+        Sets running flag to True, logs the start, calls setup, and then run.
+        """
+        self.running = True
+        self.log(f"{self.app_name} started")
+        self.setup()
+        self.run()
+
+    def setup(self):
+        """
+        Setup method to be overridden by child classes.
+        Called once after start. Logs any errors that occur with stack trace.
+        """
+        try:
+            pass  # To be overridden by child class
+        except Exception as e:
+            self._log_exception("Error in setup", e)
+            raise  # Re-raise to halt application start
+
+    def run(self):
+        """
+        Run method to be overridden by child classes.
+        Contains the main loop or logic of the application.
+        """
+        pass  # To be overridden by child class
+
+    def stop(self):
+        """
+        Stop the application.
+        Sets running flag to False and logs the stop.
+        """
+        self.running = False
+        self.log(f"{self.app_name} stopped")
+
+    def log(self, message):
+        """
+        Log a message to the log file with timestamp and app name.
+        Also prints the message to console.
+
+        :param message: The message to log.
+        """
+        # Get current time for timestamp
+        t = time.localtime()
+        timestamp = f"[{t[0]:04d}-{t[1]:02d}-{t[2]:02d} {t[3]:02d}:{t[4]:02d}:{t[5]:02d}]"
+        log_line = f"{timestamp} [{self.app_name}] {message}"
+        print(log_line)  # Print to console
+        if self.enable_file_logging:
+            log_line += "\n"
+            # Append log message to file
+            try:
+                with open(self.log_file, "a") as log_file:
+                    log_file.write(log_line)
+            except Exception as e:
+                print(f"Failed to write to log file: {e}")
+
+    def _log_exception(self, context, exc):
+        """
+        Log an exception with stack trace to the log file.
+        Also prints the exception to console.
+
+        :param context: A string describing the context of the error.
+        :param exc: The exception object.
+        """
+        t = time.localtime()
+        timestamp = f"[{t[0]:04d}-{t[1]:02d}-{t[2]:02d} {t[3]:02d}:{t[4]:02d}:{t[5]:02d}]"
+        error_msg = f"{timestamp} [{self.app_name}] {context}: {exc}"
+        print(error_msg)  # Print to console
+        if self.enable_file_logging:
+            try:
+                # Attempt to import traceback inside the method for MicroPython compatibility
+                import traceback
+                stack_trace = traceback.format_exception(type(exc), exc, exc.__traceback__)
+                full_error = ''.join(stack_trace)
+                print(full_error)  # Print stack trace to console
+                error_msg += "\n" + full_error + "\n"
+            except ImportError:
+                # Fallback if traceback not available
+                print("(Stack trace unavailable)")  # Print fallback to console
+                error_msg += "\n(Stack trace unavailable)\n"
+            except Exception as trace_e:
+                print(f"(Error formatting stack trace: {trace_e})")  # Print error to console
+                error_msg += f"\n(Error formatting stack trace: {trace_e})\n"
+            # Append log message to file
+            try:
+                with open(self.log_file, "a") as log_file:
+                    log_file.write(error_msg)
+            except Exception as log_e:
+                print(f"Failed to log exception: {log_e}")
+        else:
+            # If no file logging, still try to print stack trace
+            try:
+                import traceback
+                stack_trace = traceback.format_exception(type(exc), exc, exc.__traceback__)
+                full_error = ''.join(stack_trace)
+                print(full_error)  # Print stack trace to console
+            except ImportError:
+                print("(Stack trace unavailable)")
+            except Exception as trace_e:
+                print(f"(Error formatting stack trace: {trace_e})")

rpi_app_framework/wifi_manager.py

@@ -0,0 +1,180 @@
+from .device_manager import DeviceManager
+import network
+import time
+import json
+import os
+
+class WiFiManager(DeviceManager):
+    """
+    Manager class for WiFi connections on Raspberry Pi Pico 2 W.
+    Supports multiple networks defined by location names, read from wifi_config.json.
+    Allows dynamic or static IP configuration per location from the JSON.
+    Logs activity and raises exceptions on connection failure.
+    Provides scan-based connection to find matching SSID.
+    """
+
+    CONFIG_FILE = "wifi_config.json"
+
+    def __init__(self, name="WiFi Manager", log_func=None):
+        """
+        Initialize the WiFiManager instance.
+
+        :param name: Optional custom name for this manager instance (default: "WiFi Manager").
+        :param log_func: Optional function to log messages (e.g., app's log method).
+        """
+        super().__init__(name=name, log_func=log_func)
+        self.wlan = None
+        self.current_location = None
+        self.networks = self._load_config()
+        self._validate_config()
+
+    def _load_config(self):
+        """
+        Load WiFi configurations from JSON file.
+
+        :return: Dict of networks {location: {'ssid': str, 'password': str, 'static_ip': str (optional), ...}}.
+        :raises FileNotFoundError: If config file not found.
+        :raises json.JSONDecodeError: If file is invalid JSON.
+        """
+        try:
+            config_file = self.CONFIG_FILE
+            if not os.path.exists(config_file):
+                raise FileNotFoundError(f"WiFi config file not found: {config_file}")
+            with open(config_file, 'r') as f:
+                config = json.load(f)
+            self._log(f"Loaded WiFi config from {config_file}")
+            return config
+        except Exception as e:
+            self._log(f"Error loading WiFi config: {e}")
+            raise
+
+    def _validate_config(self):
+        """
+        Validate the loaded config has valid networks.
+
+        :raises ValueError: If config is empty or invalid.
+        """
+        if not self.networks or not isinstance(self.networks, dict):
+            raise ValueError("WiFi config must be a non-empty dict of networks")
+        for location, details in self.networks.items():
+            if not isinstance(details, dict) or 'ssid' not in details or 'password' not in details:
+                raise ValueError(f"Invalid config for location '{location}': missing ssid/password")
+            # Optional static IP fields are validated during connection
+        self._log(f"Validated {len(self.networks)} networks")
+
+    def connect(self, location):
+        """
+        Connect to the WiFi network at the specified location (direct method).
+
+        :param location: The location name from config (e.g., 'home').
+        :raises ValueError: If location not in config.
+        :raises Exception: If connection fails.
+        """
+        if location not in self.networks:
+            raise ValueError(f"Location '{location}' not in config")
+        self._connect_to_location(location)
+
+    def connect_scan(self, target_ssid):
+        """
+        Scan for WiFi networks, find one matching the target SSID,
+        identify the location from config, and connect using that config (scan method).
+
+        :param target_ssid: The SSID to search for in scan results.
+        :raises ValueError: If no matching SSID found in scan or config.
+        :raises Exception: If connection fails.
+        """
+        self._log(f"Scanning for SSID: {target_ssid}")
+        try:
+            # Scan for available networks
+            temp_wlan = network.WLAN(network.STA_IF)
+            temp_wlan.active(True)
+            scan_results = temp_wlan.scan()
+            available_ssids = [net[0].decode('utf-8') for net in scan_results]
+
+            if target_ssid not in available_ssids:
+                raise ValueError(f"Target SSID '{target_ssid}' not found in scan results")
+
+            # Find location in config with matching SSID
+            matching_location = None
+            for location, details in self.networks.items():
+                if details['ssid'] == target_ssid:
+                    matching_location = location
+                    break
+
+            if not matching_location:
+                raise ValueError(f"Target SSID '{target_ssid}' not found in config")
+
+            self._log(f"Found matching location: {matching_location}")
+            self._connect_to_location(matching_location)
+        except Exception as e:
+            self._log(f"Scan connection failed for '{target_ssid}': {e}")
+            raise
+
+    def _connect_to_location(self, location):
+        """
+        Internal method to connect using location config.
+
+        :param location: The location name from config.
+        :raises Exception: If connection fails.
+        """
+        self.current_location = location
+        details = self.networks[location]
+        ssid = details['ssid']
+        password = details['password']
+        self._log(f"Connecting to {location} ({ssid})...")
+
+        try:
+            self.wlan = network.WLAN(network.STA_IF)
+            if self.wlan is None:
+                raise Exception("Failed to create WLAN object")
+            self.wlan.active(True)
+            self.wlan.connect(ssid, password)
+
+            max_retries = 20
+            for retry in range(max_retries):
+                if self.wlan.isconnected():
+                    break
+                self._log(f"Connection attempt {retry + 1}/{max_retries}...")
+                time.sleep(1)
+            else:
+                raise Exception(f"Failed to connect to {ssid} after {max_retries} retries")
+
+            # Set static IP if provided in config for this location
+            static_ip = details.get('static_ip')
+            if static_ip:
+                netmask = details.get('netmask', '255.255.255.0')
+                gateway = details.get('gateway')
+                dns = details.get('dns', '8.8.8.8')
+                if gateway:
+                    self.wlan.ifconfig((static_ip, netmask, gateway, dns))
+                    self._log(f"Static IP set for {location}: {static_ip}")
+                else:
+                    self._log(f"Warning: Static IP '{static_ip}' specified for {location} but no gateway; using DHCP")
+            else:
+                self._log("Using DHCP for dynamic IP")
+
+            ip_addr = self.wlan.ifconfig()[0]
+            self._log(f"Connected to {location}! IP: {ip_addr}")
+        except Exception as e:
+            self._log(f"Connection failed for {location}: {e}")
+            raise
+
+    @property
+    def ip_address(self):
+        """
+        Get the current IP address.
+
+        :return: IP address string or None if not connected.
+        """
+        if self.wlan and self.wlan.isconnected():
+            return self.wlan.ifconfig()[0]
+        return None
+
+    def disconnect(self):
+        """
+        Disconnect from current WiFi network.
+        """
+        if self.wlan:
+            self.wlan.active(False)
+            self._log(f"Disconnected from {self.current_location}")
+            self.current_location = None

rpi_app_framework-0.1.2.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+rpi_app_framework/__init__.py,sha256=Z_o15zcbhnaMdkriPiE_JJdKHMGvEZk6aMjgQczoZZc,442
+rpi_app_framework/device_manager.py,sha256=iyMJWQhTOXUaUrIhLoYEV-o-rkMgBfvvLTElNy4f1iM,3036
+rpi_app_framework/hardware.py,sha256=23s0SgGZTuopNfoSbibG07w9PoBLXg4C7CWmzpN-ZAM,4438
+rpi_app_framework/led_simple.py,sha256=7AHO3QrOTu7T2yRKjNSxpuhXBhqugFlgoG5x1X0VOgc,2459
+rpi_app_framework/microdot_manager.py,sha256=PEjB_TS1yCI4sxakhgxghb18adKnujnunFZJIm9ojF8,2900
+rpi_app_framework/motor_driver_tb6612.py,sha256=c2yhHqCawb7cNd_99fqWVWGIXQjTw3cACGsyLpVb3H4,12070
+rpi_app_framework/rpi_app.py,sha256=LR0Xp0pMnub2ioSZB0SImRjz9gtlJZ14wfrBu0tg4fY,7629
+rpi_app_framework/wifi_manager.py,sha256=06XYB90KtG_xh6meOMbUOqgyxoi1gtr5gV8yEOQsJ54,7074
+rpi_app_framework-0.1.2.dist-info/licenses/LICENSE,sha256=iiV86G80RSWaWnXbHY3UfW1tmSHObi-BY4UOB882FkA,1067
+rpi_app_framework-0.1.2.dist-info/METADATA,sha256=qlae74VWY7QRfzvUMjzrbA-LNSebTQkdV_Qo8SWdULk,3783
+rpi_app_framework-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rpi_app_framework-0.1.2.dist-info/top_level.txt,sha256=OhCegglLhoeGuSaAVVE2kNYZjAkFVaCr9XMWNunrcYQ,18
+rpi_app_framework-0.1.2.dist-info/RECORD,,

rpi_app_framework-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rpi_app_framework-0.1.2.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+rpi_app_framework