Use the Connectors Without the Framework#

osprey-connectors installs on its own, without the agent, the web terminal or a built deployment. A script, a notebook or a service of your own can read a control system and its archiver through the same connectors OSPREY uses, and gets their error taxonomy and their write safety with them.

pip install osprey-connectors

This page covers reading. A connector built in a script refuses every write before anything is sent; When a write is refused says why and where writing is decided.

Every script and output on this page is a file the test suite runs, so what is shown is what the package does.

Read channels#

A connector is built from a configuration dict by its type name. The dict has the shape of a deployment’s control_system: section:

read_channels.py#
"""Read channels from an EPICS control system, with no OSPREY deployment."""

import asyncio

from osprey_connectors.factory import ConnectorFactory, register_builtin_connectors

CONFIG = {
    "type": "epics",
    "connector": {
        "epics": {
            "gateways": {"read_only": {"address": "cagw.facility.edu", "port": 5064}},
            "timeout_s": 5.0,
        }
    },
}


async def main() -> None:
    register_builtin_connectors()  # registers the built-in type names; idempotent
    connector = await ConnectorFactory.create_control_system_connector(CONFIG)
    try:
        reading = await connector.read_channel("DEMO:READBACK")
        print(reading.value, reading.metadata.units)

        values = await connector.read_multiple_channels(["DEMO:SETPOINT", "DEMO:MODE"])
        for address, channel in values.items():
            print(address, channel.value, channel.metadata.enum_label)
    finally:
        await connector.disconnect()


if __name__ == "__main__":
    asyncio.run(main())

Against an IOC serving those three records, it prints:

1.5 A
DEMO:SETPOINT 1.5 None
DEMO:MODE 1 STANDBY

create_control_system_connector connects before it returns. A state channel reads as its integer index, with the state’s name in metadata.enum_label. read_multiple_channels leaves out a channel that failed to read rather than raising, so check the keys of what it returns.

Every connector answers the same methods. To read a DOOCS or Tango control system, change type and its connector block; Use Connectors has the block for each, and the client library the DOOCS and Tango connectors need, which this package does not install.

Read history#

An archiver connector is built the same way, from the shape of a deployment’s archiver: section, and returns history as a pandas DataFrame:

read_history.py#
"""Read archived history from the EPICS Archiver Appliance, with no OSPREY deployment."""

import asyncio
from datetime import UTC, datetime, timedelta

from osprey_connectors.factory import ConnectorFactory, register_builtin_connectors

ARCHIVER = {
    "type": "epics_archiver",
    "settings": {"url": "https://archiver.facility.edu:8443", "timeout_s": 30},
}


async def main() -> None:
    register_builtin_connectors()
    archiver = await ConnectorFactory.create_archiver_connector(ARCHIVER)
    try:
        end = datetime.now(UTC)
        frame = await archiver.get_data(
            channels=["DEMO:READBACK", "DEMO:SETPOINT"],
            start_date=end - timedelta(hours=1),
            end_date=end,
        )
        print(frame)
    finally:
        await archiver.disconnect()


if __name__ == "__main__":
    asyncio.run(main())

The frame is long: one row per sample, with timestamp (UTC), channel and value columns:

                  timestamp        channel  value
0 2026-11-04 23:33:24+00:00  DEMO:READBACK    1.5
1 2026-11-04 23:34:24+00:00  DEMO:READBACK    1.6
2 2026-11-04 23:35:24+00:00  DEMO:READBACK    1.7
3 2026-11-04 23:33:24+00:00  DEMO:SETPOINT    1.5
4 2026-11-04 23:34:24+00:00  DEMO:SETPOINT    1.6
5 2026-11-04 23:35:24+00:00  DEMO:SETPOINT    1.7

get_data also takes precision_ms, a bin width, and processing, how each bin is reduced; the archiver section of Connector Contracts says what each mode returns.

Read the channel directory#

A ChannelFinder directory is built from a BackendSpec by create_service, which reads the kind from the spec; settings is the connection block. Building it sends nothing:

read_directory.py#
"""Search a ChannelFinder directory and read one channel's record, with no OSPREY deployment."""

import asyncio

from osprey_connectors.directory import DirectoryQuery, DirectoryRecord
from osprey_connectors.factory import ConnectorFactory
from osprey_connectors.service_answers import BackendSpec

DIRECTORY = {"url": "https://channelfinder.facility.edu:8443/ChannelFinder", "timeout_s": 10}

#: Seconds each call may spend.
DEADLINE_S = 10.0


async def main() -> None:
    spec = BackendSpec(
        kind="directory", type="channelfinder", target="live", settings=DIRECTORY, rehearsal=False
    )
    directory = await ConnectorFactory.create_service(spec)

    page = await directory.search(DirectoryQuery(words="SR:BPM*"), DEADLINE_S)
    print(f"{page.outcome}: {len(page.rows)} of {page.total}")
    for row in page.rows:
        print(f"  {row.name:<10} {row.channel_type:<3} {row.server:<7} {row.description}")

    record = await directory.describe("SR:BPM1:X", DEADLINE_S)
    if isinstance(record, DirectoryRecord):
        print(f"{record.row.name}: {record.row.status} on {record.row.host}")
    else:
        print(record)  # Outcome.NOT_LISTED, or Unavailable(reason=...)


if __name__ == "__main__":
    asyncio.run(main())

Against a directory listing those three BPM channels, it prints:

found: 3 of 3
  SR:BPM1:X  ai  sr-bpm  BPM 1 horizontal position
  SR:BPM1:Y  ai  sr-bpm  BPM 1 vertical position
  SR:BPM2:X  ai  sr-bpm  BPM 2 horizontal position
SR:BPM1:X: Active on sr-bpm.facility.edu

Every answer is a value, never an exception: a search returns a page whose outcome says how it ended, and describe returns the record, Outcome.NOT_LISTED, or Unavailable with the reason.

What needs a deployment#

Three things on the connector side are a deployment’s, and a script without one does without them:

The simulator

virtual_accelerator and mock_archiver serve the simulated machine of a built facility, and refuse to connect without the simulator view osprey build writes. Every other connector talks to a real system.

config.yml

A few facts are deployment-wide and read from config.yml rather than from the dict a connector is built from: the facility’s timezone, the write tier and the channel limits. A script that has none reads them at their defaults and logs a warning that it fell back to UTC. To set the timezone, name a config.yml in CONFIG_FILE that states system.timezone:

config.yml#
system:
  timezone: America/Los_Angeles

With CONFIG_FILE unset, the file is the one OSPREY_CONFIG names, else build/config.yml under the working directory, else config.yml in it. A process started in a built project directory therefore reads that project’s config with nothing set. The same file answers create_control_system_connector() and create_archiver_connector() called with no dict, which build the connector its control_system: or archiver: section selects. Without a config they raise FileNotFoundError, naming where they looked.

Writes

Every write passes the verdict in Who May Write: the write tier, the machine the connector writes to, the login it writes for, and that login’s switch for that machine, the first refusal winning. A connector built in a script names no machine and has no switch to read, so every write is refused before anything is sent.

When a write is refused#

The refusal is the package’s ordinary one. write_channel() returns a result whose outcome is refused; write_channel_checked raises ChannelWriteBlockedError, whose message ends with the reason. Built from the same CONFIG as above:

write_refused.py#
async def main() -> None:
    register_builtin_connectors()
    connector = await ConnectorFactory.create_control_system_connector(CONFIG)
    try:
        await connector.write_channel_checked("DEMO:SETPOINT", 2.0)
    except ChannelWriteBlockedError as refused:
        print(refused.reason)
        print(refused)
    finally:
        await connector.disconnect()

prints

WRITES_DISABLED
Write to 'DEMO:SETPOINT' blocked: Writes are refused because this login's write tier does not allow them; ask the deployment admin.
[osprey-refusal: tier_never]

tier_never is the answer with no config.yml; with the tier armed in one, the next term answers target_unknown. Writing is decided by a deployment, so a program that has to write runs in one and is let write by a person: from the switch, or, for a program with nobody at a prompt, through a bounded write authorization.

See also

osprey-connectors API

Every public name of the package.

Use Connectors

The configuration block of every connector.

Connector Contracts

What every connector must do: large values, write confirmation, who may write, and the archiver contract.