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 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 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:
"""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_acceleratorandmock_archiverserve the simulated machine of a built facility, and refuse to connect without the simulator viewosprey buildwrites. Every other connector talks to a real system.config.ymlA few facts are deployment-wide and read from
config.ymlrather 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 aconfig.ymlinCONFIG_FILEthat statessystem.timezone:config.yml#system: timezone: America/Los_Angeles
With
CONFIG_FILEunset, the file is the oneOSPREY_CONFIGnames, elsebuild/config.ymlunder the working directory, elseconfig.ymlin it. A process started in a built project directory therefore reads that project’s config with nothing set. The same file answerscreate_control_system_connector()andcreate_archiver_connector()called with no dict, which build the connector itscontrol_system:orarchiver:section selects. Without a config they raiseFileNotFoundError, 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:
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.