From 4130913985f0cf586fd4cce6c9bff847965baa56 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 10 Sep 2026 21:15:51 +0200 Subject: [PATCH] Update explanation about catalog. --- docs/source/explanation/catalog.md | 63 ++++++++++++++++++------------ 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/docs/source/explanation/catalog.md b/docs/source/explanation/catalog.md index 1cc6255..e5c7ca9 100644 --- a/docs/source/explanation/catalog.md +++ b/docs/source/explanation/catalog.md @@ -1,31 +1,56 @@ # Control System Catalogs -As pyAML is control-system agnostic, communication with different control systems is handled through control-system bindings. The bindings handle the details of reading from and writing to each backend. +As pyAML is control-system agnostic, communication with different control systems is handled through control-system bindings. The bindings handle the details of reading from and writing to each control system and is implemented in separate packages from the `pyaml` package. -Since the configuration for the bindings varies between backends and can be verbose, it has been separated into a catalog. The catalog allows simple keys to be used in the accelerator configuration and maps each key to the corresponding backend signal configuration, for example a TANGO attribute or an EPICS PV. +Since the configuration for the bindings varies between backends and can be verbose, it has been separated out from the rest of the pyAML configuration and is handled by the catalog. A catalog is backend specific. -The catalog can be viewed as a simple database of control-system signal configurations. It can contain signals that are not currently used by pyAML, and it can be maintained separately from the pyAML configuration if preferred. +There are two types of catalogs, dynamic and static. They work differently and are intended for different use cases as will be explained below. -There are two types of catalogs: dynamic and static. These will be explained in detail below. +The definition of which catalog to use is done at the control system level. It is possible to use to the same catalog for several control systems if you want. ## The Role of the Catalog -The definition of which catalog to use is done at the control system level. +Communication with a control system is done using `DeviceAccess` objects. They can represent an EPICS PV, TANGO attribute or other backend-specific signal. -For example: +The catalog makes it possible to use simple keys in the pyAML configuration and it will retrieve the information needed to build the `DeviceAccess` object, and in some implementations also directly create it. The exact implementation is up to the backend as long as `ControlSystem.get_device_access` returns the `DeviceAccess` object for a specific key. -``` +## Dynamic Catalog + +The dynamic catalog does not require a configuration file and it is therefore the recommended option for most use cases. + +In this version, the configuration is extracted from a dynamic source. This can be directly from the control system or some other source, for example a database, depending on the chosen backend and its catalog implementation. + +This requires access to the source, for example by being on the same network, but no configuration file for the control system configuration has to be loaded by pyAML. + +Example of configuration for dynamic catalog: + +```yaml controls: -- class: tango.pyaml.controlsystem.TangoControlSystem - name: live - catalog: fodo_1gev_6d_pyaml_catalogs.yaml + - type: pyaml_cs_oa.controlsystem + name: live + catalog: + - type: pyaml_cs_oa.dynamic_catalog + backend: tango ``` -It is possible to refer to the same catalog for several control systems. +## Static Catalog + +The static catalog is mainly intended for testing purposes. It consists of a file of entries where each entry corresponds to the configuration for a specific key. It can be seen as a simple, static database of control system signal configurations. -An entry in the catalog can for example look like: +The static catalog can contain entries that are not currently used and be maintained separately from the rest of the pyAML configuration if preferred, but it is loaded as part of loading the pyAML configuration. -``` +Example of configuration for static catalog: + +```yaml +controls: +- type: pyaml_cs_oa.controlsystem + name: live + catalog: fodo_1gev_6d_pyaml_catalogs-oa.yaml +``` + +Example of an entry in the static catalog: + +```yaml class: tango.pyaml.static_catalog.StaticCatalog entries: - class: tango.pyaml.static_catalog_entry.StaticCatalogEntry @@ -36,14 +61,4 @@ entries: unit: 1/m ``` -Devices in the accelerator configuration can then refer to the entry by using the key `AN01-AR/EM-QP/QF.01/magnetic_strength`. - -When the information is needed, the control system backend will ask the catalog to resolve the key, get the configuration information and use it to create the desired backend signal. - -## Dynamic Catalog - -The dynamic catalog allows to read configuration information directly from an external control system. This requires access to the control system of the machine but is convenient if you already have configuration information stored in your control system and want to avoid having to maintain a separate catalog for pyAML. For example, it is possible to read configuration information directly from the TANGO database. - -## Static Catalog - -A static catalog does not require access to a control system. In this version, all the configuration information is defined directly in the catalog. \ No newline at end of file +This format follows the same syntax as for the rest of the pyAML configuration since during the loading process the file is read and the content added to the rest of the pyAML configuration. \ No newline at end of file