plexus-python 0.1.0__py3-none-any.whl

plexus/adapters/ble.py

@@ -0,0 +1,257 @@
+"""
+BLE Relay Adapter - Bluetooth Low Energy gateway support
+
+This adapter scans for BLE peripherals and reads GATT characteristics,
+acting as a relay/gateway for BLE-only devices that can't reach the
+internet directly. Ideal for RPi or Linux gateways.
+
+Requirements:
+    pip install plexus-python[ble]
+    # or
+    pip install bleak
+
+Usage:
+    from plexus.adapters import BLERelayAdapter
+
+    adapter = BLERelayAdapter(
+        service_uuids=["181A"],  # Environmental Sensing
+        scan_duration=5.0,
+    )
+    adapter.connect()
+    for metric in adapter.poll():
+        print(f"{metric.name}: {metric.value}")
+
+Emitted metrics:
+    - {source_prefix}.{device_name}.{char_uuid} - Raw characteristic values
+    - {source_prefix}.{device_name}.rssi - Signal strength
+"""
+
+from typing import Any, Dict, List, Optional
+import asyncio
+import logging
+import struct
+import time
+
+from plexus.adapters.base import (
+    ProtocolAdapter,
+    AdapterConfig,
+    AdapterState,
+    Metric,
+    ConnectionError,
+    ProtocolError,
+)
+from plexus.adapters.registry import register_adapter
+
+logger = logging.getLogger(__name__)
+
+try:
+    import bleak
+    from bleak import BleakScanner, BleakClient
+except ImportError:
+    bleak = None  # type: ignore[assignment]
+    BleakScanner = None  # type: ignore[assignment,misc]
+    BleakClient = None  # type: ignore[assignment,misc]
+
+# Well-known GATT characteristic UUIDs → human-readable names
+_KNOWN_CHARACTERISTICS: Dict[str, str] = {
+    "00002a6e-0000-1000-8000-00805f9b34fb": "temperature",
+    "00002a6f-0000-1000-8000-00805f9b34fb": "humidity",
+    "00002a6d-0000-1000-8000-00805f9b34fb": "pressure",
+    "00002a19-0000-1000-8000-00805f9b34fb": "battery_level",
+    "00002a1c-0000-1000-8000-00805f9b34fb": "temperature_measurement",
+}
+
+
+def _slugify(name: str) -> str:
+    """Convert a BLE device name to a metric-safe slug."""
+    return name.lower().replace(" ", "_").replace("-", "_")[:32]
+
+
+def _try_decode_value(data: bytes, char_uuid: str) -> Any:
+    """Attempt to decode a characteristic value to a numeric type."""
+    uuid_lower = char_uuid.lower()
+
+    # Battery level is a single uint8 percentage
+    if uuid_lower == "00002a19-0000-1000-8000-00805f9b34fb":
+        return data[0] if len(data) >= 1 else None
+
+    # Temperature (sint16, 0.01 degC resolution per BLE SIG)
+    if uuid_lower == "00002a6e-0000-1000-8000-00805f9b34fb":
+        if len(data) >= 2:
+            raw = struct.unpack("<h", data[:2])[0]
+            return raw / 100.0
+        return None
+
+    # Humidity (uint16, 0.01% resolution)
+    if uuid_lower == "00002a6f-0000-1000-8000-00805f9b34fb":
+        if len(data) >= 2:
+            raw = struct.unpack("<H", data[:2])[0]
+            return raw / 100.0
+        return None
+
+    # Pressure (uint32, 0.1 Pa resolution)
+    if uuid_lower == "00002a6d-0000-1000-8000-00805f9b34fb":
+        if len(data) >= 4:
+            raw = struct.unpack("<I", data[:4])[0]
+            return raw / 10.0
+        return None
+
+    # Generic: try to interpret as a number
+    if len(data) == 1:
+        return data[0]
+    if len(data) == 2:
+        return struct.unpack("<h", data[:2])[0]
+    if len(data) == 4:
+        return struct.unpack("<f", data[:4])[0]
+
+    # Fall back to hex string
+    return data.hex()
+
+
+@register_adapter(
+    "ble",
+    description="BLE relay adapter for gateway devices",
+    author="Plexus",
+    version="1.0.0",
+    requires=["bleak"],
+)
+class BLERelayAdapter(ProtocolAdapter):
+    """
+    BLE Relay protocol adapter.
+
+    Scans for BLE peripherals, connects, and reads GATT characteristics.
+    Designed for gateway scenarios where a Linux host (e.g., RPi) relays
+    BLE sensor data to Plexus cloud.
+
+    Args:
+        service_uuids: List of GATT service UUIDs to filter for (short or full form).
+        scan_duration: How long to scan for devices per poll cycle (seconds).
+        name_filter: Only connect to devices whose name contains this string.
+        source_prefix: Prefix for emitted metric names.
+        read_timeout: Timeout for reading each characteristic (seconds).
+    """
+
+    def __init__(
+        self,
+        service_uuids: Optional[List[str]] = None,
+        scan_duration: float = 5.0,
+        name_filter: Optional[str] = None,
+        source_prefix: str = "ble",
+        read_timeout: float = 10.0,
+        **kwargs: Any,
+    ):
+        if bleak is None:
+            raise ImportError(
+                "BLE adapter requires 'bleak'. Install with: pip install plexus-python[ble]"
+            )
+
+        config = AdapterConfig(
+            name="ble",
+            params={
+                "service_uuids": service_uuids,
+                "scan_duration": scan_duration,
+                "name_filter": name_filter,
+                "source_prefix": source_prefix,
+                **kwargs,
+            },
+        )
+        super().__init__(config)
+        self.service_uuids = service_uuids or []
+        self.scan_duration = scan_duration
+        self.name_filter = name_filter
+        self.source_prefix = source_prefix
+        self.read_timeout = read_timeout
+        self._scanner: Any = None
+
+    def connect(self) -> bool:
+        """Initialize the BLE scanner."""
+        try:
+            self._scanner = BleakScanner(
+                service_uuids=self.service_uuids if self.service_uuids else None,
+            )
+            self._set_state(AdapterState.CONNECTED)
+            logger.info("BLE adapter ready (filter: %s)", self.name_filter or "none")
+            return True
+        except Exception as e:
+            self._set_state(AdapterState.ERROR, str(e))
+            raise ConnectionError(f"Failed to initialize BLE scanner: {e}") from e
+
+    def disconnect(self) -> None:
+        """Stop the BLE scanner."""
+        self._scanner = None
+        self._set_state(AdapterState.DISCONNECTED)
+
+    def poll(self) -> List[Metric]:
+        """Scan for BLE devices and read their characteristics."""
+        if not self._scanner:
+            raise ProtocolError("BLE adapter not connected")
+
+        try:
+            return asyncio.run(self._async_poll())
+        except RuntimeError:
+            # If there's already an event loop running, create a new one
+            loop = asyncio.new_event_loop()
+            try:
+                return loop.run_until_complete(self._async_poll())
+            finally:
+                loop.close()
+
+    async def _async_poll(self) -> List[Metric]:
+        """Async implementation of the poll cycle."""
+        metrics: List[Metric] = []
+        now = time.time()
+
+        # Scan for devices
+        devices = await BleakScanner.discover(
+            timeout=self.scan_duration,
+            service_uuids=self.service_uuids if self.service_uuids else None,
+        )
+
+        for device in devices:
+            # Apply name filter
+            if self.name_filter and device.name:
+                if self.name_filter.lower() not in device.name.lower():
+                    continue
+            elif self.name_filter and not device.name:
+                continue
+
+            device_name = _slugify(device.name or device.address.replace(":", ""))
+
+            # Emit RSSI as a metric
+            if device.rssi is not None:
+                metrics.append(Metric(
+                    name=f"{self.source_prefix}.{device_name}.rssi",
+                    value=device.rssi,
+                    timestamp=now,
+                ))
+
+            # Connect and read characteristics
+            try:
+                async with BleakClient(device.address, timeout=self.read_timeout) as client:
+                    for service in client.services:
+                        for char in service.characteristics:
+                            if "read" not in char.properties:
+                                continue
+                            try:
+                                data = await client.read_gatt_char(char.uuid)
+                                value = _try_decode_value(data, char.uuid)
+                                if value is not None:
+                                    char_name = _KNOWN_CHARACTERISTICS.get(
+                                        char.uuid.lower(),
+                                        char.uuid.split("-")[0],
+                                    )
+                                    metrics.append(Metric(
+                                        name=f"{self.source_prefix}.{device_name}.{char_name}",
+                                        value=value,
+                                        timestamp=now,
+                                    ))
+                            except Exception as e:
+                                logger.debug(
+                                    "Failed to read %s from %s: %s",
+                                    char.uuid, device_name, e,
+                                )
+            except Exception as e:
+                logger.warning("Failed to connect to %s: %s", device_name, e)
+
+        logger.debug("BLE poll: %d metrics from %d devices", len(metrics), len(devices))
+        return metrics

plexus/adapters/can.py

@@ -0,0 +1,439 @@
+"""
+CAN Bus Adapter - CAN protocol support with DBC decoding
+
+This adapter reads CAN bus data and emits both raw frames and decoded
+signals when a DBC file is provided.
+
+Requirements:
+    pip install plexus-python[can]
+    # or
+    pip install python-can cantools
+
+Usage:
+    from plexus.adapters import CANAdapter
+
+    # Basic usage with virtual CAN
+    adapter = CANAdapter(interface="socketcan", channel="vcan0")
+    adapter.connect()
+    for metric in adapter.poll():
+        print(f"{metric.name}: {metric.value}")
+
+    # With DBC file for signal decoding
+    adapter = CANAdapter(
+        interface="socketcan",
+        channel="can0",
+        dbc_path="/path/to/vehicle.dbc"
+    )
+
+Supported interfaces:
+    - socketcan (Linux)
+    - pcan (Peak CAN)
+    - vector (Vector CANalyzer)
+    - kvaser (Kvaser)
+    - slcan (Serial CAN)
+    - virtual (Testing)
+
+Emitted metrics:
+    - can.raw.0x{id} - Raw frame data as hex string
+    - {signal_name} - Decoded signals from DBC (e.g., "engine_rpm", "coolant_temp")
+"""
+
+from typing import Any, Dict, List, Optional
+import time
+import logging
+
+from plexus.adapters.base import (
+    ProtocolAdapter,
+    AdapterConfig,
+    AdapterState,
+    Metric,
+    ConnectionError,
+    ProtocolError,
+)
+from plexus.adapters.registry import register_adapter
+
+logger = logging.getLogger(__name__)
+
+# Optional dependencies — imported at module level so they can be
+# mocked in tests with @patch("plexus.adapters.can.can") etc.
+try:
+    import can
+except ImportError:
+    can = None  # type: ignore[assignment]
+
+try:
+    import cantools
+except ImportError:
+    cantools = None  # type: ignore[assignment]
+
+
+@register_adapter(
+    "can",
+    description="CAN bus adapter with DBC signal decoding",
+    author="Plexus",
+    version="1.0.0",
+    requires=["python-can", "cantools"],
+)
+class CANAdapter(ProtocolAdapter):
+    """
+    CAN Bus protocol adapter.
+
+    Reads CAN frames from a CAN interface and optionally decodes them
+    using a DBC file.
+
+    Args:
+        interface: CAN interface type (socketcan, pcan, vector, etc.)
+        channel: CAN channel (can0, vcan0, PCAN_USBBUS1, etc.)
+        bitrate: CAN bitrate in bps (default: 500000)
+        dbc_path: Path to DBC file for signal decoding (optional)
+        emit_raw: Whether to emit raw frame metrics (default: True)
+        emit_decoded: Whether to emit decoded signals (default: True)
+        raw_prefix: Prefix for raw frame metrics (default: "can.raw")
+        filters: List of CAN ID filters as dicts with 'can_id' and 'can_mask'
+        receive_own_messages: Whether to receive own transmitted messages
+        source_id: Source ID for metrics (optional)
+
+    Example:
+        adapter = CANAdapter(
+            interface="socketcan",
+            channel="can0",
+            dbc_path="vehicle.dbc",
+            bitrate=500000
+        )
+
+        with adapter:
+            while True:
+                for metric in adapter.poll():
+                    print(f"{metric.name} = {metric.value}")
+    """
+
+    def __init__(
+        self,
+        interface: str = "socketcan",
+        channel: str = "can0",
+        bitrate: int = 500000,
+        dbc_path: Optional[str] = None,
+        emit_raw: bool = True,
+        emit_decoded: bool = True,
+        raw_prefix: str = "can.raw",
+        filters: Optional[List[Dict[str, int]]] = None,
+        receive_own_messages: bool = False,
+        source_id: Optional[str] = None,
+        **kwargs,
+    ):
+        config = AdapterConfig(
+            name="can",
+            params={
+                "interface": interface,
+                "channel": channel,
+                "bitrate": bitrate,
+                "dbc_path": dbc_path,
+                **kwargs,
+            },
+        )
+        super().__init__(config)
+
+        self.interface = interface
+        self.channel = channel
+        self.bitrate = bitrate
+        self.dbc_path = dbc_path
+        self.emit_raw = emit_raw
+        self.emit_decoded = emit_decoded
+        self.raw_prefix = raw_prefix
+        self.filters = filters
+        self.receive_own_messages = receive_own_messages
+        self._source_id = source_id
+
+        self._bus: Optional[Any] = None  # can.Bus instance
+        self._db: Optional[Any] = None   # cantools.Database instance
+        self._message_cache: Dict[int, Any] = {}  # Cache DBC message lookups
+
+    def validate_config(self) -> bool:
+        """Validate adapter configuration."""
+        if not self.channel:
+            raise ValueError("CAN channel is required")
+
+        valid_interfaces = [
+            "socketcan", "pcan", "vector", "kvaser", "slcan",
+            "virtual", "ixxat", "neovi", "nican", "iscan"
+        ]
+        if self.interface not in valid_interfaces:
+            logger.warning(
+                f"Unknown interface '{self.interface}'. "
+                f"Valid interfaces: {', '.join(valid_interfaces)}"
+            )
+
+        return True
+
+    def connect(self) -> bool:
+        """Connect to CAN bus interface."""
+        if can is None:
+            self._set_state(AdapterState.ERROR, "python-can not installed")
+            raise ConnectionError(
+                "python-can is required. Install with: pip install plexus-python[can]"
+            )
+
+        try:
+            self._set_state(AdapterState.CONNECTING)
+            logger.info(
+                f"Connecting to CAN bus: {self.interface}:{self.channel} "
+                f"at {self.bitrate} bps"
+            )
+
+            # Configure bus
+            bus_kwargs = {
+                "interface": self.interface,
+                "channel": self.channel,
+                "bitrate": self.bitrate,
+                "receive_own_messages": self.receive_own_messages,
+            }
+
+            # Add filters if specified
+            if self.filters:
+                bus_kwargs["can_filters"] = self.filters
+
+            self._bus = can.Bus(**bus_kwargs)
+
+            # Load DBC file if provided
+            if self.dbc_path:
+                self._load_dbc(self.dbc_path)
+
+            self._set_state(AdapterState.CONNECTED)
+            logger.info(f"Connected to CAN bus: {self.channel}")
+            return True
+
+        except Exception as e:
+            self._set_state(AdapterState.ERROR, str(e))
+            logger.error(f"Failed to connect to CAN bus: {e}")
+            raise ConnectionError(f"CAN connection failed: {e}")
+
+    def _load_dbc(self, dbc_path: str) -> None:
+        """Load a DBC file for signal decoding."""
+        if cantools is None:
+            logger.warning(
+                "cantools not installed. DBC decoding disabled. "
+                "Install with: pip install cantools"
+            )
+            self._db = None
+            return
+
+        try:
+            logger.info(f"Loading DBC file: {dbc_path}")
+            self._db = cantools.database.load_file(dbc_path)
+            logger.info(
+                f"Loaded DBC with {len(self._db.messages)} messages"
+            )
+
+            # Pre-cache message lookups by arbitration ID
+            for msg in self._db.messages:
+                self._message_cache[msg.frame_id] = msg
+
+        except FileNotFoundError:
+            logger.error(f"DBC file not found: {dbc_path}")
+            self._db = None
+        except Exception as e:
+            logger.error(f"Failed to load DBC file: {e}")
+            self._db = None
+
+    def disconnect(self) -> None:
+        """Disconnect from CAN bus."""
+        if self._bus:
+            try:
+                self._bus.shutdown()
+                logger.info("Disconnected from CAN bus")
+            except Exception as e:
+                logger.warning(f"Error shutting down CAN bus: {e}")
+            finally:
+                self._bus = None
+
+        self._set_state(AdapterState.DISCONNECTED)
+
+    def poll(self) -> List[Metric]:
+        """
+        Poll for CAN frames and return metrics.
+
+        Returns:
+            List of Metric objects for raw frames and/or decoded signals.
+
+        Raises:
+            OSError: On bus disconnect (triggers auto-reconnect in run loop).
+            ProtocolError: If reading data fails.
+        """
+        if not self._bus:
+            return []
+
+        metrics: List[Metric] = []
+
+        try:
+            # Non-blocking receive with short timeout
+            message = self._bus.recv(timeout=0.1)
+
+            if message is None:
+                return []
+
+            timestamp = message.timestamp if message.timestamp else time.time()
+
+            # Emit raw frame metric
+            if self.emit_raw:
+                raw_metric = self._create_raw_metric(message, timestamp)
+                metrics.append(raw_metric)
+
+            # Decode and emit signal metrics
+            if self.emit_decoded and self._db:
+                decoded_metrics = self._decode_message(message, timestamp)
+                metrics.extend(decoded_metrics)
+
+        except OSError:
+            raise  # Let run loop handle disconnect/reconnect
+        except Exception as e:
+            logger.error(f"Error reading CAN frame: {e}")
+            raise ProtocolError(f"CAN read error: {e}")
+
+        return metrics
+
+    def _create_raw_metric(self, message: Any, timestamp: float) -> Metric:
+        """Create a raw frame metric."""
+        # Format arbitration ID as hex
+        arb_id = f"0x{message.arbitration_id:03X}"
+        metric_name = f"{self.raw_prefix}.{arb_id}"
+
+        # Format data as hex string
+        data_hex = message.data.hex().upper()
+
+        # Include metadata as tags
+        tags = {
+            "arbitration_id": str(message.arbitration_id),
+            "dlc": str(message.dlc),
+            "is_extended": str(message.is_extended_id).lower(),
+        }
+
+        if message.is_error_frame:
+            tags["error_frame"] = "true"
+        if message.is_remote_frame:
+            tags["remote_frame"] = "true"
+
+        return Metric(
+            name=metric_name,
+            value=data_hex,
+            timestamp=timestamp,
+            tags=tags,
+            source_id=self._source_id,
+        )
+
+    def _decode_message(self, message: Any, timestamp: float) -> List[Metric]:
+        """Decode CAN message using DBC and return signal metrics."""
+        metrics: List[Metric] = []
+
+        # Look up message in DBC
+        dbc_message = self._message_cache.get(message.arbitration_id)
+        if not dbc_message:
+            return []
+
+        try:
+            # Decode all signals in the message
+            decoded = dbc_message.decode(message.data)
+
+            for signal_name, value in decoded.items():
+                # Get signal info for units
+                signal = dbc_message.get_signal_by_name(signal_name)
+                tags = {
+                    "can_id": f"0x{message.arbitration_id:03X}",
+                    "dbc_message": dbc_message.name,
+                }
+
+                # Add unit if available
+                if signal and signal.unit:
+                    tags["unit"] = signal.unit
+
+                metrics.append(
+                    Metric(
+                        name=signal_name,
+                        value=value,
+                        timestamp=timestamp,
+                        tags=tags,
+                        source_id=self._source_id,
+                    )
+                )
+
+        except Exception as e:
+            logger.debug(
+                f"Could not decode message 0x{message.arbitration_id:03X}: {e}"
+            )
+
+        return metrics
+
+    def send(
+        self,
+        arbitration_id: int,
+        data: bytes,
+        is_extended_id: bool = False,
+    ) -> bool:
+        """
+        Send a CAN frame.
+
+        Args:
+            arbitration_id: CAN arbitration ID
+            data: Frame data (1-8 bytes)
+            is_extended_id: Whether to use extended (29-bit) ID
+
+        Returns:
+            True if sent successfully
+        """
+        if not self._bus:
+            raise ProtocolError("Not connected to CAN bus")
+
+        try:
+            message = can.Message(
+                arbitration_id=arbitration_id,
+                data=data,
+                is_extended_id=is_extended_id,
+            )
+            self._bus.send(message)
+            logger.debug(f"Sent CAN frame: 0x{arbitration_id:03X} {data.hex()}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to send CAN frame: {e}")
+            raise ProtocolError(f"CAN send error: {e}")
+
+    def send_signal(
+        self,
+        message_name: str,
+        signals: Dict[str, float],
+    ) -> bool:
+        """
+        Send a CAN message with encoded signals (requires DBC).
+
+        Args:
+            message_name: DBC message name
+            signals: Dict of signal names to values
+
+        Returns:
+            True if sent successfully
+        """
+        if not self._db:
+            raise ProtocolError("DBC file required for signal encoding")
+
+        try:
+            # Find message in DBC
+            dbc_message = self._db.get_message_by_name(message_name)
+            data = dbc_message.encode(signals)
+
+            return self.send(dbc_message.frame_id, data)
+
+        except Exception as e:
+            logger.error(f"Failed to send CAN signal: {e}")
+            raise ProtocolError(f"Signal encoding error: {e}")
+
+    @property
+    def stats(self) -> Dict[str, Any]:
+        """Get adapter statistics including CAN-specific info."""
+        base_stats = super().stats
+        base_stats.update({
+            "interface": self.interface,
+            "channel": self.channel,
+            "bitrate": self.bitrate,
+            "dbc_loaded": self._db is not None,
+            "dbc_messages": len(self._message_cache) if self._db else 0,
+        })
+        return base_stats