gridos 0.1.0__py3-none-any.whl

gridos/__init__.py

@@ -0,0 +1,10 @@
+"""
+GridOS — Open Energy Operating System.
+
+Vendor-neutral middleware for managing Distributed Energy Resources (DERs)
+through a unified, standards-based interface.
+"""
+
+__version__ = "0.1.0"
+__author__ = "GridOS Contributors"
+__license__ = "MIT"

gridos/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""
+GridOS protocol adapters.
+
+Provides a unified interface for communicating with Distributed Energy
+Resources over various industrial protocols (Modbus TCP/RTU, MQTT, DNP3,
+IEC 61850, OPC-UA).  All adapters inherit from :class:`BaseAdapter` and
+expose the same async API.
+"""
+
+from gridos.adapters.base import BaseAdapter
+
+__all__ = ["BaseAdapter"]

gridos/adapters/base.py

@@ -0,0 +1,116 @@
+"""
+Abstract base class for all GridOS protocol adapters.
+
+Every concrete adapter (Modbus, MQTT, DNP3, …) must inherit from
+:class:`BaseAdapter` and implement the four async lifecycle methods:
+``connect``, ``disconnect``, ``read_telemetry``, and ``write_command``.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from gridos.models.common import ControlCommand, DERTelemetry
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAdapter(ABC):
+    """Unified async interface for DER communication protocols.
+
+    Parameters
+    ----------
+    device_id:
+        Identifier of the device this adapter instance manages.
+    config:
+        Protocol-specific configuration dictionary.
+    """
+
+    def __init__(self, device_id: str, config: dict[str, Any] | None = None) -> None:
+        self.device_id = device_id
+        self.config: dict[str, Any] = config or {}
+        self._connected: bool = False
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+
+    # ── Properties ───────────────────────────────────────────────────────
+
+    @property
+    def is_connected(self) -> bool:
+        """Return ``True`` if the adapter has an active connection."""
+        return self._connected
+
+    @property
+    def protocol_name(self) -> str:
+        """Human-readable protocol name (override in subclasses)."""
+        return "unknown"
+
+    # ── Abstract Methods ─────────────────────────────────────────────────
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish a connection to the device.
+
+        Raises
+        ------
+        ConnectionError
+            If the connection cannot be established.
+        """
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Gracefully close the connection."""
+
+    @abstractmethod
+    async def read_telemetry(self) -> DERTelemetry:
+        """Read the latest telemetry from the device.
+
+        Returns
+        -------
+        DERTelemetry
+            A validated telemetry snapshot.
+
+        Raises
+        ------
+        IOError
+            If the read operation fails.
+        """
+
+    @abstractmethod
+    async def write_command(self, command: ControlCommand) -> bool:
+        """Send a control command to the device.
+
+        Parameters
+        ----------
+        command:
+            The validated control command to execute.
+
+        Returns
+        -------
+        bool
+            ``True`` if the command was acknowledged by the device.
+
+        Raises
+        ------
+        IOError
+            If the write operation fails.
+        """
+
+    # ── Context Manager ──────────────────────────────────────────────────
+
+    async def __aenter__(self) -> BaseAdapter:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.disconnect()
+
+    # ── Helpers ──────────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        status = "connected" if self._connected else "disconnected"
+        return (
+            f"<{self.__class__.__name__} device_id={self.device_id!r} "
+            f"protocol={self.protocol_name!r} status={status}>"
+        )

gridos/adapters/dnp3.py

@@ -0,0 +1,97 @@
+"""
+DNP3 protocol adapter for GridOS (stub).
+
+DNP3 (Distributed Network Protocol 3) is widely used in SCADA systems for
+utility-scale DER communication.  This module provides the adapter skeleton;
+a full implementation requires a DNP3 master library such as ``opendnp3`` or
+``pydnp3``.
+
+TODO:
+    - Integrate with ``opendnp3`` C++ bindings or ``pydnp3``.
+    - Implement integrity polls and event-driven reads.
+    - Support DNP3 Secure Authentication (SA).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from gridos.adapters.base import BaseAdapter
+from gridos.models.common import ControlCommand, DERStatus, DERTelemetry
+
+logger = logging.getLogger(__name__)
+
+
+class DNP3Adapter(BaseAdapter):
+    """DNP3 master adapter (stub implementation).
+
+    Parameters
+    ----------
+    device_id:
+        Unique device identifier.
+    config:
+        Expected keys: ``outstation_host``, ``outstation_port`` (default 20000),
+        ``master_address`` (default 1), ``outstation_address`` (default 10).
+    """
+
+    def __init__(self, device_id: str, config: dict[str, Any] | None = None) -> None:
+        super().__init__(device_id, config)
+        self._outstation_host: str = self.config.get("outstation_host", "localhost")
+        self._outstation_port: int = int(self.config.get("outstation_port", 20000))
+        self._master_address: int = int(self.config.get("master_address", 1))
+        self._outstation_address: int = int(self.config.get("outstation_address", 10))
+
+    @property
+    def protocol_name(self) -> str:
+        return "dnp3"
+
+    async def connect(self) -> None:
+        """Establish a DNP3 master session.
+
+        Raises
+        ------
+        NotImplementedError
+            Full DNP3 support is not yet implemented.
+        """
+        self.logger.warning(
+            "DNP3 adapter connect() called — stub implementation. "
+            "Install opendnp3 and implement the full master stack."
+        )
+        # Mark as connected so that the adapter can be used in test harnesses
+        # with simulated data.
+        self._connected = True
+
+    async def disconnect(self) -> None:
+        """Close the DNP3 session."""
+        self._connected = False
+        self.logger.info("DNP3 adapter disconnected (stub)")
+
+    async def read_telemetry(self) -> DERTelemetry:
+        """Perform an integrity poll and return telemetry.
+
+        Returns a placeholder telemetry object until the full DNP3 master
+        stack is integrated.
+        """
+        self.logger.debug("DNP3 read_telemetry() — returning placeholder data")
+        return DERTelemetry(
+            device_id=self.device_id,
+            timestamp=datetime.utcnow(),
+            power_kw=0.0,
+            reactive_power_kvar=0.0,
+            status=DERStatus.UNKNOWN,
+            metadata={"note": "DNP3 stub — replace with real implementation"},
+        )
+
+    async def write_command(self, command: ControlCommand) -> bool:
+        """Send a CROB or analog output to the outstation.
+
+        Returns ``False`` until the full DNP3 master stack is integrated.
+        """
+        self.logger.warning(
+            "DNP3 write_command() called — stub implementation. "
+            "Command %s was NOT dispatched.",
+            command.command_id,
+        )
+        return False

gridos/adapters/iec61850.py

@@ -0,0 +1,99 @@
+"""
+IEC 61850 MMS protocol adapter for GridOS (stub).
+
+IEC 61850 is the international standard for communication in electrical
+substations and DER integration.  A full implementation requires an
+MMS (Manufacturing Message Specification) client library such as
+``libiec61850`` with Python bindings.
+
+TODO:
+    - Integrate with ``libiec61850`` or equivalent MMS client.
+    - Implement GOOSE subscriber for fast tripping signals.
+    - Map logical nodes (MMXU, DGEN, DSTO) to GridOS models.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from gridos.adapters.base import BaseAdapter
+from gridos.models.common import ControlCommand, DERStatus, DERTelemetry
+
+logger = logging.getLogger(__name__)
+
+
+class IEC61850Adapter(BaseAdapter):
+    """IEC 61850 MMS client adapter (stub implementation).
+
+    Parameters
+    ----------
+    device_id:
+        Unique device identifier.
+    config:
+        Expected keys: ``ied_host``, ``ied_port`` (default 102),
+        ``logical_device``, ``logical_node``.
+    """
+
+    def __init__(self, device_id: str, config: dict[str, Any] | None = None) -> None:
+        super().__init__(device_id, config)
+        self._ied_host: str = self.config.get("ied_host", "localhost")
+        self._ied_port: int = int(self.config.get("ied_port", 102))
+        self._logical_device: str = self.config.get("logical_device", "LD0")
+        self._logical_node: str = self.config.get("logical_node", "MMXU1")
+
+    @property
+    def protocol_name(self) -> str:
+        return "iec61850"
+
+    async def connect(self) -> None:
+        """Establish an MMS association with the IED.
+
+        Raises
+        ------
+        NotImplementedError
+            Full IEC 61850 support is not yet implemented.
+        """
+        self.logger.warning(
+            "IEC 61850 adapter connect() called — stub implementation. "
+            "Integrate libiec61850 for production use."
+        )
+        self._connected = True
+
+    async def disconnect(self) -> None:
+        """Release the MMS association."""
+        self._connected = False
+        self.logger.info("IEC 61850 adapter disconnected (stub)")
+
+    async def read_telemetry(self) -> DERTelemetry:
+        """Read data attributes from the configured logical node.
+
+        Returns a placeholder telemetry object until the full MMS client
+        is integrated.
+        """
+        self.logger.debug("IEC 61850 read_telemetry() — returning placeholder data")
+        return DERTelemetry(
+            device_id=self.device_id,
+            timestamp=datetime.utcnow(),
+            power_kw=0.0,
+            reactive_power_kvar=0.0,
+            status=DERStatus.UNKNOWN,
+            metadata={
+                "note": "IEC 61850 stub — replace with real MMS implementation",
+                "logical_device": self._logical_device,
+                "logical_node": self._logical_node,
+            },
+        )
+
+    async def write_command(self, command: ControlCommand) -> bool:
+        """Write a control value to the IED via MMS.
+
+        Returns ``False`` until the full MMS client is integrated.
+        """
+        self.logger.warning(
+            "IEC 61850 write_command() called — stub implementation. "
+            "Command %s was NOT dispatched.",
+            command.command_id,
+        )
+        return False

gridos/adapters/modbus.py

@@ -0,0 +1,177 @@
+"""
+Modbus TCP/RTU protocol adapter for GridOS.
+
+Uses ``pymodbus`` (v3.6+) with its native async transport to read holding
+registers and write coils / registers on DER devices.  Register mappings
+are configurable per device via the ``config`` dictionary.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+
+from gridos.adapters.base import BaseAdapter
+from gridos.models.common import ControlCommand, DERStatus, DERTelemetry
+
+logger = logging.getLogger(__name__)
+
+# Default Modbus register map — override via adapter config
+DEFAULT_REGISTER_MAP: dict[str, dict[str, Any]] = {
+    "power_kw": {"address": 0, "count": 2, "scale": 0.1, "unit": "kW"},
+    "reactive_power_kvar": {"address": 2, "count": 2, "scale": 0.1, "unit": "kVAR"},
+    "voltage_v": {"address": 4, "count": 2, "scale": 0.1, "unit": "V"},
+    "current_a": {"address": 6, "count": 2, "scale": 0.01, "unit": "A"},
+    "frequency_hz": {"address": 8, "count": 1, "scale": 0.01, "unit": "Hz"},
+    "soc_percent": {"address": 9, "count": 1, "scale": 0.1, "unit": "%"},
+    "temperature_c": {"address": 10, "count": 1, "scale": 0.1, "unit": "°C"},
+}
+
+
+def _decode_registers(registers: list[int], count: int, scale: float) -> float:
+    """Decode one or two 16-bit registers into a scaled float."""
+    if count == 2 and len(registers) >= 2:
+        raw = (registers[0] << 16) | registers[1]
+    elif registers:
+        raw = registers[0]
+    else:
+        raw = 0
+    return raw * scale
+
+
+class ModbusAdapter(BaseAdapter):
+    """Async Modbus TCP adapter.
+
+    Parameters
+    ----------
+    device_id:
+        Unique device identifier.
+    config:
+        Must contain ``host`` and ``port``.  Optionally ``unit_id``
+        (default 1) and ``register_map`` (overrides defaults).
+    """
+
+    def __init__(self, device_id: str, config: dict[str, Any] | None = None) -> None:
+        super().__init__(device_id, config)
+        self._host: str = self.config.get("host", "localhost")
+        self._port: int = int(self.config.get("port", 502))
+        self._unit_id: int = int(self.config.get("unit_id", 1))
+        self._register_map: dict[str, dict[str, Any]] = self.config.get(
+            "register_map", DEFAULT_REGISTER_MAP
+        )
+        self._client: Any = None
+
+    @property
+    def protocol_name(self) -> str:
+        return "modbus_tcp"
+
+    async def connect(self) -> None:
+        """Establish an async Modbus TCP connection."""
+        try:
+            from pymodbus.client import AsyncModbusTcpClient
+
+            self._client = AsyncModbusTcpClient(
+                host=self._host,
+                port=self._port,
+                timeout=5,
+            )
+            connected = await self._client.connect()
+            if not connected:
+                raise ConnectionError(
+                    f"Modbus TCP connection to {self._host}:{self._port} failed"
+                )
+            self._connected = True
+            self.logger.info(
+                "Modbus connected",
+                extra={
+                    "device_id": self.device_id,
+                    "host": self._host,
+                    "port": self._port,
+                },
+            )
+        except ImportError as err:
+            raise ImportError(
+                "pymodbus is required for the Modbus adapter. "
+                "Install it with: pip install pymodbus"
+            ) from err
+        except Exception as exc:
+            self._connected = False
+            self.logger.error("Modbus connection error: %s", exc)
+            raise ConnectionError(str(exc)) from exc
+
+    async def disconnect(self) -> None:
+        """Close the Modbus TCP connection."""
+        if self._client is not None:
+            self._client.close()
+            self._connected = False
+            self.logger.info("Modbus disconnected", extra={"device_id": self.device_id})
+
+    async def read_telemetry(self) -> DERTelemetry:
+        """Read registers and return a ``DERTelemetry`` snapshot."""
+        if not self._connected or self._client is None:
+            raise OSError("Modbus adapter is not connected")
+
+        values: dict[str, float] = {}
+        for field_name, mapping in self._register_map.items():
+            try:
+                result = await self._client.read_holding_registers(
+                    address=mapping["address"],
+                    count=mapping["count"],
+                    slave=self._unit_id,
+                )
+                if result.isError():
+                    self.logger.warning(
+                        "Modbus read error for %s: %s", field_name, result
+                    )
+                    values[field_name] = 0.0
+                else:
+                    values[field_name] = _decode_registers(
+                        result.registers, mapping["count"], mapping["scale"]
+                    )
+            except Exception as exc:
+                self.logger.warning("Modbus read exception for %s: %s", field_name, exc)
+                values[field_name] = 0.0
+
+        return DERTelemetry(
+            device_id=self.device_id,
+            timestamp=datetime.utcnow(),
+            power_kw=values.get("power_kw", 0.0),
+            reactive_power_kvar=values.get("reactive_power_kvar", 0.0),
+            voltage_v=values.get("voltage_v"),
+            current_a=values.get("current_a"),
+            frequency_hz=values.get("frequency_hz"),
+            soc_percent=values.get("soc_percent"),
+            temperature_c=values.get("temperature_c"),
+            status=DERStatus.ONLINE,
+        )
+
+    async def write_command(self, command: ControlCommand) -> bool:
+        """Write a power setpoint to the device via Modbus registers."""
+        if not self._connected or self._client is None:
+            raise OSError("Modbus adapter is not connected")
+
+        try:
+            if command.setpoint_kw is not None:
+                # Write setpoint to register 100 (configurable)
+                target_register = int(self.config.get("setpoint_register", 100))
+                raw_value = int(command.setpoint_kw / 0.1)  # scale factor
+                result = await self._client.write_register(
+                    address=target_register,
+                    value=raw_value,
+                    slave=self._unit_id,
+                )
+                if result.isError():
+                    self.logger.error("Modbus write error: %s", result)
+                    return False
+                self.logger.info(
+                    "Modbus command sent: setpoint_kw=%.2f to register %d",
+                    command.setpoint_kw,
+                    target_register,
+                )
+                return True
+            self.logger.warning("No setpoint_kw in command; nothing written")
+            return False
+        except Exception as exc:
+            self.logger.error("Modbus write exception: %s", exc)
+            return False

gridos/adapters/mqtt.py

@@ -0,0 +1,178 @@
+"""
+MQTT protocol adapter for GridOS.
+
+Subscribes to device telemetry topics and publishes control commands using
+``paho-mqtt`` with an asyncio wrapper.  Messages are expected in JSON format
+matching the :class:`DERTelemetry` schema.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+
+from gridos.adapters.base import BaseAdapter
+from gridos.models.common import ControlCommand, DERStatus, DERTelemetry
+
+logger = logging.getLogger(__name__)
+
+
+class MQTTAdapter(BaseAdapter):
+    """Async MQTT adapter using ``paho-mqtt``.
+
+    Parameters
+    ----------
+    device_id:
+        Unique device identifier.
+    config:
+        Must contain ``broker_host``.  Optional keys: ``broker_port``
+        (default 1883), ``username``, ``password``, ``topic_prefix``
+        (default ``gridos/``), ``qos`` (default 1).
+    """
+
+    def __init__(self, device_id: str, config: dict[str, Any] | None = None) -> None:
+        super().__init__(device_id, config)
+        self._broker_host: str = self.config.get("broker_host", "localhost")
+        self._broker_port: int = int(self.config.get("broker_port", 1883))
+        self._username: str = self.config.get("username", "")
+        self._password: str = self.config.get("password", "")
+        self._topic_prefix: str = self.config.get("topic_prefix", "gridos/")
+        self._qos: int = int(self.config.get("qos", 1))
+        self._client: Any = None
+        self._latest_telemetry: DERTelemetry | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._on_telemetry_callback: Callable[[DERTelemetry], None] | None = None
+
+    @property
+    def protocol_name(self) -> str:
+        return "mqtt"
+
+    @property
+    def telemetry_topic(self) -> str:
+        """MQTT topic for this device's telemetry."""
+        return f"{self._topic_prefix}telemetry/{self.device_id}"
+
+    @property
+    def command_topic(self) -> str:
+        """MQTT topic for this device's commands."""
+        return f"{self._topic_prefix}command/{self.device_id}"
+
+    def set_telemetry_callback(self, callback: Callable[[DERTelemetry], None]) -> None:
+        """Register a callback invoked on every new telemetry message."""
+        self._on_telemetry_callback = callback
+
+    async def connect(self) -> None:
+        """Connect to the MQTT broker and subscribe to the telemetry topic."""
+        try:
+            import paho.mqtt.client as mqtt
+
+            self._loop = asyncio.get_running_loop()
+            self._client = mqtt.Client(
+                client_id=f"gridos-{self.device_id}",
+                protocol=mqtt.MQTTv5,
+                callback_api_version=mqtt.CallbackAPIVersion.VERSION2,
+            )
+
+            if self._username:
+                self._client.username_pw_set(self._username, self._password)
+
+            self._client.on_connect = self._on_connect
+            self._client.on_message = self._on_message
+
+            self._client.connect_async(
+                self._broker_host, self._broker_port, keepalive=60
+            )
+            self._client.loop_start()
+            self._connected = True
+            self.logger.info(
+                "MQTT connecting to %s:%d", self._broker_host, self._broker_port
+            )
+        except ImportError as err:
+            raise ImportError(
+                "paho-mqtt is required for the MQTT adapter. "
+                "Install it with: pip install paho-mqtt"
+            ) from err
+        except Exception as exc:
+            self._connected = False
+            self.logger.error("MQTT connection error: %s", exc)
+            raise ConnectionError(str(exc)) from exc
+
+    async def disconnect(self) -> None:
+        """Disconnect from the MQTT broker."""
+        if self._client is not None:
+            self._client.loop_stop()
+            self._client.disconnect()
+            self._connected = False
+            self.logger.info("MQTT disconnected", extra={"device_id": self.device_id})
+
+    # ── Paho callbacks (run in the network thread) ───────────────────────
+
+    def _on_connect(
+        self, client: Any, userdata: Any, flags: Any, rc: Any, properties: Any = None
+    ) -> None:
+        """Subscribe to the device telemetry topic on successful connect."""
+        client.subscribe(self.telemetry_topic, qos=self._qos)
+        self.logger.info("MQTT subscribed to %s", self.telemetry_topic)
+
+    def _on_message(self, client: Any, userdata: Any, msg: Any) -> None:
+        """Parse incoming JSON telemetry and store it."""
+        try:
+            payload = json.loads(msg.payload.decode("utf-8"))
+            telemetry = DERTelemetry(
+                device_id=self.device_id,
+                timestamp=datetime.fromisoformat(
+                    payload.get("timestamp", datetime.utcnow().isoformat())
+                ),
+                power_kw=float(payload.get("power_kw", 0.0)),
+                reactive_power_kvar=float(payload.get("reactive_power_kvar", 0.0)),
+                voltage_v=payload.get("voltage_v"),
+                current_a=payload.get("current_a"),
+                frequency_hz=payload.get("frequency_hz"),
+                soc_percent=payload.get("soc_percent"),
+                temperature_c=payload.get("temperature_c"),
+                status=DERStatus(payload.get("status", "online")),
+            )
+            self._latest_telemetry = telemetry
+
+            if self._on_telemetry_callback is not None:
+                self._on_telemetry_callback(telemetry)
+
+        except Exception as exc:
+            self.logger.warning("Failed to parse MQTT message: %s", exc)
+
+    # ── Public API ───────────────────────────────────────────────────────
+
+    async def read_telemetry(self) -> DERTelemetry:
+        """Return the most recently received telemetry.
+
+        If no message has been received yet, returns a zero-valued snapshot.
+        """
+        if self._latest_telemetry is not None:
+            return self._latest_telemetry
+
+        self.logger.debug("No MQTT telemetry received yet for %s", self.device_id)
+        return DERTelemetry(
+            device_id=self.device_id,
+            timestamp=datetime.utcnow(),
+            power_kw=0.0,
+            status=DERStatus.UNKNOWN,
+        )
+
+    async def write_command(self, command: ControlCommand) -> bool:
+        """Publish a control command to the device's command topic."""
+        if self._client is None:
+            raise OSError("MQTT adapter is not connected")
+
+        try:
+            payload = command.model_dump_json()
+            info = self._client.publish(self.command_topic, payload, qos=self._qos)
+            info.wait_for_publish(timeout=5)
+            self.logger.info("MQTT command published to %s", self.command_topic)
+            return True
+        except Exception as exc:
+            self.logger.error("MQTT publish error: %s", exc)
+            return False