From da4a19d982e926030d0b244d58fe1bba5909e6a7 Mon Sep 17 00:00:00 2001 From: Benjamin Labrecque Date: Thu, 27 Aug 2026 15:20:10 +0200 Subject: [PATCH] docs: fix and expand user docs - add-new-service.md: document agebd service add's actual behavior (required flags, that it auto-creates and pushes a feature/add-service- branch, and the CI pipeline that push triggers), explain how service-specific vs external PV naming actually works, and correct the claim that external PVs are read-only in dev (unenforced: get_pv_external_class() is unused and there's no EPICS ACF in this repo). - iocs_overview.md: fix TUNEFBX's copy-pasted "top up tool" description, merge the AGEBD-CPCL-DBPM3/DBPM3CURR duplicate, deduplicate the two conflicting PARAMS rows (the "PCT base lifetime" description actually belongs to TAUPCT), clarify that AGEBD-CPCL-ALH isn't a separate IOC, and add the services that were missing entirely (TauPCT, TuneFBy, Params, ShiftTool, BeamTransferChecks, all 11 OpticsFF-* beamline services). - gui.md: warn that launching straight from a git checkout uses unsubstituted {{ agebd_env_suffix_upper/lower }} placeholders, since substitution only happens at deploy time. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01A9GjKvXCmfgJpKzbQdZ7UA --- docs/user/add-new-service.md | 60 ++++++++++++++++++++++++++++++---- docs/user/gui.md | 7 ++++ docs/user/ioc/iocs_overview.md | 33 +++++++++++-------- 3 files changed, 80 insertions(+), 20 deletions(-) diff --git a/docs/user/add-new-service.md b/docs/user/add-new-service.md index 4836810..92ae523 100644 --- a/docs/user/add-new-service.md +++ b/docs/user/add-new-service.md @@ -23,6 +23,36 @@ agebd --help agebd service add --help ``` +Required options: + +- `--name` / `-n`: CamelCase service name (e.g. `MyService`). Used as-is in the GUI, and + converted to upper/lowercase where needed elsewhere. +- `--ioc-owner` / `-o`: who to contact if the picket service flags an issue with this IOC. +- `--ioc-description` / `-d`: short description for the [IOC overview](ioc/iocs_overview.md). + +Optional: + +- `--gui` / `-g`: `new` (default, scaffolds a new `.ui` file), `existing` (reuse another + service's GUI, requires `--gui-existing-service-name`), or `none`. + +**This command has side effects you should know about before running it.** It requires a +clean working tree, then it: + +1. Assigns the service the next free IOC port and registers it in + [`config/services_registry.yml`](../../config/services_registry.yml). +2. Adds the service to `AGEBD-CPCL-MASTER`'s IOC pattern file, so it gets the standard + ALH lifecycle PVs (`AGEBD-ALH$(SUFFIX):$(SERVICE)-*`) and appears in the `ServiceManager` + GUI screen. +3. Appends a row to [`iocs_overview.md`](ioc/iocs_overview.md). +4. Creates a new branch **`feature/add-service-`**, scaffolds the new service's files + from the templates, and **pushes the branch automatically** — you don't run `git push` + yourself. + +Pushing that branch triggers the `Add new service` Gitea Actions workflow +(`.gitea/workflows/add-new-service.yml`), which deploys `master`, installs/restarts its IOC, +deploys your new service, and installs/starts its own IOC — all in `dev`. Check the Actions +tab for that run to confirm it succeeded before doing anything else with the new service. + ## Environments The services are deployed to 2 environments: @@ -42,24 +72,37 @@ We distinguish between #### PVs - Service Specific -You create them, see (# TODO: docs...) +These are defined as EPICS records in your service's own `services//current/ioc/*.template` +file, instantiated by `services//current/ioc/AGEBD-CPCL-_main.subs`. -`prod` and `dev` PVs automatically get created. +`prod` and `dev` PVs automatically get created: at deploy time, `{{ agebd_env_suffix_upper }}`/ +`{{ agebd_env_suffix_lower }}` placeholders in those files are substituted with `-DEV`/`-dev` +in `dev`, or left empty in `prod` (see `.gitea/scripts/deploy-service.sh`). -In your code, you only use the `prod` name of a PV. The framework will automatically use the -`dev` name/PV when a service runs in the `dev` environment. +In your code, you only use the `prod` name of a PV, e.g. `PV("AGEBD-MYSERVICE:MYPVNAME")`. +The `PVLink`/`DevPVLink` framework (`packages/agebd/src/agebd/pv.py`) automatically appends +`-DEV` when the service runs in `dev` — but **only** for PVs belonging to your own service, +plus `AGEBD-ALH`/`AGEBD-MASTER`. See "External" below for PVs owned by another service. #### PVs - External -The framework will use the same PV in `prod` and `dev`, i.e. there is no `dev` PV. -However, in `dev` you can only read from the PV, whereas in `prod` you can also write to it. +PVs owned by another service (including another AGEBD service, e.g. `AGEBD-PARAMS:...` used +from a different service) or by real accelerator hardware (e.g. `ARS01-MOCT-...`) are used +verbatim — no `-DEV` suffix is ever added, even in `dev`. + +Note that, as of writing, there is **no dev/prod read/write restriction enforced anywhere** +for these PVs — `dev` code can write to them exactly like `prod` code can. A +`get_pv_external_class()` helper exists in `pv.py` with a "read-only in dev" intent in its +docstring, but no service currently uses it, and there's no EPICS Access Security (`.acf`) +configuration in this repo either. Be careful writing to external PVs from `dev` — nothing +stops you from affecting the real machine. #### PVs - Examples | Environment | Service Specific | External | |---|---|---| |`prod` | `PV("AGEBD-MYSERVICE:MYPVNAME")` read&write | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` read&write | -| `dev` | `PV("AGEBD-MYSERVICE-DEV:MYPVNAME")` read&write | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` readonly | +| `dev` | `PV("AGEBD-MYSERVICE-DEV:MYPVNAME")` read&write | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` read&write (not actually restricted, see above) | ### Python @@ -70,3 +113,6 @@ For python services there are 3 environments. The python environment is set thro | `AGEBD_ENV=prod` | uses `prod` PVs | | `AGEBD_ENV=dev` | uses `dev` PVs | | `AGEBD_ENV=local` | uses fake/mock python objects as PVs, no access to real PVs | + +An unset or misspelled `AGEBD_ENV` silently falls back to `local` (mock PVs) rather than +raising an error — worth knowing if a service seems to be doing nothing. diff --git a/docs/user/gui.md b/docs/user/gui.md index 4f3b281..d492edd 100644 --- a/docs/user/gui.md +++ b/docs/user/gui.md @@ -21,3 +21,10 @@ Any extra arguments are passed straight through to `caqtdm`, e.g. to set a macro ``` ./bin/sls_hla_launch_gui.sh qt/A_BD_Tune.ui dev -macro "OTHER_ENV_VAR=HEYHEY" ``` + +**Note:** launching straight from a git checkout, as above, uses the raw `.ui` files as +committed - including the literal `{{ agebd_env_suffix_upper }}`/`{{ agebd_env_suffix_lower }}` +placeholders in their PV names. Those only get substituted with `-DEV`/`-dev` (or emptied out, +in `prod`) at deploy time, by `.gitea/workflows/deploy.yml`'s "Qt - deploy" step, on the +*deployed* copy at `/sls/bd/hla//qt/`. If widgets show up blank or unresponsive, check +whether you're accidentally pointing at the raw checkout instead of the deployed `.ui` file. diff --git a/docs/user/ioc/iocs_overview.md b/docs/user/ioc/iocs_overview.md index 32e7aa5..c0e567c 100644 --- a/docs/user/ioc/iocs_overview.md +++ b/docs/user/ioc/iocs_overview.md @@ -4,8 +4,7 @@ The ports are configured in the [service registry](../../../config/services_regi | IOC NAME | Description | |---|---| -| AGEBD-CPCL-MASTER | IOC providing PVs for the service master application and IOC enabling to monitor the health status of BD High Level Application Services with the alarm handler ALH | -| AGEBD-CPCL-ALH | IOC enabling to monitor the health status of BD High Level Application Services with the alarm handler ALH | +| AGEBD-CPCL-MASTER | IOC providing PVs for the service master application, and monitoring the health status of BD High Level Application Services via the alarm handler ALH. ALH is not a separate IOC - its `AGEBD-ALH$(SUFFIX):$(SERVICE)-*` PVs are defined directly in `MASTER.template`, one row per registered service. | | AGEBD-CPCL-TUNE | IOC providing PVs for the tune measurement | | AGEBD-CPCL-SCRUBBING | IOC providing PVs for the vacuum scrubbing service | | AGEBD-CPCL-NTURNS | IOC providing PVs for the DBPM3 stage0 and stage1 nr. of turns calculation service | @@ -15,15 +14,23 @@ The ports are configured in the [service registry](../../../config/services_regi | AGEBD-CPCL-TUNEBUMP | IOC providing PVs for the tune bump service application | | AGEBD-CPCL-PLOTS | IOC providing Buffers of PVs for plots | | AGEBD-CPCL-ORBITBUMP | IOC providing PVs for orbit bumps for the beamlines | -| AGEBD-CPCL-TAUBPM | IOC providing PVs for the lifetime measurement | +| AGEBD-CPCL-TAUBPM | IOC providing PVs for the lifetime measurement (BPM based) | +| AGEBD-CPCL-TAUPCT | IOC providing PVs for PCT based lifetime measurement | | AGEBD-CPCL-TOPUPTOOL | IOC providing PVs for the top up tool | -| AGEBD-CPCL-TUNEFBX | IOC providing PVs for the top up tool | - -# TODO: -| IOC NAME | Description | -|---|---| -| AGEBD-CPCL-PARAMS | IOC providing PVs for machine parameters | -| AGEBD-CPCL-PARAMS | IOC providing PVs for PCT base lifetime measurement | -| AGEBD-CPCL-SHIFTTOOL | | -| AGEBD-CPCL-DBPM3CURR | | -| AGEBD-CPCL-DBPM3 | IOC providing PVs for the DBPM3 stage2 average current calculation service | +| AGEBD-CPCL-TUNEFBX | IOC providing PVs for the horizontal tune feedback | +| AGEBD-CPCL-TUNEFBY | IOC providing PVs for the vertical tune feedback | +| AGEBD-CPCL-PARAMS | IOC providing PVs for machine parameters (e.g. injection state, lifetime, current limit) | +| AGEBD-CPCL-DBPM3CURR | IOC providing PVs for the DBPM3 stage2 average current calculation service | +| AGEBD-CPCL-SHIFTTOOL | IOC providing PVs for the shift log / handover tool | +| AGEBD-CPCL-BEAMTRANSFERCHECKS | IOC providing PVs for beam transfer checks | +| AGEBD-CPCL-OPTICSFF-X02S | IOC providing PVs for optics feed-forward on the I-TOMCAT beamline | +| AGEBD-CPCL-OPTICSFF-X03M | IOC providing PVs for optics feed-forward on the ADRESS beamline | +| AGEBD-CPCL-OPTICSFF-X04S | IOC providing PVs for optics feed-forward on the ADDAMS beamline | +| AGEBD-CPCL-OPTICSFF-X05L | IOC providing PVs for optics feed-forward on the QUEST beamline | +| AGEBD-CPCL-OPTICSFF-X06S | IOC providing PVs for optics feed-forward on the PXI beamline | +| AGEBD-CPCL-OPTICSFF-X07M | IOC providing PVs for optics feed-forward on the PHOENIX/XTREME beamline | +| AGEBD-CPCL-OPTICSFF-X08S | IOC providing PVs for optics feed-forward on the MicroXAS beamline | +| AGEBD-CPCL-OPTICSFF-X09L | IOC providing PVs for optics feed-forward on the OPERA beamline | +| AGEBD-CPCL-OPTICSFF-X10S | IOC providing PVs for optics feed-forward on the PXII beamline | +| AGEBD-CPCL-OPTICSFF-X11M | IOC providing PVs for optics feed-forward on the SIM beamline | +| AGEBD-CPCL-OPTICSFF-X12S | IOC providing PVs for optics feed-forward on the cSAXS beamline |