plexus-python 0.1.0__py3-none-any.whl

plexus/sensors/spi_scan.py

@@ -0,0 +1,164 @@
+"""
+SPI bus scanning for sensor auto-detection.
+
+Scans available SPI buses for known sensors by reading WHO_AM_I registers.
+
+Usage:
+    from plexus.sensors.spi_scan import scan_spi, scan_spi_buses
+
+    # List available SPI buses
+    buses = scan_spi_buses()
+
+    # Scan for known sensors
+    sensors = scan_spi()
+    for s in sensors:
+        print(f"{s.name} on SPI bus {s.bus} CS {s.cs}")
+"""
+
+import glob
+import logging
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Tuple, Type
+
+from .base import BaseSensor
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SPISensorMatch:
+    """A sensor detected on an SPI bus."""
+    name: str
+    bus: int
+    cs: int
+    driver: Type[BaseSensor]
+    description: str
+
+
+@dataclass
+class SPISensorInfo:
+    """Registration info for an SPI-detectable sensor."""
+    driver: Type[BaseSensor]
+    who_am_i_reg: int
+    expected_id: int
+    spi_mode: int
+    spi_speed: int
+    description: str
+
+
+# Registry of known SPI sensors
+KNOWN_SPI_SENSORS: List[SPISensorInfo] = []
+
+
+def register_spi_sensor(info: SPISensorInfo):
+    """Register a sensor for SPI auto-detection."""
+    KNOWN_SPI_SENSORS.append(info)
+
+
+def _init_known_spi_sensors():
+    """Initialize the SPI sensor registry."""
+    if KNOWN_SPI_SENSORS:
+        return
+
+    try:
+        from .adxl345 import ADXL345
+        register_spi_sensor(SPISensorInfo(
+            driver=ADXL345,
+            who_am_i_reg=0x00,
+            expected_id=0xE5,
+            spi_mode=3,
+            spi_speed=1000000,
+            description="3-axis accelerometer",
+        ))
+    except ImportError:
+        pass
+
+
+def scan_spi_buses() -> List[Tuple[int, int]]:
+    """
+    Enumerate available SPI bus/CS combinations.
+
+    Scans /dev/spidev* for available SPI devices.
+
+    Returns:
+        List of (bus, cs) tuples
+    """
+    devices = sorted(glob.glob("/dev/spidev*"))
+    buses = []
+    for dev in devices:
+        match = re.search(r"spidev(\d+)\.(\d+)", dev)
+        if match:
+            bus = int(match.group(1))
+            cs = int(match.group(2))
+            buses.append((bus, cs))
+    return buses
+
+
+def _spi_read_register(bus: int, cs: int, reg: int, mode: int, speed: int) -> Optional[int]:
+    """Read a single register over SPI. Returns None on failure."""
+    try:
+        import spidev
+    except ImportError:
+        raise ImportError(
+            "spidev is required for SPI scanning. Install with: pip install spidev"
+        )
+
+    try:
+        spi = spidev.SpiDev()
+        spi.open(bus, cs)
+        spi.mode = mode
+        spi.max_speed_hz = speed
+        # SPI read: set bit 7 of register address
+        resp = spi.xfer2([reg | 0x80, 0x00])
+        spi.close()
+        return resp[1]
+    except PermissionError:
+        logger.warning(
+            "Permission denied opening SPI bus %d CS %d. "
+            "Try: sudo usermod -aG spi $USER && reboot",
+            bus, cs,
+        )
+        return None
+    except Exception as e:
+        logger.debug("SPI read failed on bus %d cs %d reg 0x%02X: %s", bus, cs, reg, e)
+        return None
+
+
+def scan_spi(buses: Optional[List[Tuple[int, int]]] = None) -> List[SPISensorMatch]:
+    """
+    Scan SPI buses for known sensors.
+
+    Args:
+        buses: List of (bus, cs) tuples to scan. None = auto-detect available buses.
+
+    Returns:
+        List of detected sensors
+    """
+    _init_known_spi_sensors()
+
+    if buses is None:
+        buses = scan_spi_buses()
+
+    if not buses:
+        return []
+
+    detected = []
+
+    for bus, cs in buses:
+        for info in KNOWN_SPI_SENSORS:
+            value = _spi_read_register(bus, cs, info.who_am_i_reg, info.spi_mode, info.spi_speed)
+            if value == info.expected_id:
+                detected.append(SPISensorMatch(
+                    name=info.driver.name,
+                    bus=bus,
+                    cs=cs,
+                    driver=info.driver,
+                    description=info.description,
+                ))
+                logger.info(
+                    "Found %s on SPI bus %d CS %d", info.driver.name, bus, cs
+                )
+                break  # One sensor per CS line
+
+    return detected

plexus/sensors/system.py

@@ -0,0 +1,261 @@
+"""
+System health sensor driver.
+
+Reports CPU, memory, disk, network, and process metrics.
+No external dependencies — uses only the Python standard library.
+Works on any Linux system; some metrics degrade gracefully on macOS.
+
+Usage:
+    from plexus.sensors import SystemSensor, SensorHub
+    from plexus import Plexus
+
+    hub = SensorHub()
+    hub.add(SystemSensor())
+    hub.run(Plexus())
+
+Or from the CLI:
+    plexus start --sensor system
+"""
+
+import os
+import time
+import shutil
+import logging
+import subprocess
+from typing import Dict, List, Optional
+
+from .base import BaseSensor, SensorReading
+
+logger = logging.getLogger(__name__)
+
+
+class SystemSensor(BaseSensor):
+    """
+    System health sensor for fleet monitoring.
+
+    Provides:
+    - cpu.temperature: CPU temperature in Celsius (Linux)
+    - cpu.usage_pct: CPU usage as a percentage (0-100)
+    - cpu.load: 1-minute load average
+    - memory.used_pct: Memory usage as a percentage (0-100)
+    - memory.available_mb: Available memory in MB
+    - disk.used_pct: Root disk usage as a percentage (0-100)
+    - disk.available_gb: Available disk space in GB
+    - net.rx_bytes: Network bytes received (cumulative)
+    - net.tx_bytes: Network bytes transmitted (cumulative)
+    - system.uptime: System uptime in seconds
+    - system.processes: Number of running processes
+    """
+
+    name = "System"
+    description = "System health (CPU, memory, disk, network, uptime)"
+    metrics = [
+        "cpu.temperature",
+        "cpu.usage_pct",
+        "cpu.load",
+        "memory.used_pct",
+        "memory.available_mb",
+        "disk.used_pct",
+        "disk.available_gb",
+        "net.rx_bytes",
+        "net.tx_bytes",
+        "system.uptime",
+        "system.processes",
+    ]
+
+    def __init__(
+        self,
+        sample_rate: float = 1.0,
+        prefix: str = "",
+        tags: Optional[dict] = None,
+    ):
+        super().__init__(sample_rate=sample_rate, prefix=prefix, tags=tags)
+        # Previous CPU times for usage calculation
+        self._prev_cpu_times: Optional[Dict[str, int]] = None
+        self._prev_cpu_time: float = 0.0
+
+    def _read_cpu_temperature(self) -> Optional[float]:
+        """Read CPU temperature from thermal zone. Returns Celsius or None."""
+        try:
+            with open("/sys/class/thermal/thermal_zone0/temp", "r") as f:
+                return int(f.read().strip()) / 1000.0
+        except (FileNotFoundError, ValueError, PermissionError):
+            pass
+
+        # Fallback: vcgencmd (common on ARM SBCs)
+        try:
+            result = subprocess.run(
+                ["vcgencmd", "measure_temp"],
+                capture_output=True,
+                text=True,
+                timeout=2,
+            )
+            if result.returncode == 0:
+                temp_str = result.stdout.strip().replace("temp=", "").replace("'C", "")
+                return float(temp_str)
+        except (FileNotFoundError, subprocess.TimeoutExpired, ValueError):
+            pass
+
+        return None
+
+    def _read_cpu_usage_pct(self) -> Optional[float]:
+        """Read CPU usage percentage from /proc/stat delta."""
+        try:
+            with open("/proc/stat", "r") as f:
+                line = f.readline()  # first line is aggregate
+            parts = line.split()
+            # user, nice, system, idle, iowait, irq, softirq, steal
+            times = {
+                "user": int(parts[1]),
+                "nice": int(parts[2]),
+                "system": int(parts[3]),
+                "idle": int(parts[4]),
+                "iowait": int(parts[5]) if len(parts) > 5 else 0,
+            }
+            now = time.monotonic()
+
+            if self._prev_cpu_times is not None:
+                prev = self._prev_cpu_times
+                dt = now - self._prev_cpu_time
+
+                if dt > 0:
+                    d_idle = (times["idle"] + times["iowait"]) - (prev["idle"] + prev["iowait"])
+                    d_total = sum(times.values()) - sum(prev.values())
+
+                    if d_total > 0:
+                        usage = (1.0 - d_idle / d_total) * 100.0
+                        self._prev_cpu_times = times
+                        self._prev_cpu_time = now
+                        return round(max(0.0, min(100.0, usage)), 1)
+
+            self._prev_cpu_times = times
+            self._prev_cpu_time = now
+            return None  # Need two samples to calculate delta
+        except (FileNotFoundError, ValueError, IndexError):
+            return None
+
+    def _read_cpu_load(self) -> Optional[float]:
+        """Read 1-minute load average."""
+        try:
+            return round(os.getloadavg()[0], 2)
+        except OSError:
+            return None
+
+    def _read_memory(self) -> Optional[tuple]:
+        """Read memory stats. Returns (used_pct, available_mb) or None."""
+        try:
+            with open("/proc/meminfo", "r") as f:
+                meminfo = {}
+                for line in f:
+                    parts = line.split(":")
+                    if len(parts) == 2:
+                        key = parts[0].strip()
+                        val = parts[1].strip().split()[0]
+                        meminfo[key] = int(val)
+
+                total = meminfo.get("MemTotal", 0)
+                available = meminfo.get("MemAvailable", 0)
+                if total > 0:
+                    used_pct = round((1.0 - available / total) * 100.0, 1)
+                    available_mb = round(available / 1024.0, 1)
+                    return used_pct, available_mb
+        except (FileNotFoundError, ValueError, KeyError):
+            pass
+        return None
+
+    def _read_disk(self) -> tuple:
+        """Read disk stats. Returns (used_pct, available_gb)."""
+        usage = shutil.disk_usage("/")
+        used_pct = round(usage.used / usage.total * 100.0, 1)
+        available_gb = round(usage.free / (1024 ** 3), 2)
+        return used_pct, available_gb
+
+    def _read_network_bytes(self) -> Optional[tuple]:
+        """Read total network rx/tx bytes from /proc/net/dev. Returns (rx, tx) or None."""
+        try:
+            rx_total = 0
+            tx_total = 0
+            with open("/proc/net/dev", "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if ":" not in line:
+                        continue
+                    iface, data = line.split(":", 1)
+                    iface = iface.strip()
+                    # Skip loopback
+                    if iface == "lo":
+                        continue
+                    fields = data.split()
+                    if len(fields) >= 9:
+                        rx_total += int(fields[0])
+                        tx_total += int(fields[8])
+            return rx_total, tx_total
+        except (FileNotFoundError, ValueError):
+            return None
+
+    def _read_uptime(self) -> Optional[float]:
+        """Read system uptime in seconds from /proc/uptime."""
+        try:
+            with open("/proc/uptime", "r") as f:
+                return round(float(f.read().split()[0]), 1)
+        except (FileNotFoundError, ValueError):
+            return None
+
+    def _read_process_count(self) -> Optional[int]:
+        """Count running processes via /proc."""
+        try:
+            count = 0
+            for entry in os.listdir("/proc"):
+                if entry.isdigit():
+                    count += 1
+            return count
+        except OSError:
+            return None
+
+    def read(self) -> List[SensorReading]:
+        readings = []
+
+        # CPU
+        cpu_temp = self._read_cpu_temperature()
+        if cpu_temp is not None:
+            readings.append(SensorReading("cpu.temperature", round(cpu_temp, 1)))
+
+        cpu_usage = self._read_cpu_usage_pct()
+        if cpu_usage is not None:
+            readings.append(SensorReading("cpu.usage_pct", cpu_usage))
+
+        cpu_load = self._read_cpu_load()
+        if cpu_load is not None:
+            readings.append(SensorReading("cpu.load", cpu_load))
+
+        # Memory
+        mem = self._read_memory()
+        if mem is not None:
+            readings.append(SensorReading("memory.used_pct", mem[0]))
+            readings.append(SensorReading("memory.available_mb", mem[1]))
+
+        # Disk
+        disk_used_pct, disk_available_gb = self._read_disk()
+        readings.append(SensorReading("disk.used_pct", disk_used_pct))
+        readings.append(SensorReading("disk.available_gb", disk_available_gb))
+
+        # Network
+        net = self._read_network_bytes()
+        if net is not None:
+            readings.append(SensorReading("net.rx_bytes", net[0]))
+            readings.append(SensorReading("net.tx_bytes", net[1]))
+
+        # System
+        uptime = self._read_uptime()
+        if uptime is not None:
+            readings.append(SensorReading("system.uptime", uptime))
+
+        procs = self._read_process_count()
+        if procs is not None:
+            readings.append(SensorReading("system.processes", procs))
+
+        return readings
+
+    def is_available(self) -> bool:
+        """Always available — disk and load work on any POSIX system."""
+        return True

plexus/sensors/vl53l0x.py

@@ -0,0 +1,109 @@
+"""
+VL53L0X Time-of-Flight distance sensor driver.
+
+The VL53L0X measures distance using a laser (940nm VCSEL).
+Range: 30mm to 2000mm with ±3% accuracy.
+Communicates via I2C at default address 0x29.
+
+Usage:
+    from plexus.sensors import VL53L0X
+
+    sensor = VL53L0X()
+    for reading in sensor.read():
+        print(f"{reading.metric}: {reading.value}")
+"""
+
+import time
+from typing import List, Optional
+from .base import BaseSensor, SensorReading
+
+VL53L0X_ADDR = 0x29
+
+# Key register addresses
+REG_IDENTIFICATION_MODEL_ID = 0xC0
+REG_SYSRANGE_START = 0x00
+REG_RESULT_RANGE_STATUS = 0x14
+REG_RESULT_RANGE_VAL = 0x1E  # 16-bit range value in mm
+
+
+class VL53L0X(BaseSensor):
+    """
+    VL53L0X Time-of-Flight distance sensor driver.
+
+    Provides:
+    - distance_mm: Distance in millimeters (30-2000mm range)
+
+    Note: This is a simplified driver using single-shot ranging.
+    For production use with custom timing budgets, consider the
+    official VL53L0X Python library.
+    """
+
+    name = "VL53L0X"
+    description = "Time-of-Flight distance sensor (30-2000mm)"
+    metrics = ["distance_mm"]
+    i2c_addresses = [VL53L0X_ADDR]
+
+    def __init__(
+        self,
+        address: int = VL53L0X_ADDR,
+        bus: int = 1,
+        sample_rate: float = 10.0,
+        prefix: str = "",
+        tags: Optional[dict] = None,
+    ):
+        super().__init__(sample_rate=sample_rate, prefix=prefix, tags=tags)
+        self.address = address
+        self.bus_num = bus
+        self._bus = None
+
+    def setup(self) -> None:
+        try:
+            from smbus2 import SMBus
+        except ImportError:
+            raise ImportError(
+                "smbus2 is required for VL53L0X. Install with: pip install smbus2"
+            )
+
+        self._bus = SMBus(self.bus_num)
+
+    def cleanup(self) -> None:
+        if self._bus:
+            self._bus.close()
+            self._bus = None
+
+    def read(self) -> List[SensorReading]:
+        if self._bus is None:
+            self.setup()
+
+        # Start single-shot ranging
+        self._bus.write_byte_data(self.address, REG_SYSRANGE_START, 0x01)
+
+        # Wait for measurement to complete (up to 50ms)
+        for _ in range(50):
+            time.sleep(0.001)
+            status = self._bus.read_byte_data(self.address, REG_RESULT_RANGE_STATUS)
+            if status & 0x01:  # Device ready
+                break
+
+        # Read range result (2 bytes, big-endian)
+        data = self._bus.read_i2c_block_data(self.address, REG_RESULT_RANGE_VAL, 2)
+        distance_mm = (data[0] << 8) | data[1]
+
+        # Filter out invalid readings (0 = no target, 8190+ = out of range)
+        if distance_mm == 0 or distance_mm >= 8190:
+            return []
+
+        return [
+            SensorReading("distance_mm", distance_mm),
+        ]
+
+    def is_available(self) -> bool:
+        try:
+            from smbus2 import SMBus
+
+            bus = SMBus(self.bus_num)
+            model_id = bus.read_byte_data(self.address, REG_IDENTIFICATION_MODEL_ID)
+            bus.close()
+            return model_id == 0xEE  # VL53L0X model ID
+        except Exception:
+            return False