plexus-python 0.1.0__py3-none-any.whl

plexus/sensors/auto.py

@@ -0,0 +1,290 @@
+"""
+Auto-detection of connected sensors.
+
+Scans I2C buses to find known sensors and automatically creates driver instances.
+
+Usage:
+    from plexus.sensors import scan_sensors, auto_sensors
+
+    # Scan and list available sensors
+    sensors = scan_sensors()
+    for s in sensors:
+        print(f"{s.name} at 0x{s.address:02X}")
+
+    # Auto-create sensor instances
+    hub = auto_sensors()
+    hub.run(Plexus())
+"""
+
+import logging
+from typing import List, Dict, Type, Optional, Tuple
+from dataclasses import dataclass
+
+from .base import BaseSensor, SensorHub
+
+try:
+    from .spi_scan import scan_spi
+    _HAS_SPI = True
+except ImportError:
+    _HAS_SPI = False
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DetectedSensor:
+    """Information about a detected sensor."""
+    name: str
+    address: int
+    bus: int
+    driver: Type[BaseSensor]
+    description: str
+
+
+# Registry of known sensors and their I2C addresses
+KNOWN_SENSORS: List[Tuple[Type[BaseSensor], int, str]] = []
+
+
+def register_sensor(driver: Type[BaseSensor], address: int, chip_id_check=None):
+    """Register a sensor for auto-detection."""
+    KNOWN_SENSORS.append((driver, address, chip_id_check))
+
+
+def _init_known_sensors():
+    """Initialize the registry with known sensors."""
+    global KNOWN_SENSORS
+
+    if KNOWN_SENSORS:
+        return  # Already initialized
+
+    # Import drivers
+    from .mpu6050 import MPU6050, MPU9250
+    from .bme280 import BME280
+    from .ina219 import INA219
+    from .sht3x import SHT3x
+    from .bh1750 import BH1750
+    from .vl53l0x import VL53L0X
+    from .ads1115 import ADS1115
+    from .magnetometer import QMC5883L, HMC5883L
+    from .adxl345 import ADXL345
+
+    # Register known sensors: (driver_class, i2c_address, chip_id_check)
+    KNOWN_SENSORS = [
+        # IMU sensors
+        (MPU6050, 0x68, None),
+        (MPU6050, 0x69, None),
+        (MPU9250, 0x68, None),  # Same address as MPU6050
+        # Environmental sensors
+        (BME280, 0x76, None),
+        (BME280, 0x77, None),
+        # Current/power monitoring
+        (INA219, 0x40, None),
+        (INA219, 0x41, None),
+        (INA219, 0x44, None),
+        (INA219, 0x45, None),
+        # Precision temperature/humidity
+        (SHT3x, 0x44, None),
+        (SHT3x, 0x45, None),
+        # Ambient light
+        (BH1750, 0x23, None),
+        (BH1750, 0x5C, None),
+        # Time-of-flight distance
+        (VL53L0X, 0x29, None),
+        # ADC
+        (ADS1115, 0x48, None),
+        (ADS1115, 0x49, None),
+        (ADS1115, 0x4A, None),
+        (ADS1115, 0x4B, None),
+        # Magnetometers
+        (QMC5883L, 0x0D, None),
+        (HMC5883L, 0x1E, None),
+        # Accelerometer (I2C mode)
+        (ADXL345, 0x53, None),
+        (ADXL345, 0x1D, None),
+    ]
+
+
+def _discover_i2c_buses() -> List[int]:
+    """Find all available I2C bus numbers on the system."""
+    import glob as _glob
+    buses = []
+    for path in sorted(_glob.glob("/dev/i2c-*")):
+        try:
+            buses.append(int(path.split("-")[-1]))
+        except ValueError:
+            pass
+    return buses
+
+
+def scan_i2c(bus: int = 1) -> List[int]:
+    """
+    Scan I2C bus for connected devices.
+
+    Args:
+        bus: I2C bus number (usually 1 on Raspberry Pi)
+
+    Returns:
+        List of detected I2C addresses
+    """
+    try:
+        from smbus2 import SMBus
+    except ImportError:
+        raise ImportError(
+            "smbus2 is required for I2C scanning. Install with: pip install smbus2"
+        )
+
+    addresses = []
+    try:
+        i2c = SMBus(bus)
+    except PermissionError:
+        raise  # Let CLI handle with user-friendly message
+    except OSError:
+        raise  # Let CLI handle with user-friendly message
+
+    for addr in range(0x03, 0x78):  # Valid I2C address range
+        try:
+            i2c.write_quick(addr)
+            addresses.append(addr)
+        except OSError:
+            pass  # No device at this address
+
+    i2c.close()
+    return addresses
+
+
+def scan_sensors(bus: Optional[int] = None) -> List[DetectedSensor]:
+    """
+    Scan for known sensors on I2C buses.
+
+    Args:
+        bus: I2C bus number, or None to scan all available buses.
+
+    Returns:
+        List of detected sensors with their drivers
+    """
+    _init_known_sensors()
+
+    buses = [bus] if bus is not None else _discover_i2c_buses()
+
+    detected = []
+
+    for scan_bus in buses:
+        try:
+            addresses = scan_i2c(scan_bus)
+        except OSError:
+            logger.debug("Could not open I2C bus %d, skipping", scan_bus)
+            continue
+
+        if not addresses:
+            continue
+
+        logger.debug("I2C bus %d: found addresses %s", scan_bus,
+                      [f"0x{a:02X}" for a in addresses])
+
+        for address in addresses:
+            for driver, known_addr, _ in KNOWN_SENSORS:
+                if address == known_addr:
+                    already_found = any(
+                        d.address == address and d.bus == scan_bus and d.driver == driver
+                        for d in detected
+                    )
+                    if not already_found:
+                        try:
+                            sensor = driver(address=address, bus=scan_bus)
+                            if sensor.is_available():
+                                detected.append(DetectedSensor(
+                                    name=driver.name,
+                                    address=address,
+                                    bus=scan_bus,
+                                    driver=driver,
+                                    description=driver.description,
+                                ))
+                                break
+                        except Exception as e:
+                            logger.debug(f"Sensor probe failed at 0x{address:02X} on bus {scan_bus}: {e}")
+
+    # Also scan SPI buses if spidev is available
+    if _HAS_SPI:
+        try:
+            spi_matches = scan_spi()
+            for match in spi_matches:
+                detected.append(DetectedSensor(
+                    name=match.name,
+                    address=0,  # SPI doesn't use addresses
+                    bus=match.bus,
+                    driver=match.driver,
+                    description=match.description,
+                ))
+        except Exception as e:
+            logger.debug("SPI scan failed: %s", e)
+
+    return detected
+
+
+def auto_sensors(
+    bus: Optional[int] = None,
+    sample_rate: Optional[float] = None,
+    prefix: str = "",
+    detected: Optional[List[DetectedSensor]] = None,
+) -> SensorHub:
+    """
+    Auto-detect sensors and create a SensorHub.
+
+    Args:
+        bus: I2C bus number, or None to scan all available buses.
+        sample_rate: Override sample rate for all sensors (None = use defaults)
+        prefix: Prefix for all metric names
+        detected: Pre-scanned sensors to use (skips re-scanning if provided)
+
+    Returns:
+        SensorHub with all detected sensors added
+    """
+    hub = SensorHub()
+
+    if detected is None:
+        detected = scan_sensors(bus)
+
+    for info in detected:
+        if info.address == 0:
+            # SPI sensor
+            kwargs = {"bus_type": "spi", "spi_bus": info.bus}
+        else:
+            kwargs = {"address": info.address, "bus": info.bus}
+
+        if sample_rate is not None:
+            kwargs["sample_rate"] = sample_rate
+
+        if prefix:
+            kwargs["prefix"] = prefix
+
+        sensor = info.driver(**kwargs)
+        hub.add(sensor)
+
+    return hub
+
+
+def get_sensor_info() -> Dict[str, dict]:
+    """
+    Get information about all supported sensors.
+
+    Returns:
+        Dict mapping sensor names to their info
+    """
+    _init_known_sensors()
+
+    info = {}
+    seen_drivers = set()
+
+    for driver, addr, _ in KNOWN_SENSORS:
+        if driver not in seen_drivers:
+            info[driver.name] = {
+                "name": driver.name,
+                "description": driver.description,
+                "metrics": driver.metrics,
+                "i2c_addresses": [
+                    f"0x{a:02X}" for d, a, _ in KNOWN_SENSORS if d == driver
+                ],
+            }
+            seen_drivers.add(driver)
+
+    return info

plexus/sensors/base.py

@@ -0,0 +1,412 @@
+"""
+Base sensor class and utilities for Plexus sensor drivers.
+
+All sensor drivers inherit from BaseSensor and implement the read() method.
+"""
+
+import logging
+import sys
+import time
+from abc import ABC, abstractmethod
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SensorReading:
+    """A single sensor reading with metric name and value."""
+    metric: str
+    value: Any
+    timestamp: float = field(default_factory=time.time)
+    tags: Dict[str, str] = field(default_factory=dict)
+
+
+class BaseSensor(ABC):
+    """
+    Base class for all sensor drivers.
+
+    Subclasses must implement:
+    - read() -> List[SensorReading]: Read current sensor values
+    - name: Human-readable sensor name
+    - metrics: List of metric names this sensor provides
+
+    Optional overrides:
+    - setup(): Initialize the sensor (called once)
+    - cleanup(): Clean up resources (called on stop)
+    - is_available(): Check if sensor is connected
+    """
+
+    # Sensor metadata (override in subclass)
+    name: str = "Unknown Sensor"
+    description: str = ""
+    metrics: List[str] = []
+
+    # I2C address(es) for auto-detection
+    i2c_addresses: List[int] = []
+
+    # SPI bus/chip-select pairs for auto-detection
+    spi_devices: List[tuple] = []
+
+    # Per-sensor read timeout (seconds). None = use SensorHub default.
+    read_timeout: Optional[float] = None
+
+    def __init__(
+        self,
+        sample_rate: float = 10.0,
+        prefix: str = "",
+        tags: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize the sensor driver.
+
+        Args:
+            sample_rate: Readings per second (Hz). Default 10 Hz.
+            prefix: Prefix for metric names (e.g., "robot1." -> "robot1.accel_x")
+            tags: Tags to add to all readings from this sensor
+        """
+        self.sample_rate = sample_rate
+        self.prefix = prefix
+        self.tags = tags or {}
+        self._running = False
+        self._error: Optional[str] = None
+        self._consecutive_failures = 0
+        self._disabled = False
+        self._original_sample_rate = sample_rate
+
+    def validate_reading(self, reading: "SensorReading") -> bool:
+        """
+        Validate a sensor reading. Override in subclasses for domain checks.
+
+        Returns:
+            True if the reading is valid
+        """
+        return True
+
+    @abstractmethod
+    def read(self) -> List[SensorReading]:
+        """
+        Read current sensor values.
+
+        Returns:
+            List of SensorReading objects with current values
+        """
+        pass
+
+    def setup(self) -> None:
+        """
+        Initialize the sensor hardware.
+        Called once before reading starts.
+        Override in subclass if needed.
+        """
+        pass
+
+    def cleanup(self) -> None:
+        """
+        Clean up sensor resources.
+        Called when sensor is stopped.
+        Override in subclass if needed.
+        """
+        pass
+
+    def is_available(self) -> bool:
+        """
+        Check if the sensor is connected and responding.
+
+        Returns:
+            True if sensor is available
+        """
+        try:
+            self.read()
+            return True
+        except Exception:
+            return False
+
+    def get_prefixed_metric(self, metric: str) -> str:
+        """Get metric name with prefix applied."""
+        if self.prefix:
+            return f"{self.prefix}{metric}"
+        return metric
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get sensor information for display."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "metrics": self.metrics,
+            "sample_rate": self.sample_rate,
+            "prefix": self.prefix,
+            "available": self.is_available(),
+        }
+
+
+class SensorHub:
+    """
+    Manages multiple sensors and streams their data to Plexus.
+
+    Usage:
+        from plexus import Plexus
+        from plexus.sensors import SensorHub, MPU6050, BME280
+
+        hub = SensorHub()
+        hub.add(MPU6050())
+        hub.add(BME280())
+        hub.run(Plexus())  # Streams forever
+    """
+
+    def __init__(
+        self,
+        default_timeout: float = 5.0,
+        max_workers: Optional[int] = None,
+    ):
+        """
+        Args:
+            default_timeout: Default per-sensor read timeout in seconds.
+            max_workers: Max threads for concurrent reads. None = number of sensors.
+        """
+        self.sensors: List[BaseSensor] = []
+        self._running = False
+        self.default_timeout = default_timeout
+        self.max_workers = max_workers
+        self.error_report_fn: Optional[Any] = None  # async fn(source, error, severity)
+
+    def add(self, sensor: BaseSensor) -> "SensorHub":
+        """Add a sensor to the hub."""
+        self.sensors.append(sensor)
+        return self
+
+    def remove(self, sensor: BaseSensor) -> "SensorHub":
+        """Remove a sensor from the hub."""
+        self.sensors.remove(sensor)
+        return self
+
+    def setup(self) -> None:
+        """Initialize all sensors."""
+        for sensor in self.sensors:
+            try:
+                sensor.setup()
+            except Exception as e:
+                logger.warning(f"Failed to setup {sensor.name}: {e}")
+                sensor._error = str(e)
+
+    def cleanup(self) -> None:
+        """Clean up all sensors."""
+        for sensor in self.sensors:
+            try:
+                sensor.cleanup()
+            except Exception:
+                pass
+
+    def _get_timeout(self, sensor: BaseSensor) -> float:
+        """Get the effective timeout for a sensor."""
+        return sensor.read_timeout if sensor.read_timeout is not None else self.default_timeout
+
+    def _handle_sensor_failure(self, sensor: BaseSensor) -> None:
+        """Track consecutive failures and degrade gracefully."""
+        sensor._consecutive_failures += 1
+        if sensor._consecutive_failures >= 5 and not sensor._disabled:
+            new_rate = sensor.sample_rate / 2.0
+            if new_rate < 0.1:
+                sensor._disabled = True
+                logger.warning(
+                    "%s disabled after %d consecutive failures",
+                    sensor.name, sensor._consecutive_failures,
+                )
+                self._report_sensor_error(
+                    sensor,
+                    f"Disabled after {sensor._consecutive_failures} consecutive failures",
+                    "error",
+                )
+            else:
+                sensor.sample_rate = new_rate
+                logger.warning(
+                    "%s: %d consecutive failures, reducing poll rate to %.2f Hz",
+                    sensor.name, sensor._consecutive_failures, new_rate,
+                )
+
+    def _report_sensor_error(self, sensor: BaseSensor, error: str, severity: str) -> None:
+        """Report sensor error to dashboard if error_report_fn is set."""
+        if self.error_report_fn:
+            import asyncio
+            try:
+                coro = self.error_report_fn(f"sensor.{sensor.name}", error, severity)
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    asyncio.ensure_future(coro)
+                else:
+                    loop.run_until_complete(coro)
+            except Exception:
+                pass
+
+    def _handle_sensor_success(self, sensor: BaseSensor) -> None:
+        """Reset failure tracking on successful read."""
+        if sensor._consecutive_failures > 0:
+            sensor._consecutive_failures = 0
+            if sensor.sample_rate != sensor._original_sample_rate:
+                sensor.sample_rate = sensor._original_sample_rate
+                logger.info(
+                    "%s recovered, restoring poll rate to %.2f Hz",
+                    sensor.name, sensor._original_sample_rate,
+                )
+
+    def read_all(self) -> List[SensorReading]:
+        """Read from all sensors concurrently with per-sensor timeouts."""
+        active = [s for s in self.sensors if not s._disabled]
+        if not active:
+            return []
+
+        readings = []
+        workers = self.max_workers or len(active)
+        pool = ThreadPoolExecutor(max_workers=workers)
+
+        try:
+            futures = {pool.submit(s.read): s for s in active}
+            for future in futures:
+                sensor = futures[future]
+                timeout = self._get_timeout(sensor)
+                try:
+                    sensor_readings = future.result(timeout=timeout)
+                    validated = [r for r in sensor_readings if sensor.validate_reading(r)]
+                    readings.extend(validated)
+                    self._handle_sensor_success(sensor)
+                except FuturesTimeoutError:
+                    logger.warning("Timeout reading %s (%.1fs)", sensor.name, timeout)
+                    sensor._error = f"timeout ({timeout}s)"
+                    future.cancel()
+                    self._handle_sensor_failure(sensor)
+                except Exception as e:
+                    logger.debug(f"Read error from {sensor.name}: {e}")
+                    sensor._error = str(e)
+                    self._handle_sensor_failure(sensor)
+        finally:
+            if sys.version_info >= (3, 9):
+                pool.shutdown(wait=False, cancel_futures=True)
+            else:
+                pool.shutdown(wait=False)
+
+        return readings
+
+    def run(
+        self,
+        client,  # Plexus client
+        run_id: Optional[str] = None,
+    ) -> None:
+        """
+        Run the sensor hub, streaming data to Plexus.
+
+        Args:
+            client: Plexus client instance
+            run_id: Optional run ID for grouping data
+        """
+        self.setup()
+        self._running = True
+
+        # Find the fastest sensor to determine loop timing
+        max_rate = max(s.sample_rate for s in self.sensors) if self.sensors else 10.0
+        min_interval = 1.0 / max_rate
+
+        # Track last read time per sensor
+        last_read = {id(s): 0.0 for s in self.sensors}
+
+        try:
+            context = client.run(run_id) if run_id else _nullcontext()
+
+            with context:
+                while self._running:
+                    loop_start = time.time()
+                    now = loop_start
+
+                    # Collect sensors that are due for a read
+                    due_sensors = []
+                    for sensor in self.sensors:
+                        if sensor._disabled:
+                            continue
+                        sensor_id = id(sensor)
+                        interval = 1.0 / sensor.sample_rate
+                        if now - last_read[sensor_id] >= interval:
+                            due_sensors.append(sensor)
+
+                    if due_sensors:
+                        # Read all due sensors concurrently
+                        workers = self.max_workers or len(due_sensors)
+                        pool = ThreadPoolExecutor(max_workers=workers)
+                        try:
+                            futures = {pool.submit(s.read): s for s in due_sensors}
+                            for future in futures:
+                                sensor = futures[future]
+                                timeout = self._get_timeout(sensor)
+                                try:
+                                    readings = future.result(timeout=timeout)
+                                    validated = [r for r in readings if sensor.validate_reading(r)]
+                                    self._handle_sensor_success(sensor)
+
+                                    batch_points = []
+                                    batch_timestamp = None
+                                    batch_tags = None
+
+                                    for reading in validated:
+                                        metric = sensor.get_prefixed_metric(reading.metric)
+                                        tags = {**sensor.tags, **reading.tags}
+                                        batch_points.append((metric, reading.value))
+
+                                        if batch_timestamp is None:
+                                            batch_timestamp = reading.timestamp
+                                            batch_tags = tags if tags else None
+
+                                    if batch_points:
+                                        client.send_batch(
+                                            batch_points,
+                                            timestamp=batch_timestamp,
+                                            tags=batch_tags,
+                                        )
+
+                                    last_read[id(sensor)] = now
+
+                                except FuturesTimeoutError:
+                                    logger.warning("Timeout reading %s (%.1fs)", sensor.name, timeout)
+                                    sensor._error = f"timeout ({timeout}s)"
+                                    future.cancel()
+                                    self._handle_sensor_failure(sensor)
+                                    last_read[id(sensor)] = now
+                                except Exception as e:
+                                    sensor._error = str(e)
+                                    self._handle_sensor_failure(sensor)
+                                    last_read[id(sensor)] = now
+                        finally:
+                            if sys.version_info >= (3, 9):
+                                pool.shutdown(wait=False, cancel_futures=True)
+                            else:
+                                pool.shutdown(wait=False)
+
+                    # Sleep to maintain timing
+                    elapsed = time.time() - loop_start
+                    if elapsed < min_interval:
+                        time.sleep(min_interval - elapsed)
+
+        finally:
+            self.cleanup()
+
+    def stop(self) -> None:
+        """Stop the sensor hub."""
+        self._running = False
+
+    def get_info(self) -> List[Dict[str, Any]]:
+        """Get info about all sensors."""
+        return [s.get_info() for s in self.sensors]
+
+    def get_sensor(self, name: str) -> Optional[BaseSensor]:
+        """Get a sensor by name."""
+        for sensor in self.sensors:
+            if sensor.name == name:
+                return sensor
+        return None
+
+
+class _nullcontext:
+    """Null context manager for Python 3.8 compatibility."""
+    def __enter__(self):
+        return None
+    def __exit__(self, *args):
+        return False