deviceaccess.TwoDRegisterAccessor

class deviceaccess.TwoDRegisterAccessor

Bases: TransferElementBase

Accessor class to read and write 2D registers transparently by using the accessor like a two-dimensional array.

The accessor exposes channels and per-channel elements. Conversion to and from the UserType is handled by a data converter matching the register description (if applicable).

Note

Create instances via Device.getTwoDRegisterAccessor(). Transfers between the device and the internal buffer need to be triggered using read() and write() before reading from or after writing to the buffer.

__init__(self: deviceaccess.TwoDRegisterAccessor) → None

Methods

__init__(self)
dataValidity(self)	Return current validity of the data.
get(self)	Return a 2D array of UserType from the internal buffer (without a previous read).
getAccessModeFlags(self)	Return the access mode flags that were used to create this accessor.
getAsCooked(self, channel, element)	Get a cooked value for a specific channel and element when the accessor is raw (no data conversion).
getDescription(self)	Return the description of this variable/register.
getId(self)	Obtain unique ID for the actual implementation of this accessor.
getNChannels(self)	Return number of channels in the register.
getNElementsPerChannel(self)	Return number of elements/samples per channel in the register.
getName(self)	Return the name that identifies the process variable.
getUnit(self)	Return the engineering unit.
getValueType(self)	Return the type_info for the value type of this accessor.
getVersionNumber(self)	Return the version number that is associated with the last transfer.
interrupt(self)	Interrupt a blocking read operation.
isInitialised(self)	Check if the accessor is initialised.
isReadOnly(self)	Check if accessor is read only.
isReadable(self)	Check if accessor is readable.
isWriteable(self)	Check if accessor is writeable.
read(self)	Read the data from the device.
readLatest(self)	Read the latest value, discarding any other update since the last read if present.
readNonBlocking(self)	Read the next value, if available in the input buffer.
set(self, newValue, List[List[int]], ...)	Set the values of the 2D array buffer.
setAsCooked(self, channel, element, value, ...)	Set a cooked value for a specific channel and element when the accessor is raw (no data conversion).
setDataValidity(self, validity)	Set the data validity of the accessor.
write(self, versionNumber)	Write the buffered data to the device.
writeDestructively(self, versionNumber)	Just like write(), but allows the implementation to destroy the content of the user buffer in the

__init__(self: deviceaccess.TwoDRegisterAccessor) → None

dataValidity(self: deviceaccess.TwoDRegisterAccessor) → ChimeraTK::DataValidity

Return current validity of the data.

Will always return DataValidity.ok if the backend does not support it.

Returns:

DataValidity: The current data validity state.

get(self: deviceaccess.TwoDRegisterAccessor) → object

Return a 2D array of UserType from the internal buffer (without a previous read).

The returned object is typically a numpy ndarray with shape (channels, elements_per_channel). For string registers, a list of lists is returned instead.

Returns:

ndarray | list: Current buffer content as a 2D array-like object.

getAccessModeFlags(self: deviceaccess.TwoDRegisterAccessor) → list

Return the access mode flags that were used to create this accessor.

This can be used to determine the setting of the raw and the wait_for_new_data flags.

Returns:

list[AccessMode]: List of access mode flags.

getAsCooked(self: deviceaccess.TwoDRegisterAccessor, channel: int, element: int) → Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str]

Get a cooked value for a specific channel and element when the accessor is raw (no data conversion).

This returns the converted data from the user buffer. It does not do any read or write transfer.

Args:

channel (int): Channel index. element (int): Element index within the channel.

Returns:

float: The cooked value.

getDescription(self: deviceaccess.TwoDRegisterAccessor) → str

Return the description of this variable/register.

Returns:

str: The description string.

getId(self: deviceaccess.TwoDRegisterAccessor) → ChimeraTK::TransferElementID

Obtain unique ID for the actual implementation of this accessor.

This means that e.g. two instances of TwoDRegisterAccessor created by the same call to Device.getTwoDRegisterAccessor() will have the same ID, while two instances obtained by two different calls to Device.getTwoDRegisterAccessor() will have a different ID even when accessing the very same register.

Returns:

TransferElementID: The unique TransferElement ID.

getNChannels(self: deviceaccess.TwoDRegisterAccessor) → int

Return number of channels in the register.

Returns:

int: Number of channels.

getNElementsPerChannel(self: deviceaccess.TwoDRegisterAccessor) → int

Return number of elements/samples per channel in the register.

Returns:

int: Number of elements per channel.

getName(self: deviceaccess.TwoDRegisterAccessor) → str

Return the name that identifies the process variable.

Returns:

str: The register name.

getUnit(self: deviceaccess.TwoDRegisterAccessor) → str

Return the engineering unit.

If none was specified, it will default to ‘n./a.’.

Returns:

str: The engineering unit string.

getValueType(self: deviceaccess.TwoDRegisterAccessor) → dtype

Return the type_info for the value type of this accessor.

This can be used to determine the type at runtime.

Returns:

type: Type information object.

getVersionNumber(self: deviceaccess.TwoDRegisterAccessor) → deviceaccess.VersionNumber

Return the version number that is associated with the last transfer.

This refers to the last read or write operation.

Returns:

VersionNumber: The version number of the last transfer.

interrupt(self: deviceaccess.TwoDRegisterAccessor) → None

Interrupt a blocking read operation.

This will cause a blocking read to return immediately and throw an InterruptedException.

Returns:

None: This function does not return a value.

isInitialised(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if the accessor is initialised.

Returns:

bool: True if initialised, false otherwise.

isReadOnly(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if accessor is read only.

This means it is readable but not writeable.

Returns:

bool: True if read only, false otherwise.

isReadable(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if accessor is readable.

Returns:

bool: True if readable, false otherwise.

isWriteable(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if accessor is writeable.

Returns:

bool: True if writeable, false otherwise.

read(self: deviceaccess.TwoDRegisterAccessor) → None

Read the data from the device.

If AccessMode.wait_for_new_data was set, this function will block until new data has arrived. Otherwise it still might block for a short time until the data transfer was complete.

See Also:

readNonBlocking: Read without blocking if no data is available. readLatest: Read latest value while discarding intermediate updates.

Returns:

None: This function does not return a value.

readLatest(self: deviceaccess.TwoDRegisterAccessor) → bool

Read the latest value, discarding any other update since the last read if present.

Otherwise this function is identical to readNonBlocking(), i.e. it will never wait for new values and it will return whether a new value was available if AccessMode.wait_for_new_data is set.

Returns:

bool: True if new data was available, false otherwise.

readNonBlocking(self: deviceaccess.TwoDRegisterAccessor) → bool

Read the next value, if available in the input buffer.

If AccessMode.wait_for_new_data was set, this function returns immediately and the return value indicates if a new value was available (true) or not (false).

If AccessMode.wait_for_new_data was not set, this function is identical to read(), which will still return quickly. Depending on the actual transfer implementation, the backend might need to transfer data to obtain the current value before returning. Also this function is not guaranteed to be lock free. The return value will be always true in this mode.

Returns:

bool: True if new data was available, false otherwise.

set(self: deviceaccess.TwoDRegisterAccessor, newValue: Union[List[List[ChimeraTK::Boolean]], List[List[int]], List[List[int]], List[List[int]], List[List[int]], List[List[int]], List[List[int]], List[List[int]], List[List[int]], List[List[float]], List[List[float]], List[List[str]]]) → None

Set the values of the 2D array buffer.

Args:

newValue (list[list[UserType]] | ndarray): New values to set, shaped as [channels][elements] or a 2D numpy array.

Returns:

None: This function does not return a value.

setAsCooked(self: deviceaccess.TwoDRegisterAccessor, channel: int, element: int, value: Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str]) → None

Set a cooked value for a specific channel and element when the accessor is raw (no data conversion).

This converts to raw and writes the data to the user buffer. It does not do any read or write transfer.

Args:

channel (int): Channel index. element (int): Element index within the channel. value (float): The cooked value to set.

Returns:

None: This function does not return a value.

setDataValidity(self: deviceaccess.TwoDRegisterAccessor, validity: ChimeraTK::DataValidity) → None

Set the data validity of the accessor.

Args:

validity (DataValidity): The data validity state to set.

Returns:

None: This function does not return a value.

write(self: deviceaccess.TwoDRegisterAccessor, versionNumber: deviceaccess.VersionNumberBase = <PyVersionNumber(versionNumber=v0)>) → None

Write the buffered data to the device.

Args:

versionNumber (VersionNumber): Version number to use for this write operation. If not specified, a new version number is generated.

Returns:

None: This function does not return a value.

See Also:

writeDestructively: Optimized write that may destroy buffer.

writeDestructively(self: deviceaccess.TwoDRegisterAccessor, versionNumber: deviceaccess.VersionNumberBase = <PyVersionNumber(versionNumber=v0)>) → None

Just like write(), but allows the implementation to destroy the content of the user buffer in the

process.

This is an optional optimisation, hence there is a default implementation which just calls write(). In any case, the application must expect the user buffer of the accessor to contain undefined data after calling this function.

Args:

versionNumber (VersionNumber): Version number to use for this write operation. If not specified, a new

version number is generated.

Returns:

None: This function does not return a value.