plexus-python 0.1.0__py3-none-any.whl

plexus/__init__.py

@@ -0,0 +1,31 @@
+"""
+Plexus Agent - Send sensor data to Plexus in one line of code.
+
+Basic Usage:
+    from plexus import Plexus
+
+    px = Plexus()
+    px.send("temperature", 72.5)
+
+With Sensors (pip install plexus-python[sensors]):
+    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())
+"""
+
+from plexus.client import Plexus
+from plexus.config import load_config, save_config
+
+__version__ = "0.1.0"
+__all__ = ["Plexus", "load_config", "save_config"]

plexus/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running plexus as: python3 -m plexus"""
+from plexus.cli import main
+
+main()

plexus/adapters/__init__.py

@@ -0,0 +1,122 @@
+"""
+Protocol Adapters - Extensible protocol support for Plexus
+
+This module provides a plugin system for protocol adapters, enabling
+Plexus to ingest data from any protocol without modifying core code.
+
+Built-in adapters:
+    - MQTTAdapter: Bridge MQTT brokers to Plexus
+    - CANAdapter: CAN bus with DBC signal decoding
+    - MAVLinkAdapter: MAVLink for drones and autonomous vehicles
+    - OPCUAAdapter: OPC-UA client for industrial automation servers
+    - SerialAdapter: Serial port (USB/UART/RS-232/RS-485) reader
+
+Usage:
+    from plexus.adapters import MQTTAdapter, CANAdapter, MAVLinkAdapter, AdapterRegistry
+
+    # Use built-in adapter
+    adapter = MQTTAdapter(broker="localhost", topic="sensors/#")
+    adapter.connect()
+    adapter.run(on_data=my_callback)
+
+    # CAN bus adapter
+    adapter = CANAdapter(interface="socketcan", channel="can0", dbc_path="vehicle.dbc")
+    with adapter:
+        for metric in adapter.poll():
+            print(f"{metric.name}: {metric.value}")
+
+    # MAVLink adapter
+    adapter = MAVLinkAdapter(connection_string="udpin:0.0.0.0:14550")
+    with adapter:
+        for metric in adapter.poll():
+            print(f"{metric.name}: {metric.value}")
+
+    # Create custom adapter
+    from plexus.adapters import ProtocolAdapter, Metric
+
+    class MyProtocolAdapter(ProtocolAdapter):
+        def connect(self) -> bool:
+            # Connect to your protocol
+            return True
+
+        def poll(self) -> "List[Metric]":
+            # Read data and return metrics
+            return [Metric("sensor.temp", 72.5)]
+
+    # Register custom adapter
+    AdapterRegistry.register("my-protocol", MyProtocolAdapter)
+"""
+
+from plexus.adapters.base import (
+    ProtocolAdapter,
+    Metric,
+    AdapterConfig,
+    AdapterState,
+    AdapterError,
+)
+from plexus.adapters.registry import AdapterRegistry
+from plexus.adapters.mqtt import MQTTAdapter
+
+# Import CANAdapter (requires optional [can] extra)
+try:
+    from plexus.adapters.can import CANAdapter
+    _HAS_CAN = True
+except ImportError:
+    CANAdapter = None  # type: ignore
+    _HAS_CAN = False
+
+# Import ModbusAdapter (requires optional [modbus] extra)
+try:
+    from plexus.adapters.modbus import ModbusAdapter
+    _HAS_MODBUS = True
+except ImportError:
+    ModbusAdapter = None  # type: ignore
+    _HAS_MODBUS = False
+
+# Import MAVLinkAdapter (requires optional [mavlink] extra)
+try:
+    from plexus.adapters.mavlink import MAVLinkAdapter
+    _HAS_MAVLINK = True
+except ImportError:
+    MAVLinkAdapter = None  # type: ignore
+    _HAS_MAVLINK = False
+
+# Import OPCUAAdapter (requires optional [opcua] extra)
+try:
+    from plexus.adapters.opcua import OPCUAAdapter
+    _HAS_OPCUA = True
+except ImportError:
+    OPCUAAdapter = None  # type: ignore
+    _HAS_OPCUA = False
+
+# Import SerialAdapter (requires optional [serial] extra)
+try:
+    from plexus.adapters.serial_adapter import SerialAdapter
+    _HAS_SERIAL = True
+except ImportError:
+    SerialAdapter = None  # type: ignore
+    _HAS_SERIAL = False
+
+# Import BLERelayAdapter (requires optional [ble] extra)
+try:
+    from plexus.adapters.ble import BLERelayAdapter
+    _HAS_BLE = True
+except ImportError:
+    BLERelayAdapter = None  # type: ignore
+    _HAS_BLE = False
+
+__all__ = [
+    "ProtocolAdapter",
+    "Metric",
+    "AdapterConfig",
+    "AdapterState",
+    "AdapterError",
+    "AdapterRegistry",
+    "MQTTAdapter",
+    "CANAdapter",
+    "ModbusAdapter",
+    "MAVLinkAdapter",
+    "OPCUAAdapter",
+    "SerialAdapter",
+    "BLERelayAdapter",
+]

plexus/adapters/base.py

@@ -0,0 +1,409 @@
+"""
+Base Protocol Adapter - Abstract interface for all protocol adapters
+
+This module defines the interface that all protocol adapters must implement.
+By following this interface, new protocols can be added without modifying
+the core Plexus codebase.
+
+Example custom adapter:
+
+    from plexus.adapters import ProtocolAdapter, Metric, AdapterConfig
+
+    class SerialAdapter(ProtocolAdapter):
+        '''Adapter for serial port communication'''
+
+        def __init__(self, port: str, baudrate: int = 9600, **kwargs):
+            config = AdapterConfig(
+                name="serial",
+                params={"port": port, "baudrate": baudrate, **kwargs}
+            )
+            super().__init__(config)
+            self.port = port
+            self.baudrate = baudrate
+            self._serial = None
+
+        def connect(self) -> bool:
+            import serial
+            self._serial = serial.Serial(self.port, self.baudrate)
+            return self._serial.is_open
+
+        def disconnect(self) -> None:
+            if self._serial:
+                self._serial.close()
+
+        def poll(self) -> "List[Metric]":
+            line = self._serial.readline().decode().strip()
+            # Parse your protocol format
+            metric, value = line.split(":")
+            return [Metric(metric, float(value))]
+"""
+
+import logging
+import random
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Union
+import time
+
+logger = logging.getLogger(__name__)
+
+
+class AdapterState(Enum):
+    """Adapter connection state"""
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    ERROR = "error"
+    RECONNECTING = "reconnecting"
+
+
+class AdapterError(Exception):
+    """Base exception for adapter errors"""
+    pass
+
+
+class ConnectionError(AdapterError):
+    """Raised when connection fails"""
+    pass
+
+
+class ProtocolError(AdapterError):
+    """Raised when protocol-specific error occurs"""
+    pass
+
+
+@dataclass
+class AdapterConfig:
+    """Configuration for a protocol adapter"""
+    name: str
+    params: Dict[str, Any] = field(default_factory=dict)
+
+    # Connection settings
+    auto_reconnect: bool = True
+    reconnect_interval: float = 5.0
+    max_reconnect_attempts: int = 10
+
+    # Data settings
+    batch_size: int = 100
+    flush_interval: float = 1.0
+
+
+@dataclass
+class Metric:
+    """
+    A single metric data point.
+
+    This is the universal format that all adapters produce.
+    The Plexus client will convert these to the ingest API format.
+
+    Args:
+        name: Metric name (e.g., "temperature", "motor.rpm", "robot.state")
+        value: The value - can be number, string, bool, dict, or list
+        timestamp: Unix timestamp (seconds). If None, current time is used.
+        tags: Optional key-value metadata
+        source_id: Optional source identifier
+        data_class: Pipeline data class - "metric" (default), "event", or "blob"
+
+    Examples:
+        Metric("temperature", 72.5)
+        Metric("robot.state", "MOVING")
+        Metric("position", {"x": 1.5, "y": 2.3, "z": 0.0})
+        Metric("joint_angles", [0.5, 1.2, -0.3, 0.0])
+    """
+    name: str
+    value: Union[int, float, str, bool, Dict[str, Any], List[Any]]
+    timestamp: Optional[float] = None
+    tags: Optional[Dict[str, str]] = None
+    source_id: Optional[str] = None
+    data_class: str = "metric"
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = time.time()
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API submission"""
+        result = {
+            "class": self.data_class,
+            "metric": self.name,
+            "value": self.value,
+            "timestamp": self.timestamp,
+        }
+        if self.tags:
+            result["tags"] = self.tags
+        if self.source_id:
+            result["source_id"] = self.source_id
+        return result
+
+
+# Type alias for data callback
+DataCallback = Callable[[List[Metric]], None]
+
+
+class ProtocolAdapter(ABC):
+    """
+    Abstract base class for protocol adapters.
+
+    All protocol adapters must inherit from this class and implement
+    the required abstract methods.
+
+    Lifecycle:
+        1. __init__() - Configure the adapter
+        2. connect() - Establish connection
+        3. run() or poll() - Receive data
+        4. disconnect() - Clean up
+
+    Two modes of operation:
+        - Push mode: Override on_data() or pass callback to run()
+        - Pull mode: Call poll() periodically to get data
+    """
+
+    def __init__(self, config: AdapterConfig):
+        self.config = config
+        self._state = AdapterState.DISCONNECTED
+        self._error: Optional[str] = None
+        self._metrics_received = 0
+        self._last_data_time: Optional[float] = None
+        self._on_data_callback: Optional[DataCallback] = None
+        self._on_state_change: Optional[Callable[[AdapterState], None]] = None
+        self._on_error_report: Optional[Any] = None  # async fn(source, error, severity)
+
+    @property
+    def state(self) -> AdapterState:
+        """Current adapter state"""
+        return self._state
+
+    @property
+    def is_connected(self) -> bool:
+        """Whether adapter is connected"""
+        return self._state == AdapterState.CONNECTED
+
+    @property
+    def error(self) -> Optional[str]:
+        """Last error message, if any"""
+        return self._error
+
+    @property
+    def stats(self) -> Dict[str, Any]:
+        """Adapter statistics"""
+        return {
+            "state": self._state.value,
+            "metrics_received": self._metrics_received,
+            "last_data_time": self._last_data_time,
+            "error": self._error,
+        }
+
+    def _set_state(self, state: AdapterState, error: Optional[str] = None):
+        """Update adapter state and notify listeners"""
+        old_state = self._state
+        self._state = state
+        self._error = error
+        if self._on_state_change:
+            self._on_state_change(state)
+        # Report transitions to ERROR or RECONNECTING to dashboard
+        if state in (AdapterState.ERROR, AdapterState.RECONNECTING) and old_state != state:
+            if self._on_error_report:
+                import asyncio
+                severity = "error" if state == AdapterState.ERROR else "warning"
+                msg = error or f"Adapter {self.config.name} entered {state.value}"
+                try:
+                    coro = self._on_error_report(
+                        f"adapter.{self.config.name}", msg, severity
+                    )
+                    # Fire-and-forget if there's a running loop
+                    loop = asyncio.get_event_loop()
+                    if loop.is_running():
+                        asyncio.ensure_future(coro)
+                    else:
+                        loop.run_until_complete(coro)
+                except Exception:
+                    pass
+
+    def _emit_data(self, metrics: List[Metric]):
+        """Emit data to callback"""
+        if metrics:
+            self._metrics_received += len(metrics)
+            self._last_data_time = time.time()
+            if self._on_data_callback:
+                self._on_data_callback(metrics)
+
+    # =========================================================================
+    # Auto-Reconnection
+    # =========================================================================
+
+    def _reconnect_loop(self, max_attempts: Optional[int] = None):
+        """Exponential backoff reconnection.
+
+        Uses config values if max_attempts is not specified.
+        """
+        if max_attempts is None:
+            max_attempts = self.config.max_reconnect_attempts
+
+        attempt = 0
+        delay = self.config.reconnect_interval
+
+        while max_attempts is None or attempt < max_attempts:
+            attempt += 1
+            jitter = random.uniform(0.75, 1.25)
+            time.sleep(delay * jitter)
+
+            try:
+                self.disconnect()
+                result = self.connect()
+                if result:
+                    logger.info(
+                        "%s: reconnected after %d attempt(s)",
+                        self.config.name, attempt,
+                    )
+                    return True
+            except Exception as e:
+                logger.warning(
+                    "%s: reconnect attempt %d failed: %s",
+                    self.config.name, attempt, e,
+                )
+
+            delay = min(delay * 2, 60.0)
+
+        self._set_state(AdapterState.ERROR, "Max reconnect attempts reached")
+        return False
+
+    # =========================================================================
+    # Abstract methods - MUST be implemented by subclasses
+    # =========================================================================
+
+    @abstractmethod
+    def connect(self) -> bool:
+        """
+        Establish connection to the data source.
+
+        Returns:
+            True if connection successful, False otherwise.
+
+        Raises:
+            ConnectionError: If connection fails with an error.
+        """
+        pass
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """
+        Close connection and clean up resources.
+
+        This should be idempotent - calling it multiple times should be safe.
+        """
+        pass
+
+    @abstractmethod
+    def poll(self) -> List[Metric]:
+        """
+        Poll for new data (pull mode).
+
+        Returns:
+            List of Metric objects. Empty list if no new data.
+
+        Raises:
+            ProtocolError: If reading data fails.
+
+        Note:
+            For push-based protocols (like MQTT), this may return an empty
+            list and data will arrive via the callback instead.
+        """
+        pass
+
+    # =========================================================================
+    # Optional methods - MAY be overridden by subclasses
+    # =========================================================================
+
+    def validate_config(self) -> bool:
+        """
+        Validate adapter configuration.
+
+        Override this to add protocol-specific validation.
+
+        Returns:
+            True if config is valid.
+
+        Raises:
+            ValueError: If config is invalid.
+        """
+        return True
+
+    def on_data(self, metrics: List[Metric]) -> None:
+        """
+        Handle incoming data (push mode).
+
+        Override this for custom data handling, or pass a callback to run().
+
+        Args:
+            metrics: List of received metrics.
+        """
+        pass
+
+    def run(
+        self,
+        on_data: Optional[DataCallback] = None,
+        on_state_change: Optional[Callable[[AdapterState], None]] = None,
+        blocking: bool = True,
+    ) -> None:
+        """
+        Run the adapter (main loop for push-based protocols).
+
+        Args:
+            on_data: Callback for received data. If None, on_data() method is used.
+            on_state_change: Callback for state changes.
+            blocking: If True, blocks until stopped. If False, returns immediately.
+
+        For pull-based protocols, this starts a polling loop.
+        For push-based protocols, this starts listening for events.
+        """
+        self._on_data_callback = on_data
+        self._on_state_change = on_state_change
+
+        if not self.is_connected:
+            if not self.connect():
+                raise ConnectionError(f"Failed to connect: {self._error}")
+
+        if blocking:
+            self._run_loop()
+
+    def _run_loop(self) -> None:
+        """
+        Default run loop implementation (polling mode).
+
+        Override this for push-based protocols like MQTT.
+        Handles disconnect detection and auto-reconnection.
+        """
+        try:
+            while True:
+                try:
+                    while self.is_connected:
+                        metrics = self.poll()
+                        if metrics:
+                            self._emit_data(metrics)
+                            self.on_data(metrics)
+                        time.sleep(0.01)  # 100 Hz max
+                except (ConnectionError, OSError) as e:
+                    logger.warning("%s: connection lost: %s", self.config.name, e)
+                    self._set_state(AdapterState.RECONNECTING, str(e))
+                    if self.config.auto_reconnect:
+                        if self._reconnect_loop():
+                            continue
+                    break
+
+                # Normal exit (is_connected went False)
+                break
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self.disconnect()
+
+    def __enter__(self):
+        """Context manager entry"""
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.disconnect()
+        return False