EPICS Bridge

epics-bridge is a Python framework for synchronous, high-availability EPICS daemons over PVA. It provides the control-loop contract, watchdog/heartbeat behavior, logging PVs, and failure handling used by daemon projects built on top of it.

Start here

Build a new daemon

Use the cookiecutter scaffold:

• Canonical repo: https://gitlab.esss.lu.se/icshwi/pydaemon/cookiecutter-epics-bridge
• Generate a project:

cookiecutter git@gitlab.esss.lu.se:icshwi/pydaemon/cookiecutter-epics-bridge.git
cd <project_name>
conda env create -f environment.yml
conda activate <project_name>
pre-commit install
pytest -m "not slow" -v

The scaffold is the primary starting point for new daemon development. It creates a standalone Python package, IOC startup files, a test harness, and project-local docs.

Understand the framework

Use these docs when you need framework behavior, design constraints, or the reference example:

• User guide: docs/README.md
• Contributor workflow: CONTRIBUTING.md
• Reference example: examples/README.md

What this repo contains

• epics_bridge/: framework package
• tests/: framework and example verification
• examples/echo_daemon/: end-to-end reference daemon + IOC
• docs/README.md: canonical framework guide

Install and verify

For local framework work:

pip install -e .
pip install -r requirements-test.txt
pytest -m "not slow" -v

For IOC-backed integration work, use the provided conda environment:

conda env create -f environment.yml
conda activate epics-bridge
pip install -e .
pytest -m slow -v

For the full project verifier used in this repo, prefer running the entire suite through the environment directly:

mamba run -n epics-bridge pytest -q

environment.yml uses ess-conda-local and conda-forge. If you are outside ESS, you may need to adjust channel/package availability for the EPICS toolchain.

Architecture summary

epics-bridge uses two threads:

1. Main thread: synchronous control loop (trigger -> run_task -> reset -> telemetry)
2. Heartbeat thread: independent watchdog with its own PVA context

If the main loop stalls, the heartbeat stops pulsing. If I/O failures persist past the configured threshold, the daemon exits so an external supervisor can restart it.

For the full EPICS contract, TaskStatus semantics, PV model, and extension points, see docs/README.md.