bec/bec
0
0
Fork 0
mirror of https://github.com/bec-project/bec.git synced 2026-06-02 08:18:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: improved scan stub docs and glossary

Browse Source
This commit is contained in:
wakonig_k
2024-05-29 14:09:14 +02:00
parent 3ad46efb14
commit e04cf65f9c
3 changed files with 38 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
bec_server/bec_server/scan_server/scan_stubs.py
+27 -4
View File
@@ -125,7 +125,7 @@ class ScanStubs:
def set_with_response(
self, *, device: str, value: float, request_id: str = None, metadata=None
) -> Generator[None, None, None]:
"""Set a device to a specific value and return the request ID.
"""Set a device to a specific value and return the request ID. Use :func:`request_is_completed` to later check if the request is completed.
Args:
device (str): Device name.
@@ -134,6 +134,8 @@ class ScanStubs:
Returns:
Generator[None, None, None]: Generator that yields a device message.
see also: :func:`request_is_completed`
"""
request_id = str(uuid.uuid4()) if request_id is None else request_id
metadata = metadata if metadata is not None else {}
@@ -142,7 +144,7 @@ class ScanStubs:
return request_id
def request_is_completed(self, RID: str) -> bool:
"""Check if a request is completed.
"""Check if a request that was initiated with :func:`set_with_response` is completed.
Args:
RID (str): Request ID.
@@ -168,6 +170,8 @@ class ScanStubs:
Returns:
Generator[None, None, None]: Generator that yields a device message.
see also: :func:`set`, :func:`wait`, :func:`set_with_response`
"""
if not isinstance(positions, list) and not isinstance(positions, np.ndarray):
positions = [positions]
@@ -313,6 +317,8 @@ class ScanStubs:
Returns:
Generator[None, None, None]: Generator that yields a device message.
see also: :func:`open_scan`
"""
yield self._device_msg(device=None, action="close_scan", parameter={})
@@ -323,6 +329,8 @@ class ScanStubs:
Returns:
Generator[None, None, None]: Generator that yields a device message.
see also: :func:`unstage`
"""
yield self._device_msg(device=None, action="stage", parameter={})
@@ -332,6 +340,8 @@ class ScanStubs:
Returns:
Generator[None, None, None]: Generator that yields a device message.
see also: :func:`stage`
"""
yield self._device_msg(device=None, action="unstage", parameter={})
@@ -450,7 +460,8 @@ class ScanStubs:
)
def trigger(self, *, group: str, point_id: int) -> Generator[None, None, None]:
"""Trigger a device group
"""Trigger a device group. Note that the trigger event is not blocking and does not wait for the completion of the trigger event.
To wait for the completion of the trigger event, use the :func:`wait` command, specifying the wait_type as "trigger".
Args:
group (str): Device group that should receive the trigger.
@@ -458,6 +469,8 @@ class ScanStubs:
Returns:
Generator[None, None, None]: Generator that yields a device message.
see also: :func:`wait`
"""
yield self._device_msg(
device=None,
@@ -467,7 +480,10 @@ class ScanStubs:
)
def set(self, *, device: str, value: float, wait_group: str, metadata=None):
"""Set the device to a specific value.
"""Set the device to a specific value. This is similar to the direct set command
in the command-line interface. The wait_group can be used to wait for the completion of this event.
For a set operation, this simply means that the device has acknowledged the set command and does not
necessarily mean that the device has reached the target value.
Args:
device (str): Device name
@@ -477,6 +493,13 @@ class ScanStubs:
Returns:
Generator[None, None, None]: Generator that yields a device message.
.. warning::
Do not use this command to kickoff a long running operation. Use :func:`kickoff` instead or, if the
device does not support the kickoff command, use :func:`set_with_response` instead.
see also: :func:`wait`, :func:`set_and_wait`, :func:`set_with_response`
"""
yield self._device_msg(
device=device,
docs/source/developer/glossary.md
+9 -3
View File
@@ -15,6 +15,12 @@ queue_id
The ``queue_id`` is an identifier for an element in a queue. Each queue element can contain multiple scans and thus enforce the sequential execution of those scans. The ``queue_id`` is a uuid4 string that is generated by the bec_lib during the preparation of a new queue element.
DIID
The ``DIID`` is the device instruction ID. It is a continuously increasing integer that is assigned to each device instruction in a scan. The ``DIID`` is used to uniquely identify each device instruction and its response in the scan.
```
point_id
The ``point_id`` is an integer that is assigned to each point in a scan. It is used to uniquely identify each point in a scan and is used to group the data that is generated by a scan. The ``point_id`` is typically set directly during the scan definition and used by the {term}`Scan Bundler` to logically bundle the data that is generated by a scan. In synchronous fly scans, the ``point_id may`` also be set directly by the device.
Device Server
The Device Server provides a core service of BEC and handles the communication to the devices. It is the only process that actually holds the connection to the devices. Other services, like the {term}`Scan Server`, communicate with the Device Server to interact with the devices.
Scan Server
The Scan Server provides a core service of BEC and handles the execution of scans. It is responsible for receiving and validating scan requests, assembling the scan instructions, queueing the scan and finally executing the scan using a Scan Worker. If necessary, the Scan Server emits DeviceInstructionMessages to the {term}`Device Server` to interact with the devices.
Scan Bundler
The Scan Bundler is a core service of BEC that is responsible for bundling the data that is generated by a scan. It subscribes to Redis channels and listens for data that is generated by the devices. The Scan Bundler then bundles the data into logical units, called scan segments, and emits them as ScanMessage back to Redis.
```
docs/source/developer/scans/scans.md
+2 -1
View File
@@ -190,7 +190,8 @@ In order to simplify the creation of new scans, BEC provides a set of scan stubs
- [`set`](/api_reference/_autosummary/bec_server.scan_server.scan_stubs.ScanStubs.rst#bec_server.scan_server.scan_stubs.ScanStubs.set) Set a device to a value.
- [`rpc`](/api_reference/_autosummary/bec_server.scan_server.scan_stubs.ScanStubs.rst#bec_server.scan_server.scan_stubs.ScanStubs.rpc) Send an RPC command to a device.
- [`send_rpc_and_wait`](/api_reference/_autosummary/bec_server.scan_server.scan_stubs.ScanStubs.rst#bec_server.scan_server.scan_stubs.ScanStubs.send_rpc_and_wait) Send an RPC command to a device and wait for it to finish.
- [`set_with_response`](/api_reference/_autosummary/bec_server.scan_server.scan_stubs.ScanStubs.rst#bec_server.scan_server.scan_stubs.ScanStubs.set_with_response) Set a device to a specific value and return the request ID. Use this method as an alternative to `kickoff` if the device does not support `kickoff`.
- [`request_is_completed`](/api_reference/_autosummary/bec_server.scan_server.scan_stubs.ScanStubs.rst#bec_server.scan_server.scan_stubs.ScanStubs.request_is_completed) Check if a request that was initiated with `set_with_response` is completed.
*Scan operations*
- [`open_scan`](/api_reference/_autosummary/bec_server.scan_server.scan_stubs.ScanStubs.rst#bec_server.scan_server.scan_stubs.ScanStubs.open_scan) Open a scan.
- [`close_scan`](/api_reference/_autosummary/bec_server.scan_server.scan_stubs.ScanStubs.rst#bec_server.scan_server.scan_stubs.ScanStubs.close_scan) Close a scan.