Skip to content

Commit c68368c

Browse files
birkenfeldbirkenfeld
committed
Use Sphinx "glossary" to define terms
1 parent 1e6ca52 commit c68368c

File tree

1 file changed

+91
-100
lines changed

1 file changed

+91
-100
lines changed

‎protocol/specification/structure.rst‎

Lines changed: 91 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -3,70 +3,62 @@ Structure of SECoP
33

44
.. image:: images/secop-img/secop-node-instance.svg
55

6-
.. index:: ECS
7-
.. index:: SEC node
8-
96
SECoP is a communication protocol with a client-server model. The server is
107
called the **SEC node**, while the client in here is called the **ECS**.
118

12-
ECS
13-
Software controlling the hardware for carrying out an experiment. Includes the
14-
user interface. Usually speaks several protocols with different parts of the
15-
instrument. Often also called "instrument control" in short.
9+
.. glossary::
1610

17-
SEC node
18-
A computing unit or process, connected to all control units (temperature
19-
controller, flow controller, pressure sensor ...) of a sample environment,
20-
bridge to the ECS. SECoP specifies how ECS speak with a SEC node. The SEC
21-
node allows ECS to access a set of modules (and their parameters/commands)
22-
via SECoP. It also provides a list of accessible modules and parameters as
23-
well as descriptive meta data.
11+
ECS
12+
Software controlling the hardware for carrying out an experiment. Includes the
13+
user interface. Usually speaks several protocols with different parts of the
14+
instrument. Often also called "instrument control" in short.
2415

25-
.. index:: module
16+
SEC node
17+
A computing unit or process, connected to all control units (temperature
18+
controller, flow controller, pressure sensor ...) of a sample environment,
19+
bridge to the ECS. SECoP specifies how ECS speak with a SEC node. The SEC
20+
node allows ECS to access a set of modules (and their parameters/commands)
21+
via SECoP. It also provides a list of accessible modules and parameters as
22+
well as descriptive meta data.
2623

2724
Each SEC node consists of one or more **Modules**. These represent the main
2825
interface for interacting with the hardware.
2926

3027
Modules usually have one or more **Base classes** assigned that indicate their
3128
basic functionality, split into **Interface classes** and **Features**.
3229

33-
Module
34-
A named logical component of an abstract view of the equipment.
35-
36-
We intentionally avoid the term "device", which might be misleading, as
37-
"device" is often used for an entire apparatus, like a cryomagnet or
38-
humidity cell. In the context of SECoP, an apparatus in general is composed
39-
of several modules. For example different temperature sensors in one
40-
apparatus are to be seen as different modules.
30+
.. glossary::
4131

42-
Most modules should correspond to one independently measurable physical
43-
quantity and use one of the interface classes `Readable`, `Writable` or
44-
`Drivable`. However, more specialized modules like `Communicator` can be
45-
implemented where appropriate.
32+
Module
33+
A named logical component of an abstract view of the equipment.
4634

47-
A SEC node controls a set of named modules. Modules are fully specified by
48-
the descriptive data, see :ref:`module-description`.
35+
We intentionally avoid the term "device", which might be misleading, as
36+
"device" is often used for an entire apparatus, like a cryomagnet or
37+
humidity cell. In the context of SECoP, an apparatus in general is composed
38+
of several modules. For example different temperature sensors in one
39+
apparatus are to be seen as different modules.
4940

50-
.. index:: interface class
51-
.. index:: feature
41+
Most modules should correspond to one independently measurable physical
42+
quantity and use one of the interface classes `Readable`, `Writable` or
43+
`Drivable`. However, more specialized modules like `Communicator` can be
44+
implemented where appropriate.
5245

53-
Interface class
54-
A named grouping of parameters, commands and properties on a module that
55-
specifies a certain capability.
46+
A SEC node controls a set of named modules. Modules are fully specified by
47+
the descriptive data, see :ref:`module-description`.
5648

57-
Adherence to interface classes (such as `Drivable`) greatly simplifies
58-
implementation in the ECS, since the basic functionality of any Drivable can
59-
be handled in exactly the same way.
49+
Interface class
50+
A named grouping of parameters, commands and properties on a module that
51+
specifies a certain capability.
6052

61-
Feature
62-
Similar to an interface class, a feature specifies a elements and
63-
functionality that are supported by a module, however it is not bound to a
64-
specific hierarchy and can be added to any module regardless of interface
65-
class.
53+
Adherence to interface classes (such as `Drivable`) greatly simplifies
54+
implementation in the ECS, since the basic functionality of any Drivable can
55+
be handled in exactly the same way.
6656

67-
.. index:: parameter
68-
.. index:: command
69-
.. index:: accessible
57+
Feature
58+
Similar to an interface class, a feature specifies a elements and
59+
functionality that are supported by a module, however it is not bound to a
60+
specific hierarchy and can be added to any module regardless of interface
61+
class.
7062

7163
Each of these modules can have static values which are known at startup and
7264
dynamic values. These are called **Properties** and **Parameters**
@@ -78,58 +70,57 @@ To initiate actions that may not necessarily be tied to a parameter, modules can
7870
also have **Commands**, like stopping the current movement or running a
7971
calibration.
8072

81-
Accessible
82-
Parameters and commands together are called Accessibles.
83-
84-
Parameter
85-
A piece of data associated with a module, typically in one of three
86-
categories:
87-
88-
- physical or hardware defined, e.g. `value` or ``pid``
89-
- informational, e.g. `status`
90-
- controlling the operation of the module, e.g. `pollinterval`
91-
92-
The main parameter of a module is its `value`. Writable parameters may
93-
influence the measurement (like PIDs). Additional parameters may give more
94-
information about its state (running, target reached), or details about its
95-
functioning (heater power) for diagnostics purposes.
96-
97-
Parameters with a predefined meaning are listed in :doc:`the standard
98-
<accessibles>`, they must always be used in the same way. Custom parameters
99-
are defined by the implementation of the SEC node and their name must start
100-
with an underscore. The ECS can use unknown parameters only in a generic
101-
way, as their meaning is not known.
102-
103-
Parameters are fully specified by the descriptive data, see
104-
:ref:`accessible-description`.
105-
106-
Command
107-
Commands are provided to initiate specified actions of the module.
108-
They should generate an appropriate reply immediately after that action is
109-
initiated, i.e. should not wait until some other state is reached.
110-
111-
However, if the command triggers side-effects, they MUST be communicated
112-
before the reply is sent. Commands may use a possibly structured argument
113-
and may return a possibly structured result.
114-
115-
Commands with a predefined meaning are listed in :doc:`the standard
116-
<accessibles>`, they must always be used in the same way. Custom commands
117-
are defined by the implementation of the SEC node, the ECS can use them only
118-
in a general way, as their meaning is not known.
119-
120-
.. index:: property
121-
.. index:: data info
122-
123-
Property
124-
The static information about SEC nodes, modules, parameters/commands and
125-
their data types is constructed from properties with predefined names and
126-
meanings. They constitute the "self-describing" part of SECoP.
127-
128-
All properties are collected in the so-called "structure report" and sent to
129-
clients on request, as described in :ref:`this section <descriptive-data>`.
130-
131-
Data info
132-
The full information about data type and metadata of the value of all
133-
parameters, and argument/return value of all commands, is called "data info"
134-
specified in the descriptive data. Available data info is specified in
135-
:doc:`this section <datainfo>`.
73+
.. glossary::
74+
75+
Accessible
76+
Parameters and commands together are called Accessibles.
77+
78+
Parameter
79+
A piece of data associated with a module, typically in one of three
80+
categories:
81+
82+
- physical or hardware defined, e.g. `value` or ``pid``
83+
- informational, e.g. `status`
84+
- controlling the operation of the module, e.g. `pollinterval`
85+
86+
The main parameter of a module is its `value`. Writable parameters may
87+
influence the measurement (like PIDs). Additional parameters may give more
88+
information about its state (running, target reached), or details about its
89+
functioning (heater power) for diagnostics purposes.
90+
91+
Parameters with a predefined meaning are listed in :doc:`the standard
92+
<accessibles>`, they must always be used in the same way. Custom parameters
93+
are defined by the implementation of the SEC node and their name must start
94+
with an underscore. The ECS can use unknown parameters only in a generic
95+
way, as their meaning is not known.
96+
97+
Parameters are fully specified by the descriptive data, see
98+
:ref:`accessible-description`.
99+
100+
Command
101+
Commands are provided to initiate specified actions of the module.
102+
They should generate an appropriate reply immediately after that action is
103+
initiated, i.e. should not wait until some other state is reached.
104+
105+
However, if the command triggers side-effects, they MUST be communicated
106+
before the reply is sent. Commands may use a possibly structured argument
107+
and may return a possibly structured result.
108+
109+
Commands with a predefined meaning are listed in :doc:`the standard
110+
<accessibles>`, they must always be used in the same way. Custom commands
111+
are defined by the implementation of the SEC node, the ECS can use them only
112+
in a general way, as their meaning is not known.
113+
114+
Property
115+
The static information about SEC nodes, modules, parameters/commands and
116+
their data types is constructed from properties with predefined names and
117+
meanings. They constitute the "self-describing" part of SECoP.
118+
119+
All properties are collected in the so-called "structure report" and sent to
120+
clients on request, as described in :ref:`this section <descriptive-data>`.
121+
122+
Data info
123+
The full information about data type and metadata of the value of all
124+
parameters, and argument/return value of all commands, is called "data info"
125+
specified in the descriptive data. Available data info is specified in
126+
:doc:`this section <datainfo>`.

0 commit comments

Comments
 (0)