Skip to content

Connections - #459

Draft
tomkane-dls wants to merge 10 commits into
mainfrom
connections
Draft

tomkane-dls wants to merge 10 commits into
mainfrom
connections

Conversation

@tomkane-dls

@tomkane-dls tomkane-dls commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Closes #458

...


Eiger example

eiger/
  connections.py
  controllers.py
  __main__.py
fastcs.yaml

connections.py

import asyncio
import json
from dataclasses import dataclass
from typing import Any

from fastcs.connections import (
    Connection,
    ConnectionSpec,
    HTTPConnection,
    Introspection,
    disconnect_on,
)


@dataclass
class EigerIntrospection:
    # {"count_time": {"value": 0.5, "value_type": "float", "access_mode": "rw"}, ...}
    parameters: dict[str, dict[str, Any]]


class EigerConnection(HTTPConnection[EigerIntrospection]):
    # HTTPConnection already gives connect(), close(), and get()/put() with
    # @disconnect_on, and reconnects 60 times, 5 seconds apart

    async def introspect(self) -> Introspection[EigerIntrospection]:
        return Introspection(EigerIntrospection(await self.get("/config")))


@dataclass
class OdinIntrospection:
    parameters: dict[str, dict[str, Any]]
    meta_writer_ip: str
    meta_writer_port: int


class OdinConnection(HTTPConnection[OdinIntrospection]):
    # Opened after the detector, and waits for it to be up before reconnecting
    depends_on = EigerConnection

    async def introspect(self) -> Introspection[OdinIntrospection]:
        tree = await self.get("/config")
        meta_writer = tree.pop("meta_writer")
        info = OdinIntrospection(tree, meta_writer["ip"], meta_writer["port"])

        # Renamed "odin_meta" by the runner, after this connection's name
        meta = ConnectionSpec(
            "meta", MetaWriterConnection, ip=info.meta_writer_ip, port=info.meta_writer_port
        )
        return Introspection(info, subconnections=[meta])


class MetaWriterConnection(Connection):
    """A line-based JSON protocol over TCP"""

    reconnect_attempts = 20
    reconnect_period = 1.0

    def __init__(self, ip: str, port: int) -> None:
        self.ip = ip
        self.port = port

    async def connect(self) -> None:
        self._reader, self._writer = await asyncio.open_connection(self.ip, self.port)

    async def close(self) -> None:
        self._writer.close()
        await self._writer.wait_closed()

    @disconnect_on(TimeoutError)
    async def request(self, command: str, **params: Any) -> dict[str, Any]:
        self._writer.write(json.dumps({"command": command, **params}).encode() + b"\n")
        await self._writer.drain()
        reply = await asyncio.wait_for(self._reader.readline(), timeout=2.0)
        if not reply:
            raise ConnectionResetError("The meta writer closed the link")

        return json.loads(reply)

controllers.py

from typing import Any

from fastcs.attributes import Attribute, AttrR, AttrRW, Polled
from fastcs.connections import HTTPConnection
from fastcs.controllers import Controller

from eiger.connections import EigerConnection, MetaWriterConnection, OdinConnection

_DATATYPES: dict[str, type] = {"float": float, "int": int, "string": str, "bool": bool}


def _attribute(connection: HTTPConnection, path: str, parameter: dict[str, Any]) -> Attribute:
    """An attribute for one parameter of a device that describes itself"""
    datatype = _DATATYPES[parameter["value_type"]]
    # Metadata is passed as keyword arguments, e.g. units="s" for a number
    meta = {"units": parameter["units"]} if "units" in parameter else {}

    async def get() -> Any:
        return (await connection.get(path))["value"]

    if parameter["access_mode"] == "rw":

        async def put(value: Any) -> None:
            await connection.put(path, json={"value": value})

        # Read once at startup and after each reconnect, then on every set
        return AttrRW(datatype, getter=get, setter=put, **meta)

    # Status the device changes by itself
    return AttrR(datatype, getter=Polled(get, period=0.2), **meta)


class EigerController(Controller):
    """The top-level controller, whose arguments are the connections"""

    def __init__(
        self,
        eiger: EigerConnection,
        odin: OdinConnection,
        odin_meta: MetaWriterConnection | None = None,
    ) -> None:
        super().__init__()
        self.DET = EigerDetController(eiger)
        self.ODIN = OdinController(odin, odin_meta)


class EigerDetController(Controller):
    def __init__(self, connection: EigerConnection) -> None:
        super().__init__()
        self.connection = connection
        for name, parameter in connection.introspection.parameters.items():
            self.add_attribute(name, _attribute(connection, f"/config/{name}", parameter))


class OdinController(Controller):
    def __init__(
        self, connection: OdinConnection, meta: MetaWriterConnection | None
    ) -> None:
        super().__init__()
        self.connection = connection
        for name, parameter in connection.introspection.parameters.items():
            self.add_attribute(name, _attribute(connection, f"/config/{name}", parameter))

        # Not stored here: each controller holds at most one connection
        if meta is not None:
            self.META = MetaWriterController(meta)


class MetaWriterController(Controller):
    def __init__(self, connection: MetaWriterConnection) -> None:
        super().__init__()
        self.connection = connection
        self.writing = AttrR(bool, getter=Polled(self._get_writing, period=0.5))
        self.frames_written = AttrR(
            int,
            getter=Polled(self._get_frames_written, period=0.5),
            description="Frames written to the current file",
        )
        self.file_path = AttrRW(
            str, getter=self._get_file_path, setter=self._set_file_path, length=256
        )

    async def _get_writing(self) -> bool:
        return (await self.connection.request("status"))["writing"]

    async def _get_frames_written(self) -> int:
        return (await self.connection.request("status"))["frames_written"]

    async def _get_file_path(self) -> str:
        return (await self.connection.request("status"))["file_path"]

    async def _set_file_path(self, value: str) -> None:
        await self.connection.request("configure", file_path=value)

__main__.py

from fastcs.launch import launch

from eiger.controllers import EigerController

launch(EigerController)

fastcs.yaml

controllers:
  - id: EIGER
    type: eiger.EigerController
    connections:
      eiger:
        url: http://10.0.0.1/detector/api/1.8.0
      odin:
        url: http://10.0.0.2:8888/api/0.1
        reconnect_attempts: 10
        reconnect_period: 2.0
      # odin_meta is discovered from odin. Give it here to set it by hand instead:
      # odin_meta:
      #   ip: 10.0.0.3
      #   port: 5659
transport:
  - epicsca: {}

Without fastcs.yaml

The same thing built in Python. A ControllerSpec takes connection instances, named by their argument. odin_meta is left out, so it's discovered:

from fastcs.controllers import ControllerSpec
from fastcs.launch import FastCS
from fastcs.transports.epics.ca import EpicsCATransport

eiger = EigerConnection("http://10.0.0.1/detector/api/1.8.0")
odin = OdinConnection("http://10.0.0.2:8888/api/0.1").set_reconnect(
    attempts=10, period=2.0
)

FastCS(
    [ControllerSpec("EIGER", EigerController, eiger=eiger, odin=odin)],
    [EpicsCATransport()],
).run()

@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.84536% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.57%. Comparing base (1d884b3) to head (976ffb9).

Files with missing lines Patch % Lines
src/fastcs/runner.py 94.11% 5 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #459      +/-   ##
==========================================
+ Coverage   91.37%   91.57%   +0.19%     
==========================================
  Files          72       73       +1     
  Lines        2922     2931       +9     
==========================================
+ Hits         2670     2684      +14     
+ Misses        252      247       -5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Connections Rework

1 participant