halyn 0.2.0__py3-none-any.whl

halyn/drivers/opcua.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+OPC-UA Driver — Industrial PLCs, SCADA systems.
+
+Connects to Siemens, ABB, Rockwell, Schneider, any OPC-UA server.
+The language of factories.
+"""
+from __future__ import annotations
+from typing import Any
+from nrp import NRPDriver, ShieldRule, ShieldType
+
+class OPCUADriver(NRPDriver):
+    def __init__(self, endpoint: str = "opc.tcp://localhost:4840",
+                 node_ids: list[str] | None = None) -> None:
+        self.endpoint = endpoint
+        self.node_ids = node_ids or []
+        self._client: Any = None
+
+    @property
+    def kind(self) -> str: return "opcua"
+
+    @property
+    def capabilities(self) -> list[str]:
+        return ["read_node", "write_node", "browse", "subscribe"]
+
+    async def connect(self) -> bool:
+        try:
+            from asyncua import Client
+            self._client = Client(self.endpoint)
+            await self._client.connect()
+            return True
+        except Exception:
+            return False
+
+    async def disconnect(self) -> None:
+        if self._client:
+            await self._client.disconnect()
+
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        if not self._client:
+            return {"error": "not connected"}
+        ids = channels or self.node_ids
+        values: dict[str, Any] = {}
+        for node_id in ids:
+            try:
+                node = self._client.get_node(node_id)
+                val = await node.read_value()
+                values[node_id] = val
+            except Exception as e:
+                values[node_id] = f"error: {e}"
+        return values
+
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        if not self._client:
+            raise RuntimeError("Not connected to OPC-UA server")
+        if command == "write_node":
+            node = self._client.get_node(args["node_id"])
+            await node.write_value(args["value"])
+            return {"written": args["node_id"], "value": args["value"]}
+        if command == "browse":
+            node = self._client.get_node(args.get("node_id", "i=84"))
+            children = await node.get_children()
+            return [{"node_id": str(c.nodeid), "name": (await c.read_browse_name()).Name}
+                    for c in children[:50]]
+        raise ValueError(f"Unknown opcua command: {command}")
+
+    def shield_rules(self) -> list[ShieldRule]:
+        return [
+            ShieldRule("read_only_default", ShieldType.PATTERN, "write*",
+                      description="Write operations need explicit allow"),
+            ShieldRule("confirm_write", ShieldType.CONFIRM, "write_node",
+                      description="Confirm before writing to PLC"),
+            ShieldRule("max_write_rate", ShieldType.LIMIT, 10, "writes/s",
+                      description="Rate limit writes"),
+        ]
+

halyn/drivers/ros2.py

@@ -0,0 +1,124 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+ROS2 Driver — Any robot running ROS2.
+
+Bridges NRP to the Robot Operating System 2 ecosystem.
+Wraps ROS2 topics (observe) and services/actions (act).
+Works with: Universal Robots, Unitree, TurtleBot, any ROS2 robot.
+
+Requires: rclpy (ROS2 Python client library)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nrp import NRPDriver, ShieldRule, ShieldType
+
+
+class ROS2Driver(NRPDriver):
+    """Control any ROS2 robot through NRP."""
+
+    def __init__(self, node_name: str = "nrp_bridge",
+                 observe_topics: dict[str, str] | None = None,
+                 action_services: dict[str, str] | None = None) -> None:
+        self.node_name = node_name
+        self.observe_topics = observe_topics or {
+            "joint_states": "/joint_states",
+            "odom": "/odom",
+            "battery": "/battery_state",
+            "camera": "/camera/image_raw",
+        }
+        self.action_services = action_services or {
+            "move": "/move_base",
+            "gripper": "/gripper_command",
+        }
+        self._ros_node: Any = None
+        self._latest: dict[str, Any] = {}
+
+    @property
+    def kind(self) -> str:
+        return "ros2"
+
+    @property
+    def capabilities(self) -> list[str]:
+        return list(self.action_services.keys()) + ["emergency_stop", "get_tf"]
+
+    async def connect(self) -> bool:
+        try:
+            import rclpy
+            from rclpy.node import Node
+            if not rclpy.ok():
+                rclpy.init()
+            self._ros_node = Node(self.node_name)
+            # Subscribe to observation topics
+            for name, topic in self.observe_topics.items():
+                self._create_subscription(name, topic)
+            return True
+        except ImportError:
+            # ROS2 not installed — degrade gracefully
+            return False
+        except Exception:
+            return False
+
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        if self._ros_node:
+            import rclpy
+            rclpy.spin_once(self._ros_node, timeout_sec=0.1)
+        if channels:
+            return {ch: self._latest.get(ch) for ch in channels}
+        return dict(self._latest)
+
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        if command == "emergency_stop":
+            return await self._emergency_stop()
+        service = self.action_services.get(command)
+        if not service:
+            raise ValueError(f"Unknown command: {command}. Available: {self.capabilities}")
+        # Publish to action topic or call service
+        return await self._call_service(service, args)
+
+    def shield_rules(self) -> list[ShieldRule]:
+        return [
+            ShieldRule("max_velocity", ShieldType.LIMIT, 1.5, unit="m/s",
+                      description="Maximum linear velocity"),
+            ShieldRule("max_angular", ShieldType.LIMIT, 1.0, unit="rad/s",
+                      description="Maximum angular velocity"),
+            ShieldRule("workspace", ShieldType.ZONE,
+                      {"x": [-2, 2], "y": [-2, 2], "z": [0, 2]}, unit="m",
+                      description="Allowed workspace bounds"),
+            ShieldRule("emergency_stop", ShieldType.COMMAND, True,
+                      description="Always allowed — immediate stop"),
+            ShieldRule("min_battery", ShieldType.THRESHOLD, 10, unit="percent",
+                      description="Refuse commands below 10% battery"),
+        ]
+
+    async def _emergency_stop(self) -> dict[str, Any]:
+        """Immediate stop — highest priority, bypasses all queues."""
+        if self._ros_node:
+            # Publish zero velocity to cmd_vel
+            try:
+                from geometry_msgs.msg import Twist
+                pub = self._ros_node.create_publisher(Twist, "/cmd_vel", 10)
+                pub.publish(Twist())  # All zeros = stop
+                return {"stopped": True}
+            except Exception as e:
+                return {"stopped": False, "error": str(e)}
+        return {"stopped": False, "error": "No ROS2 node"}
+
+    async def _call_service(self, service: str, args: dict[str, Any]) -> Any:
+        """Call a ROS2 service. Override for specific robot types."""
+        # Base implementation — subclass for specific robots
+        return {"service": service, "args": args, "status": "not_implemented"}
+
+    def _create_subscription(self, name: str, topic: str) -> None:
+        """Create a ROS2 subscription. Stores latest message."""
+        try:
+            from std_msgs.msg import String
+            def callback(msg: Any) -> None:
+                self._latest[name] = str(msg)
+            self._ros_node.create_subscription(String, topic, callback, 10)
+        except Exception:
+            pass
+

halyn/drivers/serial.py

@@ -0,0 +1,226 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Serial meta-driver — UART, RS-485, Modbus RTU/TCP.
+
+Covers legacy industrial hardware, embedded controllers,
+PLCs, energy meters, and any RS-232/485 device.
+"""
+
+from __future__ import annotations
+
+import logging
+import struct
+from typing import Any
+
+from nrp import NRPDriver, NRPManifest, NRPId, ChannelSpec, ActionSpec, ShieldSpec, ShieldRule, ShieldType
+
+log = logging.getLogger("halyn.drivers.serial")
+
+try:
+    import serial
+    HAS_SERIAL = True
+except ImportError:
+    HAS_SERIAL = False
+
+try:
+    from pymodbus.client import ModbusTcpClient, ModbusSerialClient
+    HAS_MODBUS = True
+except ImportError:
+    HAS_MODBUS = False
+
+
+class SerialDriver(NRPDriver):
+    """
+    Serial port driver with Modbus support.
+
+    Modes:
+      - raw: direct UART read/write
+      - modbus_rtu: Modbus over RS-485 serial
+      - modbus_tcp: Modbus over TCP/IP
+    """
+
+    def __init__(
+        self,
+        port: str = "/dev/ttyUSB0",
+        baudrate: int = 9600,
+        mode: str = "raw",
+        modbus_host: str = "",
+        modbus_port: int = 502,
+        unit_id: int = 1,
+        registers: dict[str, dict[str, Any]] | None = None,
+    ) -> None:
+        super().__init__()
+        self.port = port
+        self.baudrate = baudrate
+        self.mode = mode
+        self.modbus_host = modbus_host
+        self.modbus_port = modbus_port
+        self.unit_id = unit_id
+        self.registers = registers or {}
+        self._serial = None
+        self._modbus = None
+
+    def manifest(self) -> NRPManifest:
+        channels = []
+        actions = []
+
+        if self.mode == "raw":
+            channels.append(ChannelSpec("buffer", "string", description="Raw serial buffer"))
+            actions.append(ActionSpec("write", {"data": "string — bytes to send"}, "Write to serial port"))
+            actions.append(ActionSpec("query", {"data": "string", "timeout": "float"}, "Write then read response"))
+        else:
+            for name, reg in self.registers.items():
+                rtype = reg.get("type", "int")
+                unit = reg.get("unit", "")
+                channels.append(ChannelSpec(name, rtype, unit=unit, description=reg.get("desc", "")))
+                if reg.get("writable"):
+                    actions.append(ActionSpec(
+                        f"write_{name}",
+                        {"value": f"{rtype} — target value"},
+                        f"Write {name} register",
+                        dangerous=reg.get("dangerous", False),
+                    ))
+
+        actions.append(ActionSpec("reconnect", {}, "Reset connection"))
+
+        return NRPManifest(
+            nrp_id=self._nrp_id or NRPId.create("local", "serial", self.port.split("/")[-1]),
+            manufacturer="Serial",
+            model=f"{self.mode} @ {self.port if self.mode == 'raw' else self.modbus_host}",
+            firmware=f"baud={self.baudrate}" if self.mode == "raw" else f"unit={self.unit_id}",
+            observe=channels,
+            act=actions,
+            shield=[ShieldSpec("rate", "limit", 10, "req/s", "Max poll rate")],
+        )
+
+    async def connect(self) -> bool:
+        if self.mode == "raw":
+            if not HAS_SERIAL:
+                log.warning("serial: pyserial not installed")
+                return False
+            try:
+                self._serial = serial.Serial(self.port, self.baudrate, timeout=1)
+                return self._serial.is_open
+            except Exception as e:
+                log.error("serial.connect_failed port=%s error=%s", self.port, e)
+                return False
+
+        elif self.mode in ("modbus_rtu", "modbus_tcp"):
+            if not HAS_MODBUS:
+                log.warning("serial: pymodbus not installed")
+                return False
+            try:
+                if self.mode == "modbus_tcp":
+                    self._modbus = ModbusTcpClient(self.modbus_host, port=self.modbus_port)
+                else:
+                    self._modbus = ModbusSerialClient(self.port, baudrate=self.baudrate)
+                return self._modbus.connect()
+            except Exception as e:
+                log.error("modbus.connect_failed error=%s", e)
+                return False
+        return False
+
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        if self.mode == "raw":
+            return self._observe_raw()
+        return self._observe_modbus(channels)
+
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        if command == "reconnect":
+            await self.disconnect()
+            return {"reconnected": await self.connect()}
+
+        if self.mode == "raw":
+            return self._act_raw(command, args)
+        return self._act_modbus(command, args)
+
+    def shield_rules(self) -> list[ShieldRule]:
+        return [ShieldRule("rate", ShieldType.LIMIT, 10)]
+
+    async def disconnect(self) -> None:
+        if self._serial and self._serial.is_open:
+            self._serial.close()
+        if self._modbus:
+            self._modbus.close()
+
+    def _observe_raw(self) -> dict[str, Any]:
+        if not self._serial or not self._serial.is_open:
+            return {"buffer": "", "error": "not connected"}
+        waiting = self._serial.in_waiting
+        data = self._serial.read(min(waiting, 4096)) if waiting else b""
+        return {"buffer": data.hex() if data else "", "bytes_waiting": waiting}
+
+    def _observe_modbus(self, channels: list[str] | None) -> dict[str, Any]:
+        if not self._modbus:
+            return {"error": "not connected"}
+        state: dict[str, Any] = {}
+        targets = channels or list(self.registers.keys())
+        for name in targets:
+            reg = self.registers.get(name)
+            if not reg:
+                continue
+            try:
+                addr = reg["address"]
+                count = reg.get("count", 1)
+                fc = reg.get("function", "holding")
+                if fc == "holding":
+                    result = self._modbus.read_holding_registers(addr, count, slave=self.unit_id)
+                elif fc == "input":
+                    result = self._modbus.read_input_registers(addr, count, slave=self.unit_id)
+                elif fc == "coil":
+                    result = self._modbus.read_coils(addr, count, slave=self.unit_id)
+                else:
+                    continue
+
+                if hasattr(result, "registers"):
+                    raw = result.registers
+                    scale = reg.get("scale", 1.0)
+                    if count == 1:
+                        state[name] = raw[0] * scale
+                    elif reg.get("type") == "float" and count == 2:
+                        state[name] = struct.unpack(">f", struct.pack(">HH", *raw))[0]
+                    else:
+                        state[name] = [v * scale for v in raw]
+                elif hasattr(result, "bits"):
+                    state[name] = result.bits[:count]
+            except Exception as e:
+                state[name] = f"error: {e}"
+        return state
+
+    def _act_raw(self, command: str, args: dict[str, Any]) -> Any:
+        if not self._serial or not self._serial.is_open:
+            return {"error": "not connected"}
+        if command == "write":
+            data = bytes.fromhex(args.get("data", ""))
+            self._serial.write(data)
+            return {"written": len(data)}
+        if command == "query":
+            data = bytes.fromhex(args.get("data", ""))
+            self._serial.write(data)
+            timeout = float(args.get("timeout", 1.0))
+            self._serial.timeout = timeout
+            response = self._serial.read(4096)
+            return {"response": response.hex(), "length": len(response)}
+        return {"error": f"unknown command: {command}"}
+
+    def _act_modbus(self, command: str, args: dict[str, Any]) -> Any:
+        if not self._modbus:
+            return {"error": "not connected"}
+        for name, reg in self.registers.items():
+            if command == f"write_{name}" and reg.get("writable"):
+                value = args.get("value")
+                addr = reg["address"]
+                try:
+                    if reg.get("type") == "float":
+                        packed = struct.pack(">f", float(value))
+                        regs = struct.unpack(">HH", packed)
+                        self._modbus.write_registers(addr, list(regs), slave=self.unit_id)
+                    elif reg.get("function") == "coil":
+                        self._modbus.write_coil(addr, bool(value), slave=self.unit_id)
+                    else:
+                        self._modbus.write_register(addr, int(float(value)), slave=self.unit_id)
+                    return {"written": name, "value": value}
+                except Exception as e:
+                    return {"error": str(e)}
+        return {"error": f"unknown command: {command}"}

halyn/drivers/socket_raw.py

@@ -0,0 +1,153 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Raw socket meta-driver — TCP and UDP.
+
+Covers: custom protocols, proprietary hardware, game servers,
+legacy systems, network testing, raw telemetry streams.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket
+import time
+from typing import Any
+
+from nrp import (
+    NRPDriver, NRPManifest, NRPId,
+    ChannelSpec, ActionSpec, ShieldSpec, ShieldRule, ShieldType,
+)
+
+log = logging.getLogger("halyn.drivers.socket_raw")
+
+
+class SocketDriver(NRPDriver):
+    """
+    Raw TCP/UDP socket driver.
+
+    Maintains a persistent connection (TCP) or stateless
+    send/recv (UDP). Data is exchanged as hex-encoded bytes.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        protocol: str = "tcp",
+        buffer_size: int = 4096,
+        timeout: float = 5.0,
+    ) -> None:
+        super().__init__()
+        self.host = host
+        self.port = port
+        self.protocol = protocol.lower()
+        self.buffer_size = buffer_size
+        self.timeout = timeout
+        self._socket: socket.socket | None = None
+        self._rx_bytes = 0
+        self._tx_bytes = 0
+        self._connected_at = 0.0
+
+    def manifest(self) -> NRPManifest:
+        return NRPManifest(
+            nrp_id=self._nrp_id or NRPId.create(
+                "local", "socket", f"{self.host}-{self.port}".replace(".", "-")
+            ),
+            manufacturer="Socket",
+            model=f"{self.protocol.upper()} {self.host}:{self.port}",
+            observe=[
+                ChannelSpec("connected", "bool"),
+                ChannelSpec("rx_bytes", "int"),
+                ChannelSpec("tx_bytes", "int"),
+                ChannelSpec("uptime", "float", unit="seconds"),
+                ChannelSpec("buffer", "string", description="Last received data (hex)"),
+            ],
+            act=[
+                ActionSpec("send", {"data": "string — hex-encoded bytes"}, "Send raw bytes"),
+                ActionSpec("query", {"data": "string", "timeout": "float"}, "Send and receive"),
+                ActionSpec("reconnect", {}, "Reset connection"),
+            ],
+            shield=[ShieldSpec("max_send", "limit", 65535, "bytes")],
+        )
+
+    async def connect(self) -> bool:
+        try:
+            sock_type = socket.SOCK_STREAM if self.protocol == "tcp" else socket.SOCK_DGRAM
+            self._socket = socket.socket(socket.AF_INET, sock_type)
+            self._socket.settimeout(self.timeout)
+            if self.protocol == "tcp":
+                self._socket.connect((self.host, self.port))
+            self._connected_at = time.time()
+            return True
+        except Exception as e:
+            log.error("socket.connect_failed %s:%d error=%s", self.host, self.port, e)
+            return False
+
+    async def observe(self, channels: list[str] | None = None) -> dict[str, Any]:
+        connected = self._socket is not None
+        state: dict[str, Any] = {
+            "connected": connected,
+            "rx_bytes": self._rx_bytes,
+            "tx_bytes": self._tx_bytes,
+            "uptime": time.time() - self._connected_at if self._connected_at else 0,
+        }
+        if connected and self.protocol == "tcp":
+            try:
+                self._socket.setblocking(False)
+                data = self._socket.recv(self.buffer_size)
+                state["buffer"] = data.hex()
+                self._rx_bytes += len(data)
+            except (BlockingIOError, socket.error):
+                state["buffer"] = ""
+            finally:
+                self._socket.setblocking(True)
+                self._socket.settimeout(self.timeout)
+        return state
+
+    async def act(self, command: str, args: dict[str, Any]) -> Any:
+        if command == "reconnect":
+            await self.disconnect()
+            return {"reconnected": await self.connect()}
+
+        if not self._socket:
+            return {"error": "not connected"}
+
+        if command == "send":
+            data = bytes.fromhex(args.get("data", ""))
+            if self.protocol == "tcp":
+                self._socket.sendall(data)
+            else:
+                self._socket.sendto(data, (self.host, self.port))
+            self._tx_bytes += len(data)
+            return {"sent": len(data)}
+
+        if command == "query":
+            data = bytes.fromhex(args.get("data", ""))
+            timeout = float(args.get("timeout", self.timeout))
+            if self.protocol == "tcp":
+                self._socket.sendall(data)
+            else:
+                self._socket.sendto(data, (self.host, self.port))
+            self._tx_bytes += len(data)
+            self._socket.settimeout(timeout)
+            try:
+                resp = self._socket.recv(self.buffer_size)
+                self._rx_bytes += len(resp)
+                return {"response": resp.hex(), "length": len(resp)}
+            except socket.timeout:
+                return {"response": "", "timeout": True}
+
+        return {"error": f"unknown: {command}"}
+
+    def shield_rules(self) -> list[ShieldRule]:
+        return [ShieldRule("max_send", ShieldType.LIMIT, 65535)]
+
+    async def disconnect(self) -> None:
+        if self._socket:
+            try:
+                self._socket.close()
+            except Exception:
+                pass
+            self._socket = None