Connector Contracts#
Every connector – the ones that ship with OSPREY and any you register yourself – has to behave the same way at its edges, because the agent, the plans and the safety layers on top of it are written against that behaviour rather than against any one control system. This page states those contracts: how large array values are returned, how a write reports whether it actually took effect and which gates it must pass first, where a connector makes its client put, and what an archiver’s historical data has to look like. For the day-to-day task of picking and configuring a connector, see Use Connectors.
Reading Large Values#
Array-valued channels – camera frames, waveforms, orbit vectors – are often
far too big to hand to the agent as raw numbers. channel_read applies a size
rule to every read, whatever protocol answered it: values within an element
budget come back inline as JSON lists, and anything larger is saved to the
artifact gallery and reported as a summary plus a handle to it.
control_system:
read_inline_max_elements: 2000 # per-value element budget
Only arrays are measured – strings and single scalars are always inline. One
channel_read call also has an aggregate budget of four times
read_inline_max_elements, spent in request order. Every withheld value
names which limit it hit as artifact_reason: per_value_threshold (the
value alone is over budget; it will never come back inline) or
aggregate_budget (earlier channels in the same request spent the call’s
budget; a smaller batch returns it inline).
The summary that replaces the value reports shape, dtype and element count,
plus min/max/mean for numeric data, along with the artifact’s id and its
data_file path – the authoritative copy of the values. 1-D arrays are
saved as JSON with an interactive chart in the gallery (x axis is sample
index); 2-D and 3-D data with a color axis get an auto-scaled PNG preview
beside a raw .npy; shapes with no honest rendering are saved as .npy
alone. The agent reaches the numbers by loading data_file inside
execute (numpy.load / json.load). If the artifact store cannot
write, the read still reports success with artifact_error in place of the
handle – the machine did answer.
OSPREY never deletes a reading; keep or delete them in the gallery.
Addresses Outside the Facility#
A connector that holds the facility’s whole address set – the simulator served in process, and the mock archiver – knows when an address is not one of its channels, and says so:
A read of such an address raises
ChannelNotFoundError, whose message is<address> is not a channel of this facility.A write to such an address is not raised: it comes back with outcome
refusedandrefusal_reasonCHANNEL_NOT_FOUND. In a batch it is one refused row, and no write of that batch is sent.
The controls tools report both as error type not_found, naming the address
under details.channel. A read that names several channels still succeeds
for the ones that answered and names the unknown address under missing
(see Partial Answers); a batch write reports the unknown address as its
refused row beside the rows it held back (BATCH_REFUSED).
A Channel Access connector cannot tell an unknown name from an unreachable one
– a search that finds nothing times out – so it reports
ChannelUnreachableError for both.
Connection Failures#
A connector separates a failure about one channel from the loss of the connector itself, and the supervisor that owns the connector’s lifetime acts on the difference:
ChannelUnreachableError– one channel could not be reached, or did not answer in time. It names the channel underchannel_addressand is noConnectionError: the connector keeps serving every other channel, and nothing is restarted. The controls tools report it as error typechannel_unreachable, naming the channel underdetails.channel. The error also states whether the active target’s gateway answered when the channel failed, underdetails.target_reachability:stateisreached,down, orunmeasuredwhen no gateway could be probed.ConnectorUnavailableError– the connector’s own transport is gone: its context, its service or its connector-host child. It is aConnectionError. Its supervisor replaces the connector once per instance or child, however many calls saw it fail, and attaches what it did as the error’srecovery. A bareConnectionErrorfrom a connector that does not say which is treated the same way.
A child that misses a call’s deadline is pinged: one that answers is kept, one
that does not is replaced. The controls tools report a lost connector as
connection_error and a missed deadline as timeout_error, with the
supervisor’s records under details.recovery (see Partial Answers).
A call that finds the connector-host child already dead is refused, the
refusal names the fresh child the supervisor started on the same target, and
the next call is served by it.
Every failure about one channel – an unreachable or unknown channel, a
refused, failed or limits-violating write – is a ChannelError whose
channel_address names the channel, in process or across the connector
host. The registry that carries failures across the host is derived from
osprey_connectors.errors: each public class there crosses as itself, and a
connector’s own subclass crosses as the nearest public class it extends.
Write Confirmation#
A write is confirmed when the channel it wrote now holds the value that was
sent. The connector establishes that itself: it re-reads the channel once the
control system has accepted the put, and reports what it found as a single word
on ChannelWriteResult, which every
write_channel() call returns; write_multiple_channels() returns one per
operation. The program in Writing from a program reads it after a
batch, with WriteOutcome imported
from osprey_connectors.control_system:
for result in results:
if result.outcome is WriteOutcome.CONFIRMED:
print(result.channel_address, "now holds", result.value_written)
else:
print(result.channel_address, result.outcome.value, result.verdict_reason)
Every write ends in exactly one of six outcomes:
Outcome |
What it means |
|---|---|
|
Nothing was written. A gate stopped the write before it left OSPREY –
write posture, a limit, a channel marked not writable, an address that
is not a channel of the facility – and |
|
The value was sent and the control system did not take it. |
|
The re-read holds the value that was sent. |
|
The re-read holds a different value. A setpoint the machine clamped or rounded is reported here, not smoothed over. |
|
The value was sent, but not acknowledged in time or the re-read itself failed, so what the channel holds is unknown. |
|
Confirmation is switched off for this channel; nothing was checked. |
Beside the outcome, the result carries observed_value (what the re-read
returned), alarm_status and alarm_severity (the channel’s alarm state,
which is reported with the write and is never itself a reason to fail one), and
notes – a short display line such as observed 2.4, sent 2.5 that is
there to be shown, not parsed.
In Python, anything short of a confirmation raises.
osprey.runtime.write_channel raises ChannelWriteBlockedError on
refused and ChannelWriteFailedError on failed, mismatch and
unconfirmed; the mismatch message names both the value sent and the value
observed. The channel_write MCP tool reports the outcome for every channel
instead of raising, so the agent can describe a batch in which some channels
took the value and others did not. A call where no value reached any channel is
refused, with the same rows under details.results (see
Partial Answers).
Switching confirmation off#
confirm is a per-channel boolean in the limits database, sitting beside
writable, which every entry states:
{
"SHUTTER:OPEN_CMD": {
"writable": true,
"confirm": false
}
}
A channel’s own entry decides; an entry that does not state confirm, or a
channel with no entry, has confirmation on. The database holds no defaults
block: a top-level defaults key, or an entry without writable, fails the
load. Switch it off for the channels a re-read cannot answer
for – a command channel that resets itself, a register that cannot be read back
– so those writes report unrequested rather than unconfirmed. A call
site may pass confirm=True or confirm=False to decide for one call;
passing nothing means “no opinion” and leaves the choice to the configuration.
write_multiple_channels() confirms each channel exactly as a single write
would, which is why osprey.runtime.write_channels behaves like
osprey.runtime.write_channel.
What a batch means#
write_multiple_channels() checks every write before it sends any, on every
connector. The promise covers refusals known before the send:
The checks are all-or-nothing. Every write passes what a single write passes before its put: the write verdict, the connector’s own refusals and the limits,
max_stepincluded (the stepped channels are read together, once). If one write is refused, no write of the batch is sent. Every row isrefused: a refused write with its own reason, each other write withBATCH_REFUSED, whose message names a refused one.Past the checks each write is sent and verified on its own. A write that fails, mismatches or stays unconfirmed does not recall the others, which may already hold their values. The batch succeeded only if every row is
confirmedorunrequested.A refusal given only at the send is a row, not a recall. A control system that refuses at the put (a connector with no precheck, a value the target coerces, a read-only channel) can do so after earlier writes of the batch went out. Each row says what happened to its own channel.
A batch names a channel once; one that names a channel more than once is
refused whole (VALIDATION_ERROR on the repeated writes). The write verdict
is asked again right before the send: a switch turned off, a hold or a stop
that arrived during the checks refuses every write not yet sent.
A batch does not raise ChannelLimitsViolationError; a limits refusal is a
refused row with reason LIMITS. The EPICS connector sends the puts of a
batch together; the other connectors send them in the order given.
A caller that must not proceed on a batch passes its results to
raise_for_write_results(), which raises for a refused write before the
writes its batch held back.
How values are compared#
One rule decides every outcome, on every connector, and there is nothing to
configure. Two numbers agree when they are within a relative 1e-6 of each other
– enough to absorb the rounding of a float on its way through a control system,
not enough to hide a clamped setpoint. A string written to an enum channel is
compared against the label the connector resolved for the reading, since the
channel itself reads back an index. A single-element array compares as the value
it holds, because control systems disagree about whether such a channel reads
back boxed. A scalar never matches a longer vector, and two vectors must be the
same length and agree element by element. Everything else compares for equality.
If the comparison cannot be made at all, the outcome is mismatch: a write is
confirmed only when the values are known to agree.
Who May Write#
Three facts decide a write. This section is the contract every other page points to.
The tier key is the furthest position a login may put its switch at:
control_system:
writes: asked # never | asked | allowed; silence is never
It is spelled in tiers/*.yml and, for the root or single-user render, in
the deployment root; a shared login is always never. A tier
overrides the root. Only asked and allowed arm; any other value, and no
key at all, reads never. The tier is a ceiling, not a selection: an armed
tier may write to every machine the deployment configures, and the switch picks
which and how. Connector blocks carry transport facts only. On a never
render the build denies the write tools outright, so they are refused before
any per-call check.
The switch is one login’s, per machine, set from the control-target chip to off (writes refused, the default), asked (every governed write prompts a person) or allowed (governed writes run unprompted). It is read on every write, so a move reaches a session already running. Moving it to off is never refused. A position past the tier acts as the tier, and arms again when the tier is restored.
The governed set is the tools the position decides for: channel_write,
write-mode execute and execute_file, pyaml_measure, queue_add,
queue_start, and every declared facility write tool wired to both the
writes check and the approval hook. approval.* keys have no say over them;
every other tool keeps its approval.tools.<tool> policy.
The verdict combines them. One total order of terms; the first that refuses names the reason:
# |
Reason |
Refused when |
|---|---|---|
1 |
|
the run is read-only. |
2 |
|
the render’s tier is |
3 |
|
the session has an unanswered hold (Watchdog Contract). A write
about to execute meets this term through |
4 |
|
the machine does not resolve in this deployment. |
5 |
|
no login can be named for the write; a scheduled or triggered job runs for no login; or the owner is not the login this process acts for. |
6 |
|
in a shared container, the owner is missing from the login→tier map,
or mapped |
7 |
|
the owner’s switch record cannot be read. An absent record is not
unavailable: it is every switch at |
8 |
|
the owner’s switch is at |
9 |
|
the run was started with writes held off for this machine. |
Two reasons come from outside the verdict: the EPICS connector refuses
switching while its write gateway has not yet followed the switch, and the
chip refuses a widening with stopped_since when a stop landed after it
began. The package’s verdict, the connector and the stdlib hook twin share the
order above, so a write is refused for the same reason on every side.
Refusal reasons and their trailer. Every refusal a write path returns ends with a trailer line naming the reason, so a reader recovers it without parsing the words:
Writes are off; turn it on from the chip in the web terminal.
[osprey-refusal: switch_off]
The phrase says what stopped the write and who can lift it. It never names a
config key, a file, an environment variable or a build command: its reader is
an operator or the agent. The reasons and phrases are one importable table,
osprey_connectors.refusals.
The connector applies per-write mechanical safety — the verdict, limits validation, the fail-closed validation path — on every put. That is a separate layer from the per-intent human authorization at the tool boundary (the approval hook, the launch token for plans), which gates the intent once rather than every put. Neither substitutes for the other. See Safety Chain for the order the layers run in.
Upgrading from a deployment-wide write flag#
Earlier releases armed writes per connector type, with
control_system.writes_enabled and
control_system.connector.<type>.writes_enabled. Those keys are retired.
Run
osprey init --revalidate. It rewrites every layer to the tier key in place.Until you do, each retired key builds with one warning naming the new key. A layer with a literal
truein its flat or any per-type key readswrites: allowed— for every machine, not only the type it named; any other value readsnever. A shared login always readsnever. A file that spells both the retired and the new key is refused. The retired keys are refused in the next stable release.A render built before this release is not reread with the old rule: at run time it has no tier key and reads
neveruntil it is rebuilt.Every machine starts at off. After the rebuild, nothing writes until a login moves a machine’s switch from the chip. A scheduled dispatch job or a queue item with no owner no longer writes at all.
A shell on a write tier is refused at build. On an armed render, a
claude_code.permissions.remove_denythat liftsBashorMonitorfails the build: a shell reaches the switch and the connectors around every gate. On aneverrender it stays a warning.Two countdowns, warn now, refused in the next stable release. A facility tool that a server lists under
permissions.ask, or whose name carries a destructive marker, and that is missing from that server’smcp_servers.<server>.writeslist, is a build warning.control_system.write_toolsstill gates its entries per call, now on the real machine’s switch, and warns; move them tomcp_servers.<server>.writes.Shared containers read a login→tier map. The Bluesky queue and dispatch workers carry every login’s job, so the build renders
control_system.login_tiers({login: never | asked | allowed}) into their config from the roster. A write there needs the container’s tier, the owner’s mapped tier and the owner’s switch; an owner the map does not name is refusedowner_unknown. Nothing at run time writes the map: rebuild after a roster change.
The write door#
In a readwrite executor run, a client library’s put entry points refuse a put
that no connector is making (What a readwrite run refuses). A notebook
kernel refuses to load a client library at all
(what a cell may load), so the door opens
only in the processes that hold a connector. A connector marks its own put by
holding the write door open around it. The base class does that for every
connector: it wraps write_channel and write_multiple_channels — the
latter is what write_channels reaches — and, after the verdict has
allowed the write, opens the door around the original method. A refused write
never opens it.
The door is a context variable
(osprey_connectors.control_system.write_door), so it reaches only code
that shares the context that opened it. That makes one rule for a connector’s
implementation:
Make the client put in the calling context, inside
asyncio.to_thread, or in a coroutine handed to another loop withasyncio.run_coroutine_threadsafe. Each runs the put in a copy of the calling context, and a task created while the door is open inherits it too. The EPICS connector uses the last: its Channel Access puts run on the process’s single Channel Access loop.Not behind
loop.run_in_executor, a raw executorsubmitor a barethreading.Thread. Each starts from a fresh context, sees the door closed, and the put is refused with reasonRAW_CLIENT_WRITE.
A put made from a client-library callback thread the library started itself — libca’s own callback threads, for one — carries no door either, and is refused the same way.
The door records who is making a put; it does not decide whether the put is
allowed. The connector’s own gates below do that. One path holds the door
open for code that is not a shipped connector’s own put, and is accepted as a
cooperative bypass: a connector subclass written by the user is wrapped
like a shipped one, so its write_channel puts inside the open door.
osprey_connectors imports nothing from osprey for this. The door
module is standard-library only, because the guard that reads it runs in
executor subprocesses and kernels where osprey may not be importable.
Limits Checking#
control_system:
limits_checking:
enabled: true # Enable limits validation
mode: exclusive # Only channels in the database can be written
connector:
virtual_accelerator:
limits_checking: # This connector type's own posture,
enabled: true # replacing the pair above for it alone
mode: optional
When enabled, every write_channel() call is validated against the limits
database before the write reaches hardware. The database format is the
per-channel configuration above.
Limits are optional, and mode chooses between two ways of using the
database:
mode: exclusive— only channels in the database can be written. A channel with no record is refused.mode: optional— channels in the database are held to their limits, and every other channel is written with no limits.
enabled: false means no limits at all.
The posture is per connector type. control_system.limits_checking is what a
type inherits when it says nothing about itself, and
control_system.connector.<type>.limits_checking answers for that type
instead — so one deployment can run exclusive on its live machine and
optional on a simulator. Three rules govern the per-type
block:
It replaces, it does not merge. A per-type block must state both
enabledandmode; neither is inherited. A block stating one alone is refused byosprey buildandosprey validate, naming the missing setting — and a half-written block that reaches a running deployment anyway, by a hand-editedconfig.ymlor an older render, blocks every write until it is completed.The database stays deployment-wide.
database_pathis not a per-type setting: the deployment mounts one limits file, and every target is checked against it. A profile that states it is refused byosprey build,osprey validateandosprey facility validate:osprey buildwritesdata/channel_limits.jsonfromdata/facility/limits.yamland setscontrol_system.limits_checking.database_pathto it in the rendered config.Only explicit values decide.
modeisexclusive,optional, or unstated. With limits checking enabled, amodethat no key states refuses a channel with no record — permission needs an explicitoptional. Any other value, and any leaf the block does not define, is refused byosprey buildandosprey validate. A deployment that states no limits posture at all runs no limits checking, and nothing on that path refuses a channel with no record.
max_step is the one limit that costs a read. It caps how far a single write
may move a channel, which means measuring the channel’s present value first —
over the client the write is about to go through, not some other one. The
connector performing the write supplies that read from its own client, so
max_step works on every control system rather than only over Channel
Access. A connector with no synchronous read refuses a max_step channel
rather than guessing: a step that cannot be measured cannot be approved. The
layers above the connector — the channel_write tool and the limits hook —
hold no client, so they apply every other limit and leave this one to the
connector, which makes it on the write itself.
That read is bounded: control_system.connector.<type>.step_read_timeout_s
(default 2.0 seconds) is how long it waits, beside the connector’s own
timeout_s and for the same reason — a gateway two hops away answers more
slowly than an IOC on the deploy host. The bound is fail-closed: a channel that
does not answer inside it reads as “could not be measured”, which refuses the
write. Raising it buys a slow channel room, never a weaker check. The python
executor’s sandbox applies the same number, so a script’s step check and the
connector’s wait the same length of time for the same channel.
A refusal about a channel with no record names the key that answered, the
per-type one where a block spoke and the deployment-wide one where none did, so
an operator edits the line that decides rather than one it overrides. The
channel_limits tool reports mode for the target the deployment is on,
including null where nothing states one, alongside mode_key naming the
key it read.
See also
ChannelValueChannel read result data model
ChannelWriteResultComplete write operation result
WriteOutcomeThe six words a write can end in
Archiver Connectors#
An archiver connector answers the same questions about the past that a control-system connector answers about the present.
Changed in version Unreleased: get_data returns long-format data (below) instead of a shared-index wide
DataFrame. Out-of-tree connectors written against the old contract must be updated.
Subclass ArchiverConnector and implement
connect, disconnect, get_data, get_metadata, check_availability.
get_metadata’s is_archived and the values check_availability answers
are None when the archiver cannot say; check_availability raises
RuntimeError while the archiver is not connected. store_extent() is optional: it
answers an ArchiveExtent (the channels the store records now, its oldest and
newest sample); the default answers every part unknown, with a reason.
get_data is the entire contract. It returns a long-format pandas.DataFrame
with exactly three columns, sorted by channel then timestamp:
Column |
Dtype |
Contents |
|---|---|---|
|
|
When the sample – or, under a |
|
|
The channel/PV name the row belongs to. |
|
not dtype-constrained |
|
An empty result is an empty frame with these same three columns.
Nothing is manufactured. Each channel contributes only its own real
samples – never forward-filled, never reindexed onto a shared grid, never
padded with a row nothing was recorded at. A channel with no data in the range
contributes no rows; it never appears as an all-NaN column. If a custom
connector finds itself building a shared DatetimeIndex and reindexing
per-channel series onto it, that is the bug.
Per-channel aggregation. get_data takes processing: str = "raw" –
one of raw, mean, min, max, median, std, count –
applied independently to each channel’s own samples:
rawdecimates eachprecision_msbin to its last real sample, keeping that sample’s own true timestamp (the Archiver Appliance’slastSample_Nsemantics).Every other mode aggregates the real samples in each bin. A bin with no samples is dropped, not emitted as
NaN.precision_ms <= 0means full resolution, valid only withprocessing="raw"– anything else must raiseValueError.Aggregating a non-numeric channel with anything but
rawmust raiseValueErrornaming the channel – never coerce, drop, or emitNaN.A bin width your backend cannot express must raise
ValueError, never round to one it can (the Archiver Appliance connector rejects a positiveprecision_msthat is not a multiple of 1000).Bins are anchored on
start_date: one request cuts one lattice, the same for every channel in it and every processing mode. A backend that bins on a grid of its own is the documented exception – the Archiver Appliance’s operators are epoch-anchored, and the window merely clips them.
The dtype rule for value. Enum/status channels carry string
values, and get_data never coerces them: a channel’s own dtype flows
through, and only mixing non-numeric with numeric channels in one query promotes
the shared value column. Forcing value to float64 “for consistency”
silently corrupts every enum/status channel. (This is deliberately not the live-read
contract, where an enum reads as its index with the label in enum_label –
an archiver reports what its backend recorded, and these backends recorded the
string.)
Query windows must be normalized to UTC before touching the wire: a naive
start_date/end_date is facility-local and must be converted – not
relabeled – to your backend’s UTC wire format.