CANOPY#
CANOPY shows the machine the way a control-room display does: screens with live readbacks, setpoints and buttons, plus Trace for archived history, a correlation plot and a waveform view. In an OSPREY deployment it is the Canopy panel in the web terminal’s sidebar, and the agent works in it with you: it opens the screen you ask for, arranges tabs, and builds new screens.
What You’ll Learn
How CANOPY fits into the web terminal, and where its screens come from
How to turn it on in a deployment
What a click on a screen may write, and what stops it
What the agent can and cannot do in the panel
How to upgrade CANOPY
Prerequisites: a deployment built with osprey build (see
Deploy a Facility). Sharing screens with everyone has its own
page, Share CANOPY Screens.
How it fits together#
Every user’s web terminal runs its own CANOPY. It reads and writes the machine through the terminal’s control session, the same one the agent and the notebooks use. So a screen shows the machine the control-target chip names, and a click on it is judged like any other write from that login: same tier, same write switch, same limits, same audit trail. CANOPY has no permissions of its own.
A screen comes from one of two places:
The library holds the deployment’s shared screens, in
data/canopy/libraryof the deployment repository. Everyone sees them, and nobody can change them from the panel. Share CANOPY Screens explains how a screen gets in.Your personal store holds the screens you or the agent built. It lives in your own agent data, survives rebuilds, and only you see it.
In a multi-user deployment, every login card has its own CANOPY. A shared card is one CANOPY for everyone who opens it: they share its screens and saved views, and its writes are audited under the card’s name.
Turn it on#
OSPREY does not build CANOPY. It takes a ready-made payload: a directory with CANOPY’s Python packages and web pages, built from the canopy repository.
Build the payload with the canopy repository’s
scripts/build-payload.sh(its--helplists the inputs). Build it at the commits this OSPREY release was tested against, which this command prints with everything else the build needs:python -m osprey.integrations.canopy --pins
A payload built at any other canopy or PyDMConverter commit stops the build. Build the payload from public sources walks through it from the public repositories.
Name the payload in the deployment’s
.env:OSPREY_CANOPY_PAYLOAD=/srv/canopy/payload
Add the panel to
profile.yml. A deployment made from thedemopreset already has it, and the web terminal opens on it at the example facility’sfacility/overview: skip this step. For any other profile, addcanopytoweb_panels, its three skills toskills, and the build step that copies the payload into the deployment:web_panels: - canopy skills: - canopy-panel-builder # build and check screens - canopy-operator # open and arrange what the panel shows - canopy-screens # which screen shows which device lifecycle: pre_build: - name: canopy-payload timeout: 30 run: '"{python}" -m osprey.integrations.canopy.stage'
Run
osprey buildandosprey up. The Canopy panel is in the sidebar.
If OSPREY_CANOPY_PAYLOAD is unset, the build leaves the panel and its
skills out and says so in one line. To leave the panel out of one tier, list
canopy under exclude.web_panels and the three skills under
exclude.skills (see Build Profiles).
Build the payload from public sources#
Every input is public on GitHub, in the als-apg/canopy-osprey-mirror-*
repositories:
canopy-osprey-mirror-canopy: CANOPY, and the builder,scripts/build-payload.sh.canopy-osprey-mirror-pydm-converter-tool: PyDMConverter.canopy-osprey-mirror-screen-runtime: the screen viewer.canopy-osprey-mirror-react-trace: Trace.canopy-osprey-mirror-sdk-js: the JavaScript SDK. Its release carries the packs the build installs.
A mirror’s default branch is not the pin. Build each repository at the
commit --pins names, never a branch head.
The build needs git, Node.js, pnpm 11.1.1 exactly (the version the
commits’ packageManager names; the builder refuses any other pnpm on
PATH), uv, python3 and curl.
Print the pins from an OSPREY clone. This runs with a bare
python3, before anything is installed:python3 src/osprey/integrations/canopy/proven.py --pins > pins pin() { sed -n "s/^$1=//p" pins; }
Each repository has a
<name>=<commit>and a<name>.mirror=<url>line.builderis the canopy commit whosebuild-payload.shruns (on branchbuilder.branch).SDK_PACKSandpnpmare the build’s settings.canopy.versionandPyDMConverter.versionare the versions the build is expected to give the two wheels.Clone the mirrors in full, with their tags: the builder refuses a shallow clone, and derives each wheel’s version from the tag reachable from its pin. The canopy clone is the builder: check out
builderthere, and the build takes the canopy pin from the same clone byCANOPY_SHA:for name in PyDMConverter canopy-screen-runtime react-trace canopy-sdk-js; do git clone "$(pin "$name.mirror")" "$name" done git clone "$(pin builder.mirror)" canopy git -C canopy checkout --detach "$(pin builder)"
Build. Every repository is built at the commit named here, whatever is checked out:
PYDM="$PWD/PyDMConverter" PYDM_SHA="$(pin PyDMConverter)" \ RT="$PWD/canopy-screen-runtime" RT_SHA="$(pin canopy-screen-runtime)" \ SDK="$PWD/canopy-sdk-js" SDK_SHA="$(pin canopy-sdk-js)" \ SDK_PACKS="$(pin SDK_PACKS)" \ TRACE="$PWD/react-trace" TRACE_REF="$(pin react-trace)" \ CANOPY_SHA="$(pin canopy)" \ bash canopy/scripts/build-payload.sh /srv/canopy/payload
SDK_PACKSis the SDK release URL; the builder fetches its packs and checks them against the release’sSHA512SUMS. Check the result:canopy_versionandpydm_versionin the payload’sSTAGED.jsonequalcanopy.versionandPyDMConverter.version. If the build reports that no tag is reachable from a pin, fetch the tags from that repository’s mirror (git -C <clone> fetch --tags) and build again.Set
OSPREY_CANOPY_PAYLOAD=/srv/canopy/payloadin the deployment’s.env.Install OSPREY from its clone editable, and build and start with
--dev, so the images carry that checkout rather than a PyPI release:pip install -e <osprey-clone> osprey build --dev osprey up --dev
A non-editable install of an unreleased checkout cannot be pinned, and
osprey buildstops with Cannot pin osprey-framework.
The demo preset seeds an archive on the first osprey up; size the
host for it (archive size).
The panel’s optional settings are flat keys under config:, for example the
screen CANOPY opens first and the channel Trace starts with:
config:
web.panels.canopy.home_screen: facility/overview
web.panels.canopy.trace_default_query: pv=SR:DIAG:BPM:03:POSITION:X&range=-1h
osprey build refuses a home_screen the library does not hold. Every key
is in the configuration reference.
Use the panel#
Open a screen from the panel’s sidebar or the command palette, or ask the agent (“open the RF overview”). Screens and tools open as tabs in CANOPY’s own tiles, which you drag and split much as you do the terminal’s (Tiles). The ☰ menu at the right end of the top-right tile’s bar resets the layout, saves the open tabs as a collection and reopens recently closed tabs.
Which machine. A badge names the machine the values come from. Switch the control target on the chip and CANOPY follows: the screens go blank for a moment and return with the new machine’s values. A click made on a screen that still showed the old machine is refused, never sent to the new one. If the terminal has no control target on record, CANOPY shows the deployment’s default machine, read-only. If it cannot reach the chosen machine, every channel shows disconnected and every write is refused.
History. Trace and the correlation plot read the archive of the machine you are on. If the deployment archives another machine, or none, they say No archiver. Live values and history never come from two different machines.
Saved views in Trace and the correlation plot are yours: they are kept in your agent data.
Write to the machine from a screen#
A button, slider or entry field on a screen writes as you. The chip’s write switch for the machine decides how:
off — the write is refused.
asked — a dialog asks you to confirm each write. A slider asks once, when you let go. Declining sends nothing.
allowed — the write is sent at once, without a dialog.
Your tier, the channel limits and the safety watchdogs apply as well. While a
watchdog has flagged one of the terminal’s agent sessions, the panel says
writes held with the reason and refuses every click, because the agent
arranges this panel and could have set up the click. When a write ends, a
short notice says whether the machine read back the value you sent, or why the
write was refused. Every write and every refusal is in the audit trail under
your name, with the surface canopy. A panel write on the safety chain page follows the
path step by step.
Warning
At allowed, take care with a screen the agent opened. The agent chose
the screen and its settings, so its write buttons address what the agent
chose, and they write without a dialog. Read what a button addresses before
you press it. The canopy-operator skill has the agent say which screen
it opened and how.
After the agent changes the panel, the write buttons in that window pause for 750 ms with a visible notice, so a tab that moves under your pointer cannot catch a click meant for something else.
What the agent can do in the panel#
The agent reaches your CANOPY and nobody else’s. Its CANOPY tools fall into three groups:
Look — read a screen, take a screenshot, read a channel, search channel names, check a screen for errors. No prompt.
Arrange — open, close, split and zoom tabs, open a collection, set Trace’s channels (
get_workspace,set_workspace). No prompt, because none of it touches the machine. What changed is highlighted, each batch is a row in the terminal’s activity log (⋯ More), and anything the agent closes comes back with the closed-tabs toast’s Undo or ☰ → Recently closed.Author — create, edit or delete a screen in your personal store, convert a legacy panel (
.bob,.opi,.edl,.ui), or ask for a screen to join the library (request_push). Each call asks you first.
The agent never writes a channel through CANOPY: its writes stay on OSPREY’s own write tools and their approval. Your own actions win: if you change the panel while an agent command is on its way, the command fails and the agent looks again. While a write dialog is open, the agent’s arranging waits for it to close.
Note
In this release the CANOPY payload carries no screen-format specification.
When the agent checks a screen, the result carries one warning,
spec_unavailable: the schema checks did not run, everything else did.
Read such a check as incomplete, not as a pass.
Size the host#
Each CANOPY takes about 270 MiB, and one runs for every login whose tier shows
the panel, whether or not the tab is open. The agent’s screenshot tool starts
a headless browser that adds up to 450 MiB while it is in use.
web.panels.canopy.vole_bytes_max caps the live-value buffers of one
CANOPY. For a wall display that many people watch, use one shared card: ten
users on one screen are ten sets of subscriptions on the control system.
Upgrade CANOPY#
A CANOPY upgrade is an OSPREY upgrade plus a new payload:
Upgrade OSPREY to a release tested against the new CANOPY, and read its pins with
python -m osprey.integrations.canopy --pins.Build a new payload at those commits and point
OSPREY_CANOPY_PAYLOADat it.Regenerate the library’s report with the new CANOPY and commit it, even if no screen changed (Regenerate the report).
Run
osprey buildandosprey up.
The rebuild restarts every terminal and ends open agent sessions, so announce it. Personal stores, saved views and pending push requests live in the users’ agent data and are kept.
To go back, keep the old payload directory: install the OSPREY release it was
built for, point OSPREY_CANOPY_PAYLOAD at it again, revert the report
commit of step 3, and rebuild.
See also
- Share CANOPY Screens
Add, review, remove and roll back shared screens.
- A panel write
How a click on a screen is checked on its way to the machine.
- The configuration reference
Every
web.panels.canopykey.