@@ -57,6 +57,128 @@ Base classes
5757 indicate a ``BUSY `` state for a longer lasting operations.
5858
5959
60+ Acqusition base classes
61+ ~~~~~~~~~~~~~~~~~~~~~~~
62+
63+ These base classes are meant to support devices used for data acquisition. This
64+ hardware can range in complexity from devices that simply provide values after
65+ some acquisition time, to multi-channel detector setups common in large scale
66+ facilities.
67+
68+ This is conceptually different simple `Readable `\s , where reading a value is
69+ assumed to be always available, without noticeably waiting time. In contrast,
70+ an acqusition cycle represented by these modules can take a while to complete,
71+ maybe providing intermediate values, and deliver a final value once finished,
72+ until the next acquisition cycle is started.
73+
74+ The following terms are relevant here:
75+
76+ - "acquisition": a complete data acquisition system consisting of one
77+ AcquisitionController module and optionally some AcquisitionChannel modules.
78+
79+ - "acquisition cycle": a single cycle of data acquisition, started by the
80+ controller's `go ` command.
81+
82+ - "channel": a part of the data acquisition system representing a measured
83+ quantity. An acquisition can acquire data for one or more channels at the
84+ same time.
85+
86+ See also :secop-rfc: `006-acquisition `.
87+
88+ .. baseclass :: AcquisitionController
89+
90+ A module that controls a data acquisition process that consists of one or
91+ more channels. It must have a `status ` that is either ``IDLE ``, ``BUSY ``
92+ while the acquisition is acquiring, or ``PREPARED `` state after ``prepare ``
93+ is called or data acquisition is paused by `hold `.
94+
95+ Descriptive data `~mod.interface_classes `: ``["AcquisitionController"] ``.
96+
97+ It must have a `go ` command to start the data acquisition. It is a no-op if
98+ already busy. Data acquisition runs until one of the channels' active
99+ presets is hit or `stop ` is called explicitly. Runs the `prepare ` sequence
100+ first if module is not already prepared.
101+
102+ Optional commands:
103+
104+ - `prepare `: prepares a data acquisition so that triggering with `go ` is
105+ immediate. No-op if already prepared. Cannot be called when busy.
106+ - `hold `: pauses a data acquisition. No-op if not busy. Subsequent
107+ `go ` continues the acquisition without clearing currently acquired data.
108+ - `stop `: stops a data acquisition. No-op if not busy. Subsequent `go `
109+ starts a new acquisition with clearing currently acquired data.
110+
111+ An acquisition controller furthermore must have a `~mod.acquisition_channels `
112+ property specifying the channel modules belonging to this controller. The
113+ names of the channel modules are represented as the values of the JSON
114+ object. The role of the channels are represented by the keys and can be
115+ used as such by an ECS.
116+
117+ The key "t" is predefined as a time channel, which basically ends
118+ acquisition when the time indicated by the `goal ` parameter of the channel
119+ module is reached.
120+
121+ Example module property of a controller module "controller"::
122+
123+ {"t": "timechannel", "monitor": "monitor_channel"}
124+
125+ The 3 modules "controller", "timechannel" and "monitor_channel" all belong
126+ together.
127+
128+ .. baseclass :: AcquisitionChannel
129+
130+ A module that represents one component of a data acqusition. Multiple
131+ channels can be combined within a controller.
132+
133+ Descriptive data `~mod.interface_classes `: ``["AcquisitionChannel",
134+ "Readable"] ``.
135+
136+ It must have a `value ` parameter which is interpreted as in `Readable `. If
137+ the hardware allows, this parameter should be readable during the
138+ acquisition and return the current intermediate state. Outside of a data
139+ acquisition, the value MUST stay unchanged and represent the result of the
140+ latest cycle.
141+
142+ It also must have a standard `status ` parameter that is ``BUSY `` while the
143+ channel is acquiring.
144+
145+ Optionally, it can have a `goal ` parameter. It is a `value ` that, when
146+ reached, stops the data acquisition. Depending on the nature of the
147+ acqusition cycle being performed, it may or may not be useful to configure
148+ the acqusition with a `goal `. It can for example represent time for timer
149+ channels, or a certain number of events for event counter channels, or a
150+ desired statistical significance for a channel that represents the
151+ measurement uncertainty. For acquisitions that are configured with several
152+ parameters whose value is unrelated to the main `value ` parameter, it is
153+ better to use custom parameters instead.
154+
155+ Furthermore, it can have a ``goal_enable `` parameter. If false, the goal is
156+ ignored and the acquisition does not stop due to this channel. If `goal ` is
157+ present but not ``goal_enable ``, the goal is always active.
158+
159+ **Optional extension for channels that have "matrix" like values **
160+
161+ - `roi `, an optional parameter: a list containing a ``(min, max) `` tuple
162+ per dimension, to specify a sub-slice of matrix data to consider in
163+ `value ` and return in `get_data `.
164+ - `get_data `, an optional command: returns the channel's data, with a
165+ :ref: `matrix <matrix >` data type.
166+
167+ The `value ` parameter only contains a useful "reduced" form of the data,
168+ for example, the sum of all events in the matrix, or the average of all
169+ intensity values in a spectrum. If `roi ` exists, only the selected
170+ sub-slice of matrix data is considered for this reduction.
171+
172+ .. baseclass :: Acquisition
173+
174+ Combines both AcquisitionController and AcquisitionChannel accessibles into
175+ one interface, for simple devices where only one channel is needed.
176+
177+ Does not have the `~mod.acquisition_channels ` property.
178+
179+ Descriptive data `~mod.interface_classes `: ``["Acquisition", "Readable"] ``.
180+
181+
60182.. _features :
61183
62184Features
0 commit comments