plexus-python 0.1.0__py3-none-any.whl

plexus/sensors/__init__.py

@@ -0,0 +1,118 @@
+"""
+Plexus Sensor Drivers
+
+Pre-built drivers for common sensors that stream data to Plexus.
+
+Quick Start:
+    from plexus import Plexus
+    from plexus.sensors import MPU6050
+
+    px = Plexus()
+    imu = MPU6050()
+
+    while True:
+        for reading in imu.read():
+            px.send(reading.metric, reading.value)
+
+With SensorHub (recommended):
+    from plexus import Plexus
+    from plexus.sensors import SensorHub, MPU6050, BME280
+
+    hub = SensorHub()
+    hub.add(MPU6050(sample_rate=100))
+    hub.add(BME280(sample_rate=1))
+    hub.run(Plexus())
+
+Auto-detection:
+    from plexus import Plexus
+    from plexus.sensors import auto_sensors
+
+    hub = auto_sensors()  # Finds all connected sensors
+    hub.run(Plexus())
+
+Supported Sensors:
+    - MPU6050: 6-axis IMU (accelerometer + gyroscope)
+    - MPU9250: 9-axis IMU (accelerometer + gyroscope + magnetometer)
+    - BME280: Environmental (temperature, humidity, pressure)
+    - INA219: Current/power monitor (voltage, current, power)
+    - SHT3x: Precision temperature + humidity (with CRC verification)
+    - BH1750: Ambient light sensor (1-65535 lux)
+    - VL53L0X: Time-of-flight distance sensor (30-2000mm)
+    - ADS1115: 16-bit ADC (4 channels, programmable gain)
+    - QMC5883L: 3-axis magnetometer / compass
+    - HMC5883L: 3-axis magnetometer / compass
+    - ADXL345: 3-axis accelerometer (I2C or SPI)
+    - GPSSensor: GPS receiver (lat, lon, altitude, speed via NMEA serial)
+    - SystemSensor: System health (CPU temp, memory, disk, load)
+"""
+
+from .base import BaseSensor, SensorReading, SensorHub
+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
+from .gps import GPSSensor
+from .auto import scan_sensors, auto_sensors, scan_i2c, DetectedSensor
+from .system import SystemSensor
+
+try:
+    from .spi_scan import scan_spi, scan_spi_buses, SPISensorMatch
+except ImportError:
+    pass
+
+__all__ = [
+    # Base classes
+    "BaseSensor",
+    "SensorReading",
+    "SensorHub",
+    # I2C sensors
+    "MPU6050",
+    "MPU9250",
+    "BME280",
+    "INA219",
+    "SHT3x",
+    "BH1750",
+    "VL53L0X",
+    "ADS1115",
+    "QMC5883L",
+    "HMC5883L",
+    "ADXL345",
+    # Serial sensors
+    "GPSSensor",
+    # System
+    "SystemSensor",
+    # Auto-detection
+    "scan_sensors",
+    "auto_sensors",
+    "scan_i2c",
+    "DetectedSensor",
+    "scan_spi",
+    "scan_spi_buses",
+    "SPISensorMatch",
+    # Registry
+    "SENSOR_REGISTRY",
+]
+
+# Maps sensor names to driver classes (used by config and CLI)
+SENSOR_REGISTRY = {
+    # Named sensors (no I2C address needed)
+    "system": SystemSensor,
+    "gps": GPSSensor,
+    # I2C sensors
+    "mpu6050": MPU6050,
+    "mpu9250": MPU9250,
+    "bme280": BME280,
+    "ina219": INA219,
+    "sht3x": SHT3x,
+    "bh1750": BH1750,
+    "vl53l0x": VL53L0X,
+    "ads1115": ADS1115,
+    "qmc5883l": QMC5883L,
+    "hmc5883l": HMC5883L,
+    "adxl345": ADXL345,
+}

plexus/sensors/ads1115.py

@@ -0,0 +1,164 @@
+"""
+ADS1115 16-bit ADC sensor driver.
+
+The ADS1115 is a precision 16-bit ADC with 4 single-ended or 2 differential
+channels. Programmable gain amplifier (PGA) and data rate.
+Communicates via I2C at address 0x48–0x4B (configurable via ADDR pin).
+
+Usage:
+    from plexus.sensors import ADS1115
+
+    sensor = ADS1115()
+    for reading in sensor.read():
+        print(f"{reading.metric}: {reading.value}")
+"""
+
+import time
+from typing import List, Optional
+from .base import BaseSensor, SensorReading
+
+ADS1115_ADDR = 0x48
+
+# Register addresses
+REG_CONVERSION = 0x00
+REG_CONFIG = 0x01
+
+# Config register bits
+# OS: Start single conversion
+OS_SINGLE = 0x8000
+# MUX: Input multiplexer
+MUX_AIN0 = 0x4000  # AIN0 vs GND
+MUX_AIN1 = 0x5000  # AIN1 vs GND
+MUX_AIN2 = 0x6000  # AIN2 vs GND
+MUX_AIN3 = 0x7000  # AIN3 vs GND
+# PGA: Programmable gain (full-scale voltage)
+PGA_6144 = 0x0000   # ±6.144V (LSB = 187.5µV)
+PGA_4096 = 0x0200   # ±4.096V (LSB = 125µV)
+PGA_2048 = 0x0400   # ±2.048V (LSB = 62.5µV) — default
+PGA_1024 = 0x0600   # ±1.024V
+PGA_0512 = 0x0800   # ±0.512V
+PGA_0256 = 0x0A00   # ±0.256V
+# MODE: Operating mode
+MODE_SINGLE = 0x0100  # Single-shot
+# DR: Data rate
+DR_128SPS = 0x0080  # 128 samples per second
+# COMP: Disable comparator
+COMP_DISABLE = 0x0003
+
+MUX_CHANNELS = [MUX_AIN0, MUX_AIN1, MUX_AIN2, MUX_AIN3]
+
+# Voltage per LSB for each PGA setting
+PGA_LSB = {
+    PGA_6144: 0.0001875,
+    PGA_4096: 0.000125,
+    PGA_2048: 0.0000625,
+    PGA_1024: 0.00003125,
+    PGA_0512: 0.000015625,
+    PGA_0256: 0.0000078125,
+}
+
+
+class ADS1115(BaseSensor):
+    """
+    ADS1115 16-bit ADC driver.
+
+    Provides:
+    - adc_ch0 through adc_ch3: Voltage readings in volts (single-ended)
+
+    Default gain: ±4.096V (suitable for 3.3V/5V systems)
+    """
+
+    name = "ADS1115"
+    description = "16-bit ADC (4 channels, programmable gain)"
+    metrics = ["adc_ch0", "adc_ch1", "adc_ch2", "adc_ch3"]
+    i2c_addresses = [0x48, 0x49, 0x4A, 0x4B]
+
+    def __init__(
+        self,
+        address: int = ADS1115_ADDR,
+        bus: int = 1,
+        gain: int = PGA_4096,
+        channels: Optional[List[int]] = None,
+        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.gain = gain
+        self.channels = channels if channels is not None else [0, 1, 2, 3]
+        self._bus = None
+        self._lsb = PGA_LSB.get(gain, 0.000125)
+
+    def setup(self) -> None:
+        try:
+            from smbus2 import SMBus
+        except ImportError:
+            raise ImportError(
+                "smbus2 is required for ADS1115. 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_channel(self, channel: int) -> float:
+        """Read a single ADC channel and return voltage."""
+        config = (
+            OS_SINGLE |
+            MUX_CHANNELS[channel] |
+            self.gain |
+            MODE_SINGLE |
+            DR_128SPS |
+            COMP_DISABLE
+        )
+
+        # Write config to start conversion
+        high = (config >> 8) & 0xFF
+        low = config & 0xFF
+        self._bus.write_i2c_block_data(self.address, REG_CONFIG, [high, low])
+
+        # Wait for conversion (128 SPS = ~8ms per sample)
+        time.sleep(0.009)
+
+        # Read conversion result
+        data = self._bus.read_i2c_block_data(self.address, REG_CONVERSION, 2)
+        raw = (data[0] << 8) | data[1]
+
+        # Convert to signed
+        if raw > 32767:
+            raw -= 65536
+
+        return raw * self._lsb
+
+    def read(self) -> List[SensorReading]:
+        if self._bus is None:
+            self.setup()
+
+        readings = []
+        for ch in self.channels:
+            if 0 <= ch <= 3:
+                voltage = self._read_channel(ch)
+                readings.append(
+                    SensorReading(f"adc_ch{ch}", round(voltage, 4))
+                )
+
+        return readings
+
+    def is_available(self) -> bool:
+        try:
+            from smbus2 import SMBus
+
+            bus = SMBus(self.bus_num)
+            # Read config register — default is 0x8583
+            data = bus.read_i2c_block_data(self.address, REG_CONFIG, 2)
+            bus.close()
+            config = (data[0] << 8) | data[1]
+            # Check OS bit is set (no conversion in progress)
+            return (config & 0x8000) != 0
+        except Exception:
+            return False

plexus/sensors/adxl345.py

@@ -0,0 +1,179 @@
+"""
+ADXL345 3-axis accelerometer driver.
+
+Supports both I2C and SPI interfaces for the ADXL345 digital accelerometer.
+Measures acceleration on X, Y, Z axes in units of g (9.81 m/s²).
+
+Usage (I2C):
+    from plexus.sensors import ADXL345
+
+    accel = ADXL345(bus_type="i2c", address=0x53)
+    accel.setup()
+    for reading in accel.read():
+        print(f"{reading.metric}: {reading.value}")
+
+Usage (SPI):
+    accel = ADXL345(bus_type="spi", spi_bus=0, spi_cs=0)
+    accel.setup()
+    for reading in accel.read():
+        print(f"{reading.metric}: {reading.value}")
+
+With SensorHub:
+    from plexus.sensors import SensorHub, ADXL345
+    hub = SensorHub()
+    hub.add(ADXL345())
+    hub.run(Plexus())
+"""
+
+import struct
+import time
+from typing import Dict, List, Optional
+
+from .base import BaseSensor, SensorReading
+
+
+# ADXL345 registers
+_REG_DEVID = 0x00
+_REG_BW_RATE = 0x2C
+_REG_POWER_CTL = 0x2D
+_REG_DATA_FORMAT = 0x31
+_REG_DATAX0 = 0x32
+
+# Expected chip ID
+_CHIP_ID = 0xE5
+
+# Scale factor: 4mg/LSB in full resolution mode
+_SCALE_FACTOR = 0.004
+
+
+class ADXL345(BaseSensor):
+    """ADXL345 3-axis accelerometer (I2C or SPI)."""
+
+    name = "ADXL345"
+    description = "3-axis accelerometer (±2g/±4g/±8g/±16g)"
+    metrics = ["accel_x", "accel_y", "accel_z"]
+    i2c_addresses = [0x53, 0x1D]
+    spi_devices = [(0, 0)]
+
+    def __init__(
+        self,
+        bus_type: str = "i2c",
+        address: int = 0x53,
+        bus: int = 1,
+        spi_bus: int = 0,
+        spi_cs: int = 0,
+        sample_rate: float = 100.0,
+        prefix: str = "",
+        tags: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Args:
+            bus_type: "i2c" or "spi"
+            address: I2C address (0x53 or 0x1D)
+            bus: I2C bus number (usually 1 on Raspberry Pi)
+            spi_bus: SPI bus number
+            spi_cs: SPI chip select
+            sample_rate: Readings per second (Hz)
+            prefix: Prefix for metric names
+            tags: Tags to add to all readings
+        """
+        super().__init__(sample_rate=sample_rate, prefix=prefix, tags=tags)
+        self.bus_type = bus_type
+        self.address = address
+        self.bus_num = bus
+        self.spi_bus = spi_bus
+        self.spi_cs = spi_cs
+        self._dev = None
+
+    def _read_reg(self, reg: int, length: int = 1) -> bytes:
+        """Read register(s) via I2C or SPI."""
+        if self.bus_type == "spi":
+            # SPI read: bit 7 = read, bit 6 = multi-byte
+            cmd = reg | 0x80
+            if length > 1:
+                cmd |= 0x40
+            tx = [cmd] + [0x00] * length
+            rx = self._dev.xfer2(tx)
+            return bytes(rx[1:])
+        else:
+            if length == 1:
+                return bytes([self._dev.read_byte_data(self.address, reg)])
+            return bytes(self._dev.read_i2c_block_data(self.address, reg, length))
+
+    def _write_reg(self, reg: int, value: int):
+        """Write a register via I2C or SPI."""
+        if self.bus_type == "spi":
+            self._dev.xfer2([reg, value])
+        else:
+            self._dev.write_byte_data(self.address, reg, value)
+
+    def setup(self) -> None:
+        """Initialize the ADXL345."""
+        if self.bus_type == "spi":
+            import spidev
+            self._dev = spidev.SpiDev()
+            self._dev.open(self.spi_bus, self.spi_cs)
+            self._dev.mode = 3
+            self._dev.max_speed_hz = 1000000
+        else:
+            from smbus2 import SMBus
+            self._dev = SMBus(self.bus_num)
+
+        # Verify chip ID
+        chip_id = self._read_reg(_REG_DEVID)[0]
+        if chip_id != _CHIP_ID:
+            raise RuntimeError(
+                f"ADXL345 not found (got chip ID 0x{chip_id:02X}, expected 0x{_CHIP_ID:02X})"
+            )
+
+        # Configure: 100Hz output rate
+        self._write_reg(_REG_BW_RATE, 0x0A)
+        # Full resolution, ±2g range
+        self._write_reg(_REG_DATA_FORMAT, 0x08)
+        # Start measurement
+        self._write_reg(_REG_POWER_CTL, 0x08)
+
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        if self._dev:
+            if self.bus_type == "spi":
+                self._dev.close()
+            else:
+                self._dev.close()
+            self._dev = None
+
+    def read(self) -> List[SensorReading]:
+        """Read acceleration on all three axes."""
+        if not self._dev:
+            return []
+
+        now = time.time()
+        raw = self._read_reg(_REG_DATAX0, 6)
+        x, y, z = struct.unpack("<hhh", raw)
+
+        return [
+            SensorReading("accel_x", round(x * _SCALE_FACTOR, 4), now),
+            SensorReading("accel_y", round(y * _SCALE_FACTOR, 4), now),
+            SensorReading("accel_z", round(z * _SCALE_FACTOR, 4), now),
+        ]
+
+    def is_available(self) -> bool:
+        """Check if ADXL345 is connected."""
+        try:
+            if self.bus_type == "spi":
+                import spidev
+                dev = spidev.SpiDev()
+                dev.open(self.spi_bus, self.spi_cs)
+                dev.mode = 3
+                dev.max_speed_hz = 1000000
+                resp = dev.xfer2([_REG_DEVID | 0x80, 0x00])
+                dev.close()
+                return resp[1] == _CHIP_ID
+            else:
+                from smbus2 import SMBus
+                bus = SMBus(self.bus_num)
+                chip_id = bus.read_byte_data(self.address, _REG_DEVID)
+                bus.close()
+                return chip_id == _CHIP_ID
+        except Exception:
+            return False