plexus-python 0.1.0__py3-none-any.whl

plexus/sensors/bh1750.py

@@ -0,0 +1,102 @@
+"""
+BH1750 ambient light sensor driver.
+
+The BH1750 measures ambient light intensity in lux.
+Communicates via I2C at address 0x23 (ADDR pin low) or 0x5C (ADDR pin high).
+
+Usage:
+    from plexus.sensors import BH1750
+
+    sensor = BH1750()
+    for reading in sensor.read():
+        print(f"{reading.metric}: {reading.value}")
+"""
+
+import time
+from typing import List, Optional
+from .base import BaseSensor, SensorReading
+
+BH1750_ADDR = 0x23
+BH1750_ADDR_ALT = 0x5C
+
+# Commands
+CMD_POWER_ON = 0x01
+CMD_RESET = 0x07
+CMD_CONT_HRES = 0x10   # Continuous high-resolution mode (1 lux, 120ms)
+CMD_CONT_HRES2 = 0x11  # Continuous high-resolution mode 2 (0.5 lux, 120ms)
+CMD_ONCE_HRES = 0x20   # One-time high-resolution mode (1 lux, 120ms)
+
+
+class BH1750(BaseSensor):
+    """
+    BH1750 ambient light sensor driver.
+
+    Provides:
+    - light_lux: Ambient light intensity in lux (1-65535 lux range)
+    """
+
+    name = "BH1750"
+    description = "Ambient light sensor (1-65535 lux)"
+    metrics = ["light_lux"]
+    i2c_addresses = [BH1750_ADDR, BH1750_ADDR_ALT]
+
+    def __init__(
+        self,
+        address: int = BH1750_ADDR,
+        bus: int = 1,
+        sample_rate: float = 1.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 BH1750. Install with: pip install smbus2"
+            )
+
+        self._bus = SMBus(self.bus_num)
+
+        # Power on and set continuous high-res mode
+        self._bus.write_byte(self.address, CMD_POWER_ON)
+        time.sleep(0.01)
+        self._bus.write_byte(self.address, CMD_CONT_HRES)
+        time.sleep(0.180)  # First measurement takes up to 180ms
+
+    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()
+
+        # Read 2 bytes of light data
+        data = self._bus.read_i2c_block_data(self.address, CMD_CONT_HRES, 2)
+        raw = (data[0] << 8) | data[1]
+
+        # Convert to lux (divide by 1.2 per datasheet)
+        lux = raw / 1.2
+
+        return [
+            SensorReading("light_lux", round(lux, 1)),
+        ]
+
+    def is_available(self) -> bool:
+        try:
+            from smbus2 import SMBus
+
+            bus = SMBus(self.bus_num)
+            # Power on command — if device ACKs, it's there
+            bus.write_byte(self.address, CMD_POWER_ON)
+            bus.close()
+            return True
+        except Exception:
+            return False

plexus/sensors/bme280.py

@@ -0,0 +1,241 @@
+"""
+BME280 environmental sensor driver.
+
+The BME280 provides temperature, humidity, and pressure readings.
+Communicates via I2C at address 0x76 or 0x77.
+
+Usage:
+    from plexus import Plexus
+    from plexus.sensors import BME280
+
+    px = Plexus()
+    env = BME280()
+
+    while True:
+        for reading in env.read():
+            px.send(reading.metric, reading.value)
+        time.sleep(1)  # 1 Hz is typical for environmental
+
+Or with SensorHub:
+    from plexus.sensors import SensorHub, BME280
+
+    hub = SensorHub()
+    hub.add(BME280(sample_rate=1))
+    hub.run(Plexus())
+"""
+
+from typing import List, Optional
+from .base import BaseSensor, SensorReading
+
+# I2C addresses
+BME280_ADDR = 0x76
+BME280_ADDR_ALT = 0x77
+
+# Register addresses
+BME280_CHIP_ID_REG = 0xD0
+BME280_CTRL_HUM = 0xF2
+BME280_CTRL_MEAS = 0xF4
+BME280_CONFIG = 0xF5
+BME280_DATA_START = 0xF7
+BME280_CALIB_START = 0x88
+BME280_CALIB_HUM_START = 0xE1
+
+
+class BME280(BaseSensor):
+    """
+    BME280 environmental sensor driver.
+
+    Provides:
+    - temperature: Temperature in Celsius
+    - humidity: Relative humidity in %
+    - pressure: Atmospheric pressure in hPa
+    """
+
+    name = "BME280"
+    description = "Environmental sensor (temperature, humidity, pressure)"
+    metrics = ["temperature", "humidity", "pressure"]
+    i2c_addresses = [BME280_ADDR, BME280_ADDR_ALT]
+
+    def __init__(
+        self,
+        address: int = BME280_ADDR,
+        bus: int = 1,
+        sample_rate: float = 1.0,
+        prefix: str = "",
+        tags: Optional[dict] = None,
+    ):
+        """
+        Initialize BME280 driver.
+
+        Args:
+            address: I2C address (0x76 or 0x77)
+            bus: I2C bus number (usually 1 on Raspberry Pi)
+            sample_rate: Readings per second (1 Hz typical)
+            prefix: Prefix for metric names
+            tags: Tags to add to all readings
+        """
+        super().__init__(sample_rate=sample_rate, prefix=prefix, tags=tags)
+        self.address = address
+        self.bus_num = bus
+        self._bus = None
+        self._calib = None
+
+    def setup(self) -> None:
+        """Initialize the BME280 and read calibration data."""
+        try:
+            from smbus2 import SMBus
+        except ImportError:
+            raise ImportError(
+                "smbus2 is required for BME280. Install with: pip install smbus2"
+            )
+
+        self._bus = SMBus(self.bus_num)
+
+        # Read calibration data
+        self._read_calibration()
+
+        # Configure sensor
+        # Humidity oversampling x1
+        self._bus.write_byte_data(self.address, BME280_CTRL_HUM, 0x01)
+        # Temperature and pressure oversampling x1, normal mode
+        self._bus.write_byte_data(self.address, BME280_CTRL_MEAS, 0x27)
+        # Standby 1000ms, filter off
+        self._bus.write_byte_data(self.address, BME280_CONFIG, 0xA0)
+
+    def cleanup(self) -> None:
+        """Close I2C bus."""
+        if self._bus:
+            self._bus.close()
+            self._bus = None
+
+    def _read_calibration(self) -> None:
+        """Read factory calibration data."""
+        # Read temperature and pressure calibration (26 bytes at 0x88)
+        calib1 = self._bus.read_i2c_block_data(self.address, BME280_CALIB_START, 26)
+
+        # Read humidity calibration (7 bytes at 0xE1)
+        calib2 = self._bus.read_i2c_block_data(self.address, BME280_CALIB_HUM_START, 7)
+
+        # Parse calibration data
+        self._calib = {
+            # Temperature
+            "T1": calib1[0] | (calib1[1] << 8),
+            "T2": self._signed16(calib1[2] | (calib1[3] << 8)),
+            "T3": self._signed16(calib1[4] | (calib1[5] << 8)),
+            # Pressure
+            "P1": calib1[6] | (calib1[7] << 8),
+            "P2": self._signed16(calib1[8] | (calib1[9] << 8)),
+            "P3": self._signed16(calib1[10] | (calib1[11] << 8)),
+            "P4": self._signed16(calib1[12] | (calib1[13] << 8)),
+            "P5": self._signed16(calib1[14] | (calib1[15] << 8)),
+            "P6": self._signed16(calib1[16] | (calib1[17] << 8)),
+            "P7": self._signed16(calib1[18] | (calib1[19] << 8)),
+            "P8": self._signed16(calib1[20] | (calib1[21] << 8)),
+            "P9": self._signed16(calib1[22] | (calib1[23] << 8)),
+            # Humidity
+            "H1": calib1[25],
+            "H2": self._signed16(calib2[0] | (calib2[1] << 8)),
+            "H3": calib2[2],
+            "H4": (calib2[3] << 4) | (calib2[4] & 0x0F),
+            "H5": (calib2[5] << 4) | ((calib2[4] >> 4) & 0x0F),
+            "H6": self._signed8(calib2[6]),
+        }
+
+    def _signed16(self, value: int) -> int:
+        """Convert unsigned 16-bit to signed."""
+        if value > 32767:
+            return value - 65536
+        return value
+
+    def _signed8(self, value: int) -> int:
+        """Convert unsigned 8-bit to signed."""
+        if value > 127:
+            return value - 256
+        return value
+
+    def read(self) -> List[SensorReading]:
+        """Read temperature, humidity, and pressure."""
+        if self._bus is None:
+            self.setup()
+
+        # Read raw data (8 bytes starting at 0xF7)
+        data = self._bus.read_i2c_block_data(self.address, BME280_DATA_START, 8)
+
+        # Parse raw values (20-bit for pressure/temp, 16-bit for humidity)
+        raw_press = (data[0] << 12) | (data[1] << 4) | (data[2] >> 4)
+        raw_temp = (data[3] << 12) | (data[4] << 4) | (data[5] >> 4)
+        raw_hum = (data[6] << 8) | data[7]
+
+        # Compensate temperature
+        temperature, t_fine = self._compensate_temperature(raw_temp)
+
+        # Compensate pressure
+        pressure = self._compensate_pressure(raw_press, t_fine)
+
+        # Compensate humidity
+        humidity = self._compensate_humidity(raw_hum, t_fine)
+
+        return [
+            SensorReading("temperature", round(temperature, 2)),
+            SensorReading("humidity", round(humidity, 1)),
+            SensorReading("pressure", round(pressure, 2)),
+        ]
+
+    def _compensate_temperature(self, raw: int) -> tuple:
+        """Compensate raw temperature value. Returns (temp_C, t_fine)."""
+        c = self._calib
+        var1 = ((raw / 16384.0) - (c["T1"] / 1024.0)) * c["T2"]
+        var2 = (((raw / 131072.0) - (c["T1"] / 8192.0)) ** 2) * c["T3"]
+        t_fine = var1 + var2
+        temperature = t_fine / 5120.0
+        return temperature, t_fine
+
+    def _compensate_pressure(self, raw: int, t_fine: float) -> float:
+        """Compensate raw pressure value. Returns pressure in hPa."""
+        c = self._calib
+        var1 = t_fine / 2.0 - 64000.0
+        var2 = var1 * var1 * c["P6"] / 32768.0
+        var2 = var2 + var1 * c["P5"] * 2.0
+        var2 = var2 / 4.0 + c["P4"] * 65536.0
+        var1 = (c["P3"] * var1 * var1 / 524288.0 + c["P2"] * var1) / 524288.0
+        var1 = (1.0 + var1 / 32768.0) * c["P1"]
+
+        if var1 == 0:
+            return 0
+
+        pressure = 1048576.0 - raw
+        pressure = ((pressure - var2 / 4096.0) * 6250.0) / var1
+        var1 = c["P9"] * pressure * pressure / 2147483648.0
+        var2 = pressure * c["P8"] / 32768.0
+        pressure = pressure + (var1 + var2 + c["P7"]) / 16.0
+
+        return pressure / 100.0  # Convert Pa to hPa
+
+    def _compensate_humidity(self, raw: int, t_fine: float) -> float:
+        """Compensate raw humidity value. Returns relative humidity in %."""
+        c = self._calib
+        humidity = t_fine - 76800.0
+        humidity = (raw - (c["H4"] * 64.0 + c["H5"] / 16384.0 * humidity)) * (
+            c["H2"] / 65536.0 * (1.0 + c["H6"] / 67108864.0 * humidity *
+            (1.0 + c["H3"] / 67108864.0 * humidity))
+        )
+        humidity = humidity * (1.0 - c["H1"] * humidity / 524288.0)
+
+        if humidity < 0:
+            humidity = 0
+        elif humidity > 100:
+            humidity = 100
+
+        return humidity
+
+    def is_available(self) -> bool:
+        """Check if BME280 is connected."""
+        try:
+            from smbus2 import SMBus
+
+            bus = SMBus(self.bus_num)
+            chip_id = bus.read_byte_data(self.address, BME280_CHIP_ID_REG)
+            bus.close()
+            return chip_id == 0x60  # BME280 chip ID
+        except Exception:
+            return False

plexus/sensors/gps.py

@@ -0,0 +1,317 @@
+"""
+GPS NMEA sensor driver.
+
+Reads NMEA sentences from a serial GPS module (e.g., NEO-6M, NEO-7M, u-blox)
+and provides latitude, longitude, altitude, speed, and satellite count.
+
+Default: /dev/ttyAMA0 at 9600 baud (Raspberry Pi UART)
+
+Usage:
+    from plexus.sensors import GPSSensor
+
+    gps = GPSSensor()
+    for reading in gps.read():
+        print(f"{reading.metric}: {reading.value}")
+
+Or with auto-detection:
+    from plexus.sensors import GPSSensor
+
+    gps = GPSSensor.auto_detect()
+    if gps:
+        for reading in gps.read():
+            print(f"{reading.metric}: {reading.value}")
+"""
+
+import logging
+from typing import List, Optional
+from .base import BaseSensor, SensorReading
+
+logger = logging.getLogger(__name__)
+
+# Common GPS serial ports on Linux/Raspberry Pi
+GPS_SERIAL_PORTS = [
+    "/dev/ttyAMA0",     # Raspberry Pi built-in UART
+    "/dev/ttyACM0",     # USB GPS (u-blox)
+    "/dev/ttyUSB0",     # USB-serial GPS
+    "/dev/ttyS0",       # Standard serial
+    "/dev/serial0",     # RPi serial symlink
+]
+
+GPS_DEFAULT_BAUD = 9600
+
+
+def _nmea_to_decimal(raw: str, direction: str) -> Optional[float]:
+    """Convert NMEA coordinate (DDMM.MMMMM) to decimal degrees."""
+    if not raw or not direction:
+        return None
+
+    try:
+        raw_f = float(raw)
+    except ValueError:
+        return None
+
+    degrees = int(raw_f / 100)
+    minutes = raw_f - (degrees * 100)
+    decimal = degrees + (minutes / 60.0)
+
+    if direction in ("S", "W"):
+        decimal = -decimal
+
+    return decimal
+
+
+def _validate_coordinate(lat: float, lon: float) -> bool:
+    """Check that lat/lon are within valid ranges."""
+    return -90.0 <= lat <= 90.0 and -180.0 <= lon <= 180.0
+
+
+def _nmea_checksum(sentence: str, require_checksum: bool = True) -> bool:
+    """Verify NMEA checksum. Rejects sentences without checksum by default."""
+    if "*" not in sentence:
+        return not require_checksum
+
+    body, checksum_str = sentence.rsplit("*", 1)
+    # Remove leading $
+    body = body.lstrip("$")
+
+    try:
+        expected = int(checksum_str[:2], 16)
+    except ValueError:
+        return False
+
+    computed = 0
+    for c in body:
+        computed ^= ord(c)
+
+    return computed == expected
+
+
+class GPSSensor(BaseSensor):
+    """
+    GPS NMEA sensor driver.
+
+    Reads NMEA sentences from a serial GPS module.
+
+    Provides:
+    - gps_latitude: Latitude in decimal degrees
+    - gps_longitude: Longitude in decimal degrees
+    - gps_altitude: Altitude in meters (from GGA)
+    - gps_speed_knots: Speed over ground in knots (from RMC)
+    - gps_satellites: Number of satellites in use
+    - gps_hdop: Horizontal dilution of precision
+    """
+
+    name = "GPS"
+    description = "GPS receiver (position, altitude, speed)"
+    metrics = [
+        "gps_latitude", "gps_longitude", "gps_altitude",
+        "gps_speed_knots", "gps_satellites", "gps_hdop",
+    ]
+    i2c_addresses = []  # Not an I2C sensor
+
+    def __init__(
+        self,
+        port: str = "/dev/ttyAMA0",
+        baudrate: int = GPS_DEFAULT_BAUD,
+        sample_rate: float = 1.0,
+        prefix: str = "",
+        tags: Optional[dict] = None,
+    ):
+        super().__init__(sample_rate=sample_rate, prefix=prefix, tags=tags)
+        self.port = port
+        self.baudrate = baudrate
+        self._serial = None
+        self._latitude = None
+        self._longitude = None
+        self._altitude = None
+        self._speed_knots = None
+        self._satellites = None
+        self._hdop = None
+        self._valid = False
+        self._buffer = ""
+
+    def setup(self) -> None:
+        try:
+            import serial
+        except ImportError:
+            raise ImportError(
+                "pyserial is required for GPS. Install with: pip install pyserial"
+            )
+
+        self._serial = serial.Serial(
+            self.port,
+            self.baudrate,
+            timeout=1.0,
+        )
+        # Flush input buffer
+        self._serial.reset_input_buffer()
+
+    def cleanup(self) -> None:
+        if self._serial:
+            self._serial.close()
+            self._serial = None
+
+    def _parse_gga(self, fields: List[str]) -> None:
+        """Parse $GPGGA or $GNGGA sentence."""
+        if len(fields) < 10:
+            return
+
+        try:
+            quality = int(fields[6]) if fields[6] else 0
+        except ValueError:
+            return
+        if quality == 0:
+            self._valid = False
+            return
+
+        lat = _nmea_to_decimal(fields[2], fields[3])
+        lon = _nmea_to_decimal(fields[4], fields[5])
+
+        if lat is not None and lon is not None:
+            if not _validate_coordinate(lat, lon):
+                return
+            self._latitude = lat
+            self._longitude = lon
+        elif lat is not None:
+            self._latitude = lat
+        elif lon is not None:
+            self._longitude = lon
+
+        try:
+            self._satellites = int(fields[7]) if fields[7] else None
+        except ValueError:
+            self._satellites = None
+        try:
+            self._hdop = float(fields[8]) if fields[8] else None
+        except ValueError:
+            self._hdop = None
+        try:
+            self._altitude = float(fields[9]) if fields[9] else None
+        except ValueError:
+            self._altitude = None
+        self._valid = True
+
+    def _parse_rmc(self, fields: List[str]) -> None:
+        """Parse $GPRMC or $GNRMC sentence."""
+        if len(fields) < 8:
+            return
+
+        if fields[2] != "A":  # V = void (no fix)
+            return
+
+        lat = _nmea_to_decimal(fields[3], fields[4])
+        lon = _nmea_to_decimal(fields[5], fields[6])
+
+        if lat is not None and lon is not None:
+            if not _validate_coordinate(lat, lon):
+                return
+            self._latitude = lat
+            self._longitude = lon
+        elif lat is not None:
+            self._latitude = lat
+        elif lon is not None:
+            self._longitude = lon
+
+        try:
+            self._speed_knots = float(fields[7]) if fields[7] else None
+        except ValueError:
+            self._speed_knots = None
+        self._valid = True
+
+    def _process_line(self, line: str) -> None:
+        """Process a single NMEA sentence."""
+        line = line.strip()
+        if not line.startswith("$"):
+            return
+
+        if not _nmea_checksum(line):
+            return
+
+        # Remove checksum for parsing
+        if "*" in line:
+            line = line[:line.index("*")]
+
+        fields = line.split(",")
+        sentence_type = fields[0]
+
+        if sentence_type in ("$GPGGA", "$GNGGA"):
+            self._parse_gga(fields)
+        elif sentence_type in ("$GPRMC", "$GNRMC"):
+            self._parse_rmc(fields)
+
+    def read(self) -> List[SensorReading]:
+        if self._serial is None:
+            self.setup()
+
+        # Read available data (non-blocking batch)
+        if self._serial.in_waiting > 0:
+            raw = self._serial.read(self._serial.in_waiting)
+            self._buffer += raw.decode("ascii", errors="ignore")
+
+            # Process complete lines
+            while "\n" in self._buffer:
+                line, self._buffer = self._buffer.split("\n", 1)
+                self._process_line(line)
+
+        if not self._valid:
+            return []
+
+        readings = []
+        if self._latitude is not None:
+            readings.append(SensorReading("gps_latitude", round(self._latitude, 6)))
+        if self._longitude is not None:
+            readings.append(SensorReading("gps_longitude", round(self._longitude, 6)))
+        if self._altitude is not None:
+            readings.append(SensorReading("gps_altitude", round(self._altitude, 1)))
+        if self._speed_knots is not None:
+            readings.append(SensorReading("gps_speed_knots", round(self._speed_knots, 1)))
+        if self._satellites is not None:
+            readings.append(SensorReading("gps_satellites", self._satellites))
+        if self._hdop is not None:
+            readings.append(SensorReading("gps_hdop", round(self._hdop, 1)))
+
+        return readings
+
+    def validate_reading(self, reading: "SensorReading") -> bool:
+        """Reject readings with out-of-range values."""
+        if reading.metric == "gps_latitude" and not (-90.0 <= reading.value <= 90.0):
+            return False
+        if reading.metric == "gps_longitude" and not (-180.0 <= reading.value <= 180.0):
+            return False
+        if reading.metric == "gps_altitude" and not (-1000.0 <= reading.value <= 100000.0):
+            return False
+        if reading.metric == "gps_satellites" and not (0 <= reading.value <= 100):
+            return False
+        return True
+
+    def is_available(self) -> bool:
+        """Check if a GPS module is connected and sending data."""
+        try:
+            import serial
+
+            ser = serial.Serial(self.port, self.baudrate, timeout=3.0)
+            data = ser.read(256)
+            ser.close()
+            # Check if we got any NMEA data
+            return b"$GP" in data or b"$GN" in data
+        except Exception:
+            return False
+
+    @classmethod
+    def auto_detect(cls) -> Optional["GPSSensor"]:
+        """
+        Try to find a connected GPS module on common serial ports.
+
+        Returns:
+            GPSSensor instance if found, None otherwise.
+        """
+        for port in GPS_SERIAL_PORTS:
+            try:
+                sensor = cls(port=port)
+                if sensor.is_available():
+                    logger.info(f"GPS detected on {port}")
+                    return cls(port=port)
+            except Exception:
+                continue
+
+        return None