epics-bridge 1.0.0__py3-none-any.whl

epics_bridge/__init__.py

@@ -0,0 +1,5 @@
+from .base_pv_interface import BasePVInterface
+from .daemon import BridgeDaemon
+from .daemon_status import TaskStatus
+
+__all__ = ["BridgeDaemon", "BasePVInterface", "TaskStatus"]

epics_bridge/base_pv_interface.py

@@ -0,0 +1,83 @@
+from dataclasses import dataclass, field, fields
+from typing import Dict
+
+
+@dataclass
+class BasePVInterface:
+    """
+    A base configuration class for EPICS PV interfaces.
+
+    This class handles the dynamic construction of PV names based on provided
+    prefixes. It supports inheritance, allowing users to define sets of PVs
+    (templates) and instantiate them with specific device prefixes.
+
+    Attributes:
+        prefixes (Dict[str, str]):
+        A dictionary of prefixes used to format the PV templates.
+        Example: {'sys': 'VAC:01:', 'main': 'PUMP:A:'}
+    """
+
+    # 1. Configuration: Holds the prefixes used for formatting
+    prefixes: Dict[str, str] = field(default_factory=dict)
+
+    # 2. Default PV Templates (Note: These use the '{main}' key)
+    trigger: str = "{main}Trigger"
+    heartbeat: str = "{main}Heartbeat"
+    busy: str = "{main}Busy"
+    task_status: str = "{main}TaskStatus"
+    task_duration: str = "{main}TaskDuration"
+
+    def __post_init__(self):
+        """
+        Post-initialization hook.
+        Iterates through all string fields in the instance. If a field contains
+        Python format placeholders (e.g., "{sys}Name"), it formats the string
+        using the provided `prefixes` dictionary.
+        """
+        missing_keys = []
+
+        for f in fields(self):
+            # Skip internal configuration fields
+            if f.name == "prefixes":
+                continue
+
+            # Get the raw value (the template, e.g., "{sys}Trigger")
+            raw_template = getattr(self, f.name)
+
+            # Only process strings that look like templates
+            if isinstance(raw_template, str) and "{" in raw_template:
+                try:
+                    # FIX: Changed 'self.context' to 'self.prefixes'
+                    formatted_pv = raw_template.format(**self.prefixes)
+                    setattr(self, f.name, formatted_pv)
+                except KeyError as e:
+                    # Collect errors to show them all at once
+                    missing_keys.append(f"Field '{f.name}' requires prefix key {e}")
+
+        if missing_keys:
+            raise ValueError(
+                "Configuration Error: Missing prefixes for PV templates.\n"
+                + "\n".join(missing_keys)
+            )
+
+    @property
+    def as_dict(self) -> Dict[str, str]:
+        """Returns a dictionary of PVs, excluding the internal 'prefixes'."""
+        # vars(self) is faster than asdict(self)
+        # We use .copy() to ensure we don't modify the actual object
+        data = vars(self).copy()
+
+        # Remove the configuration field so you only get PVs
+        if "prefixes" in data:
+            del data["prefixes"]
+
+        return data
+
+    @property
+    def pv_to_attr(self) -> Dict[str, str]:
+        """
+        Returns a reverse mapping: {Formatted_PV_Name: Attribute_Name}.
+        Example: {'VAC:01:Trigger': 'trigger'}
+        """
+        # Invert the dictionary: value becomes key, key becomes value
+        return {v: k for k, v in self.as_dict.items()}

epics_bridge/daemon.py

@@ -0,0 +1,323 @@
+import logging
+import os
+import threading
+import time
+from abc import ABC, abstractmethod
+from typing import Tuple
+
+from p4p.client.thread import Context
+
+from .base_pv_interface import BasePVInterface
+from .daemon_status import TaskStatus
+from .io import BridgeIO
+from .utils import Timer
+
+logger = logging.getLogger(__name__)
+
+
+class BridgeDaemon(ABC):
+    """
+    Base class for an EPICS Bridge Daemon with High-Availability features.
+
+    Architecture:
+        1. **Main Loop (Control):** Runs on the main thread using the 'main_context'.
+           It executes the synchronous control cycle:
+           Trigger -> Read -> Logic -> Write -> Ack.
+        2. **Heartbeat Loop (Monitor):** Runs on a separate daemon thread with a
+           PRIVATE 'hb_context'. This ensures the heartbeat never stalls, even if
+           the Main Loop is blocked by heavy network traffic.
+
+    Safety Features:
+        - **Zombie Protection:** The Heartbeat thread acts as a watchdog. It monitors
+          the Main Loop's activity timestamp. If the Main Loop hangs (e.g., infinite
+          loop or deadlocked IO), the Heartbeat STOPS pulsing to alert external
+          supervisors.
+        - **Suicide Pact:** If the Main Loop encounters persistent IO failures
+          (defined by `max_stuck_cycles`), it voluntarily exits the process to
+          allow a system-level restart (Docker/systemd).
+
+    Attributes:
+        cfg (BridgeConfig): Configuration object.
+        io (BridgeIO): The synchronous IO handler for the Main Loop.
+    """
+
+    def __init__(self, interface: BasePVInterface):
+        self.interface = interface
+
+        # 1. Main IO (Control Logic)
+        # We assume BridgeIO is the synchronous version (max_workers=1 or blocking)
+        self.io = BridgeIO()
+
+        # 2. State & Concurrency
+        self._running = False
+        self._last_main_loop_activity = 0.0  # Timestamp for Zombie Protection
+
+        # 3. Safety Thresholds
+        self.max_stall_limit = 10.0  # Time considered normal for the task
+        self.max_stuck_cycles = 15  # Approx 15 * poll_interval seconds
+        self._stuck_counter = 0
+
+    # =========================================================================
+    # Overridable Hooks
+    # =========================================================================
+
+    def get_poll_rate(self) -> float:
+        """
+        [Overridable] Controls the polling rate of the Main Loop.
+        Defaults to 1 Hz
+        Can be overridden in child classes
+        """
+        return 1.0
+
+    def trigger(self) -> bool:
+        """
+        [Overridable] Checks if the control cycle should run.
+
+        Default Implementation:
+            Reads the trigger PV.
+            Raises RuntimeError if the read operation fails (triggering stuck counter).
+
+        Returns:
+            bool: True to start `run_task()`, False to sleep.
+        """
+
+        return self.io.pvget(self.interface.trigger, timeout=1.0)
+
+    @abstractmethod
+    def run_task(self) -> TaskStatus:
+        """
+        [Required Override] Core business logic.
+
+        Args:
+            inputs: Dictionary of current values from Input PVs.
+
+        Returns:
+            Dict[str, Any]: Values to write to Output PVs.
+            None: If no output is required for this cycle.
+        """
+        pass
+
+    def reset_cycle(self):
+        """
+        [Overridable] Resets the handshake/trigger PVs at end of cycle.
+        Retries 3 times. If all fail, raises RuntimeError.
+
+        Returns:
+            bool: True if the reset write was successful.
+
+        Raises:
+            RuntimeError: If the write fails after 3 attempts.
+        """
+        payload = {self.interface.busy: False, self.interface.trigger: False}
+
+        for attempt in range(1, 4):
+            if self.io.pvput(payload, timeout=2.0):
+                return
+            logger.warning("Reset cycle failed (Attempt %d/3). Retrying...", attempt)
+            time.sleep(0.5)  # Brief pause to let network/IOC recover
+
+        logger.error("Critical: Failed to reset cycle after 3 attempts.")
+        raise RuntimeError("Failed to reset cycle PVs (Busy/Trigger) after 3 attempts.")
+
+    # =========================================================================
+    # Lifecycle Management
+    # =========================================================================
+
+    def start(self) -> None:
+        """Starts the Heartbeat thread and enters the blocking Main Loop."""
+        self._running = True
+        self._last_main_loop_activity = time.time()  # Prime the watchdog
+
+        # Start the Isolated Heartbeat Thread (Daemon)
+        # Daemon=True ensures it dies instantly if the main process crashes.
+        hb_thread = threading.Thread(
+            target=self._heartbeat_worker, daemon=True, name="Bridge_Heartbeat_Isolated"
+        )
+        hb_thread.start()
+
+        # Block main thread on the Control Loop
+        self._main_loop()
+
+    def stop(self) -> None:
+        """Signals loops to stop."""
+        logger.info("Stopping Daemon...")
+        self._running = False
+        exit(0)
+
+    # =========================================================================
+    # Main Control Loop (Thread 1)
+    # =========================================================================
+
+    def _main_loop(self) -> None:
+        """
+        The Master Control Loop.
+        Orchestrates the cycle: Health -> Attempt -> Report -> Sleep.
+        """
+        logger.info("Main loop started.")
+
+        try:
+            while self._running:
+                # 1. Health Check (Watchdogs & Suicide Pacts)
+                self._last_main_loop_activity = time.time()
+
+                # 2. Attempt Cycle (Trigger -> Execute -> Catch Errors)
+                status, duration = self._attempt_cycle()
+
+                # 3. Report Status (Best Effort)
+                self._update_telemetry(status, duration)
+
+                # 4. Pace the loop
+                time.sleep(self.get_poll_rate())
+
+        except Exception as e:
+            # Fatal Error Boundary: Catches infrastructure crashes
+            logger.critical(f"Fatal error in main loop: {e}", exc_info=True)
+        finally:
+            self.stop()
+
+    def _attempt_cycle(self) -> Tuple[object, float]:
+        # 1. Initialize duration safety
+        duration = 0.0
+
+        try:
+            if not self.trigger():
+                return None, None
+
+            with Timer() as t:
+                status = self._execute_cycle()
+
+            # Happy path duration
+            duration = t.duration
+            return status, duration
+
+        except Exception as e:
+            logger.error("Cycle failed: %s", e, exc_info=True)
+            # 2. Now safe to return 'duration' (either 0.0 or t.duration if t exists)
+            if "t" in locals():
+                duration = t.duration
+            return TaskStatus.EXCEPTION, duration
+
+    def _execute_cycle(self) -> TaskStatus:
+        """
+        The Action Sequence.
+        Uses try...finally to GUARANTEE cleanup.
+        """
+        # 1. Set Busy Flag
+        if not self.io.pvput({self.interface.busy: True}):
+            raise IOError("Failed to set Busy flag at start of cycle.")
+
+        try:
+            # 2. Run User Logic
+            return self.run_task()
+        finally:
+            # 3. Cleanup (Always runs, even on error)
+            self.reset_cycle()
+
+    def _update_telemetry(self, status: object, duration: float) -> None:
+        """Writes status and duration to the I/O interface (Best Effort)."""
+
+        if status is None or duration is None:
+            return
+
+        self.io.pvput(
+            {self.interface.task_status: status, self.interface.task_duration: duration}
+        )
+
+    # =========================================================================
+    # Isolated Heartbeat (Thread 2)
+    # =========================================================================
+
+    def _heartbeat_worker(self) -> None:
+        """
+        Executes the background Heartbeat and Watchdog logic.
+
+        This method runs on a separate daemon thread (`Bridge_Heartbeat_Isolated`).
+        It serves two critical roles:
+
+        1. **Liveness Monitor (External):** Toggles a 'heartbeat' PV (0/1) to let
+           external monitoring tools (like the IOC or Alarm Handler) know the
+           bridge is connected and processing data.
+
+        2. **Watchdog Terminator (Internal):** Monitors the `_last_main_loop_activity`
+           timestamp.
+           If the Main Thread gets stuck (deadlock, infinite loop, blocking IO),
+           this thread detects the stall and forcibly terminates the process to allow
+           supervisors (systemd/Docker) to restart it.
+        """
+        logger.info("Starting Isolated Heartbeat Worker...")
+
+        # Toggle state for the heartbeat (flips between 0 and 1)
+        pulse_val = 0
+
+        with Context("pva") as ctx:
+            while self._running:
+                is_active = self._is_main_loop_active()
+
+                if is_active:
+                    pulse_val = 1 - pulse_val  # Toggle value
+
+                    success = self._send_pulse(ctx, pulse_val)
+
+                    if success:
+                        self._stuck_counter = 0  # Reset fault counter on success
+                    else:
+                        # Main loop is fine, but Network/EPICS layer is failing
+                        self._stuck_counter += 1
+
+                else:
+                    # The Main Loop has not updated its timestamp within 'stall_limit'.
+                    # We stop pulsing to alert external monitors.
+                    self._stuck_counter += 1
+
+                    logger.warning(
+                        "Heartbeat Paused: Main Loop Stalled. Faults: %d/%d",
+                        self._stuck_counter,
+                        self.max_stuck_cycles,
+                    )
+
+                # If the Main Thread has been stuck for too long, we must take action.
+                # Since the Main Thread is stuck, it cannot exit itself.
+                if self._stuck_counter >= self.max_stuck_cycles:
+                    self._kill_process()
+
+                # Pace the heartbeat (1 Hz)
+                time.sleep(1.0)
+
+        logger.info("Heartbeat Worker stopped cleanly.")
+
+    # =========================================================================
+    # Helper Methods (Private)
+    # =========================================================================
+
+    def _is_main_loop_active(self) -> bool:
+        """Calculates if the main loop has updated its timestamp recently."""
+        # Dynamic tolerance based on current poll rate
+        stall_limit = max(self.get_poll_rate() * 4, self.max_stall_limit)
+        time_since_activity = time.time() - self._last_main_loop_activity
+
+        return time_since_activity < stall_limit
+
+    def _send_pulse(self, context: Context, value: int) -> bool:
+        """Attempts to write the heartbeat PV. Returns True if successful."""
+        try:
+            context.put(self.interface.heartbeat, value, wait=True, timeout=1.0)
+            return True
+        except Exception as e:
+            logger.warning("Heartbeat IO Error: %s", e)
+            return False
+
+    def _kill_process(self) -> None:
+        """
+        CRITICAL: Use os._exit(), not sys.exit()
+        sys.exit() only raises an exception in THIS thread (the heartbeat thread).
+        os._exit() tells the OS to immediately destroy the entire process.
+        This bypasses 'finally' blocks and cleanup handlers, which is
+        necessary because the Main Thread is likely deadlocked.
+        """
+        logger.critical(
+            "Watchdog Triggered: Main Loop stuck for %d cycles. "
+            "initiating HARD KILL via os._exit(1).",
+            self._stuck_counter,
+        )
+
+        os._exit(1)

epics_bridge/daemon_status.py

@@ -0,0 +1,13 @@
+from enum import IntEnum
+
+
+class TaskStatus(IntEnum):
+    """
+    Simple status tracking for task completion.
+    Maps to an EPICS mbbi record.
+    """
+
+    SUCCESS = 0  # ZRST="Success",    ZRSV=NO_ALARM
+    LOGIC_FAILURE = 1  # ONST="Task Fail",  ONSV=MINOR (Business logic said no)
+    IO_FAILURE = 2  # TWST="IO Fail",    ONSV=MINOR (Network/IO operation failed)
+    EXCEPTION = 3  # THST="Code Crash", ONSV=MAJOR (Python traceback occurred)

epics_bridge/io.py

@@ -0,0 +1,130 @@
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+from p4p.client.thread import Context, Value
+
+from .utils import unwrap_p4p_structure
+
+logger = logging.getLogger(__name__)
+
+
+class BridgeIO:
+    """
+    Handles synchronous Input/Output operations for Process Variables (PVs) via p4p.
+
+    This class serves as the abstraction layer between the logical pv_names used in
+    the application (e.g., 'motor_position') and the actual EPICS PV strings
+    (e.g., 'IOC:SYS:MOTOR:POS').
+
+    Design Philosophy:
+        - **Synchronous Execution:** All methods block until the operation completes
+          or times out. This ensures the caller has absolute control over flow.
+        - **Fail-Safe:** Errors (disconnects, timeouts) are caught and logged,
+          returning safe fallback values (None/False) rather than crashing the thread.
+
+    Attributes:
+        cfg (BridgeConfig): Configuration object containing PV definitions.
+        ctx (Context): The active p4p client context.
+        pv_map (Dict[str, str]): A unified lookup map of {logical_name: full_pv_name}.
+    """
+
+    def __init__(self):
+        self.ctx = Context("pva")
+
+    def pvget(
+        self, pv_names: Union[str, List[str]], timeout: float = 5.0, raw: bool = False
+    ) -> Union[Any, Dict[str, Optional[Any]]]:
+        """
+        Reads PVs synchronously. Supports both single-value and batch reads.
+
+        Args:
+            pv_names: A single logical name (str) OR a list of pv_names (List[str]).
+            timeout: Maximum seconds to wait for the network response.
+
+
+        Returns:
+            - If 'pv_names' is a str:
+            Returns the single value (or None on failure).
+            - If 'pv_names' is a list:
+            Returns {name: value} dict. None values indicate failure.
+        """
+        # 1. Normalize Input
+        is_single_value = isinstance(pv_names, str)
+        if is_single_value:
+            pv_names_list = [pv_names]
+        else:
+            pv_names_list = pv_names
+
+        if not pv_names_list:
+            return None if is_single_value else {}
+
+        # 2. Execute Read
+        try:
+            # throw=False returns Exception objects in the list for specific failures
+            values: List[Union[Value, Exception]] = self.ctx.get(
+                pv_names_list, throw=False, timeout=timeout
+            )
+        except Exception as e:
+            # Catastrophic failure (Context down, etc.)
+            logger.error("Batch read failure: %s", e)
+            return None if is_single_value else {n: None for n in pv_names_list}
+
+        if not raw:
+            values = self._convert_epics_to_python_types(values)
+
+        # 4. Return (Polymorphic)
+        if is_single_value:
+            return values[0]
+
+        return dict(zip(pv_names_list, values))
+
+    def pvput(self, data: Dict[str, Any], timeout: float = 5.0) -> bool:
+        """
+        Writes to a batch of PVs synchronously.
+
+        Blocks until the server confirms the write.
+        This guarantees that when this function returns True,
+        the value has reached the IOC.
+
+        Args:
+            data: A dictionary of {logical_name: value_to_write}.
+            timeout: Maximum seconds to wait for write confirmation.
+
+        Returns:
+            True: If the write was successful and acknowledged.
+            False: If the write timed out or failed (e.g., PV not writable).
+        """
+        if not data:
+            return False
+
+        pvs = []
+        vals = []
+        for k, v in data.items():
+            pvs.append(k)
+            vals.append(v)
+
+        try:
+            # Block here. wait=True ensures we wait for the server's handshake.
+            self.ctx.put(pvs, vals, wait=True, timeout=timeout)
+            return True
+
+        except TimeoutError:
+            # The server received the request but didn't Ack in time,
+            # or the network dropped the packet.
+            logger.error("IO Timeout: Write operation stuck for >%.1fs.", timeout)
+            return False
+
+        except Exception as e:
+            # Catches disconnection errors, permission denied, or type mismatches.
+            logger.error("IO Error during write: %s", e)
+            return False
+
+    def _convert_epics_to_python_types(self, raw_values):
+        processed_values = []
+        for raw_val in raw_values:
+            if isinstance(raw_val, Exception):
+                processed_values.append(None)
+            else:
+                processed_values.append(unwrap_p4p_structure(raw_val))
+
+        return processed_values

epics_bridge/utils.py

@@ -0,0 +1,39 @@
+import logging
+import time
+from typing import Any
+
+from p4p.nt.enum import ntenum
+from p4p.nt.ndarray import ntndarray
+from p4p.nt.scalar import ntbool, ntfloat, ntint, ntnumericarray, ntstr, ntstringarray
+
+logger = logging.getLogger(__name__)
+
+
+class Timer:
+    def __enter__(self):
+        self.start = time.perf_counter()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.end = time.perf_counter()
+        self.duration = self.end - self.start
+
+
+def unwrap_p4p_structure(res: Any) -> Any:
+    """
+    Unwraps P4P structures to get clean Python types.
+    """
+    raw_data = res.raw
+    raw_dict = raw_data.todict()
+    # logger.debug("Unwrapping object type: %s", type(res))
+    if isinstance(res, (ntbool, ntint, ntfloat, ntnumericarray, ntstr, ntstringarray)):
+        val = raw_dict["value"]
+    elif isinstance(res, ntenum):
+        val = raw_dict["value"]["index"]
+    elif isinstance(res, ntndarray):
+        val = raw_dict["value"]
+    else:
+        val = None
+
+    # logger.debug("Extracted %s from %s", val, raw_dict)
+    return val

epics_bridge-1.0.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: epics-bridge
+Version: 1.0.0
+Summary: A generic bridge between EPICS IOCs and Python logic.
+Author-email: Hugo Valim <hugo.valim@ess.eu>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: p4p
+
+# EPICS Bridge
+
+![Coverage](resources/coverage.svg)
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**EPICS Bridge** is a high-availability Python framework designed for implementing a robust EPICS-Python interface. It provides a structured environment for bridging external control logic with the EPICS control system, emphasizing synchronous execution, fault tolerance, and strict process monitoring.
+
+This library addresses the common reliability challenges like preventing silent stalls ("zombie processes") and handling network IO failures deterministically.
+
+
+## System Architecture
+
+The core of `epics-bridge` relies on a **Twin-Thread Architecture** that decouples the control logic from the monitoring signal.
+
+### 1. Synchronous Control Loop (Main Thread)
+The primary thread executes the user-defined logic in a strict, synchronous cycle:
+1.  **Trigger:** Waits for an input event or timer.
+2.  **Run Task:** Executes user-defined task
+3.  **Acknowledge:** Updates the task status and completes the handshake.
+
+### 2. Isolated Heartbeat Monitor (Daemon Thread)
+A separate, isolated thread acts as an internal watchdog. It monitors the activity timestamp of the Main Thread.
+* **Operational:** Pulses the `Heartbeat` PV as long as the Main Thread is active.
+* **Stalled (Zombie Protection):** If the Main Thread hangs (e.g., infinite loop, deadlocked IO) for longer than the defined tolerance, the Heartbeat thread ceases pulsing immediately. This alerts external watchdogs (e.g., the IOC or alarm handler) that the process is unresponsive.
+
+### 3. Automatic Recovery ("Suicide Pact")
+To support containerized environments (Docker, Kubernetes) or systemd supervisors, the daemon implements a fail-fast mechanism. If network connectivity is lost or IO errors persist beyond a configurable threshold (`max_stuck_cycles`), the process voluntarily terminates (`exit(0)`). This allows the external supervisor to perform a clean restart of the service.
+
+
+### 4. Logger
+Output important messages in the daemon shell to a configured log file.
+
+
+
+## Installation
+
+```bash
+# Install the package
+pip install .
+
+# Install test dependencies
+pip install -r requirements-test.txt
+```
+
+
+
+
+## Project Structure
+
+- **epics_bridge.daemon**
+  Main control loop, heartbeat logic, and failure handling
+
+- **epics_bridge.io**
+  Synchronous P4P client wrapper with strict error handling
+
+- **epics_bridge.base_pv_interface**
+  PV template definitions and prefix validation
+
+- **epics_bridge.utils**
+  Utilities for converting P4P data into native Python types
+
+
+---
+## Quick Start
+### 1. EPICS Interface
+There should be a standard epics db to handle the basic functionalities of the daemon and any amount of specialized dbs to fulfill the intended functionality.
+
+The standard db should always be loaded by the IOC that interfaces with the daemon.
+These are its contents:
+
+```epics
+record(bo, "$(P)Trigger") {
+    field(DESC, "Start Task")
+    field(ZNAM, "Idle")
+    field(ONAM, "Run")
+}
+
+record(bi, "$(P)Busy") {
+    field(DESC, "Task Running Status")
+    field(ZNAM, "Idle")
+    field(ONAM, "Busy")
+}
+
+record(bi, "$(P)Heartbeat") {
+    field(DESC, "Daemon Heartbeat")
+}
+
+record(mbbi, "$(P)TaskStatus") {
+    field(DESC, "Last Cycle Result")
+    field(DTYP, "Raw Soft Channel")
+
+    # State 0: Success (Green)
+    field(ZRVL, "0")
+    field(ZRST, "Success")
+    field(ZRSV, "NO_ALARM")
+
+    # State 1: Logic Failure (Yellow - e.g. Interlock)
+    field(ONVL, "1")
+    field(ONST, "Task Fail")
+    field(ONSV, "MINOR")
+
+    # State 2: EPICS IO Failure (Yellow - e.g. PV Read/Write Error)
+    field(TWVL, "2")
+    field(TWST, "IO Failure")
+    field(TWSV, "MINOR")
+
+    # State 3: Exception (Red - Software/Hardware Crash)
+    field(THVL, "3")
+    field(THST, "Code Crash")
+    field(THSV, "MAJOR")
+}
+
+record(ai, "$(P)TaskDuration") {
+    field(DESC, "Task duration")
+    field(PREC, "2")
+    field(EGU,  "s")
+}
+```
+
+
+### 2. Define a Python PV Interface
+
+Use a dataclass to define EPICS PV templates.
+Standard PVs (trigger, busy, heartbeat, task_status) are provided automatically.
+
+```python
+from dataclasses import dataclass
+from epics_bridge.base_pv_interface import BasePVInterface
+
+@dataclass
+class MotorInterface(BasePVInterface):
+    position_rbv: str = "{main}Pos:RBV"
+    velocity_sp: str  = "{main}Vel:SP"
+    temperature: str  = "{sys}Temp:Mon"
+
+```
+
+### 3. Implement Control Logic
+
+Subclass BridgeDaemon and implement the synchronous execute() method.
+
+```python
+from epics_bridge.daemon import BridgeDaemon, TaskStatus
+
+class MotorControlDaemon(BridgeDaemon):
+    def run_task(self, inputs=None) -> TaskStatus:
+        velocity = self.io.pvget(self.interface.velocity_sp)
+
+        if velocity is None:
+            return TaskStatus.ERROR
+
+        new_position = velocity * 0.5
+
+        self.io.pvput({
+            self.interface.position_rbv: new_position
+        })
+
+        return TaskStatus.DONE
+```
+
+### 4. Run the Daemon
+
+```python
+
+def main():
+
+    prefixes = {
+        "main": "IOC:MOTOR:01:",
+        "sys": "IOC:SYS:"
+    }
+
+    interface = MotorInterface(prefixes=prefixes)
+
+    daemon = MotorControlDaemon(
+        interface=interface,
+    )
+
+    daemon.start()
+
+if __name__ == "__main__":
+    main()
+```

epics_bridge-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+epics_bridge/__init__.py,sha256=nOU5u5m8LjRkq_eH69p2OY7OYZF-FBoJyZC7dBO-MVg,179
+epics_bridge/base_pv_interface.py,sha256=7Q_r2y7ChuFmPKw500CODXnjE2iF7kVbj50VEeLASjg,3022
+epics_bridge/daemon.py,sha256=DZfI0Ayhr7m4Rvjyd3g0PVKVC8FhGsH7Yf49ySiDaAo,11802
+epics_bridge/daemon_status.py,sha256=Q9BiV96eHPSo82xovOOm5wJlgCa2bSyyc2Ivna58NCA,446
+epics_bridge/io.py,sha256=QOyALzdwM_Yf2JAn1x-M7g_RUcoLZ9fRPGKnei3383s,4550
+epics_bridge/utils.py,sha256=kdHqm-EwTK3M0TcFXS-nJrOl6fJgn0u139E1OCs3Knk,1085
+epics_bridge-1.0.0.dist-info/METADATA,sha256=lVrwj8YzEejqcSeD9tUgwqruTtm3phpPS2M1KG-krcE,5552
+epics_bridge-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+epics_bridge-1.0.0.dist-info/top_level.txt,sha256=Ps28BHqERpyKVNk5Bhk-KVFobpGQNQJ-Q7fqFYc9rvo,13
+epics_bridge-1.0.0.dist-info/RECORD,,

epics_bridge-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

epics_bridge-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+epics_bridge