Metadata-Version: 2.4
Name: epics-bridge
Version: 5.0.0
Summary: A generic bridge between EPICS IOCs and Python logic.
Author-email: Hugo Valim <hugo.valim@ess.eu>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.esss.lu.se/icshwi/pydaemon/epics-bridge
Project-URL: Repository, https://gitlab.esss.lu.se/icshwi/pydaemon/epics-bridge
Project-URL: Issues, https://gitlab.esss.lu.se/icshwi/pydaemon/epics-bridge/-/issues
Keywords: epics,p4p,control-system,daemon,ioc,process-variable
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: p4p
Dynamic: license-file

# EPICS Bridge
![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

`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:

```bash
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`](docs/README.md)
- Contributor workflow: [`CONTRIBUTING.md`](CONTRIBUTING.md)
- Reference example: [`examples/README.md`](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:

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

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

```bash
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:

```bash
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`](docs/README.md).
