deviceaccess.ScalarRegisterAccessor

class deviceaccess.ScalarRegisterAccessor

Bases: TransferElementBase

Accessor class to read and write scalar registers transparently by using the accessor object like a variable.

Conversion to and from the UserType will be handled by a data converter matching the register description in the map (if applicable).

Note

Transfers between the device and the internal buffer need to be triggered using the read() and write() functions before reading from resp. after writing to the buffer.

__init__(self: deviceaccess.ScalarRegisterAccessor) → None

Methods

`__init__`(self)
`dataValidity`(self)	Return current validity of the data.
`get`(self)	Return the scalar value (without a previous read).
`getAccessModeFlags`(self)	Return the access mode flags that were used to create this accessor.
`getAsCooked`(self)	Get the cooked values in case the accessor is a raw accessor (which does not do data conversion).
`getDescription`(self)	Returns the description of this variable/register.
`getId`(self)	Obtain unique ID for the actual implementation of this accessor.
`getName`(self)	Returns the name that identifies the process variable.
`getUnit`(self)	Returns the engineering unit.
`getValueType`(self)	Returns the type_info for the value type of this accessor.
`getVersionNumber`(self)	Returns 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.
`readAndGet`(self)	Convenience function to read and return the scalar value.
`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`(args, *kwargs)	Overloaded function.
`setAndWrite`(self, newValue, int, int, int, ...)	Convenience function to set and write new value.
`setAsCooked`(self, value, int, int, int, int, ...)	Set the cooked values in case the accessor is a raw accessor (which does not do data conversion).
`setDataValidity`(self, validity)	Set the data validity of the accessor.
`write`(self, versionNumber)	Write the data to device.
`writeDestructively`(self, versionNumber)	Just like write(), but allows the implementation to destroy the content of the user buffer in the process.
`writeIfDifferent`(self, newValue, int, int, ...)	Convenience function to set and write new value if it differs from the current value.

Attributes

dtype

Return the dtype of the value type of this accessor.

__init__(self: deviceaccess.ScalarRegisterAccessor) → None

dataValidity(self: deviceaccess.ScalarRegisterAccessor) → 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.

property dtype

Return the dtype of the value type of this accessor.

This can be used to determine the type at runtime.

Returns:: Type information object.
Return type:: dtype

get(self: deviceaccess.ScalarRegisterAccessor) → object

Return the scalar value (without a previous read).

Returns:
scalar: The current value in the buffer.

getAccessModeFlags(self: deviceaccess.ScalarRegisterAccessor) → 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.ScalarRegisterAccessor) → Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str]

Get the cooked values in case the accessor is a raw accessor (which does not do data conversion).

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

Returns:
float: The cooked value.

getDescription(self: deviceaccess.ScalarRegisterAccessor) → str

Returns the description of this variable/register.

Returns:
str: The description string.

getId(self: deviceaccess.ScalarRegisterAccessor) → ChimeraTK::TransferElementID

Obtain unique ID for the actual implementation of this accessor.

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

Returns:
TransferElementID: The unique TransferElement ID.

getName(self: deviceaccess.ScalarRegisterAccessor) → str

Returns the name that identifies the process variable.

Returns:
str: The register name.

getUnit(self: deviceaccess.ScalarRegisterAccessor) → str

Returns the engineering unit.

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

Returns:
str: The engineering unit string.

getValueType(self: deviceaccess.ScalarRegisterAccessor) → dtype

Returns 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.ScalarRegisterAccessor) → deviceaccess.VersionNumber

Returns 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.ScalarRegisterAccessor) → 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.ScalarRegisterAccessor) → bool

Check if the accessor is initialised.

Returns:
bool: True if initialised, false otherwise.

isReadOnly(self: deviceaccess.ScalarRegisterAccessor) → 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.ScalarRegisterAccessor) → bool

Check if accessor is readable.

Returns:
bool: True if readable, false otherwise.

isWriteable(self: deviceaccess.ScalarRegisterAccessor) → bool

Check if accessor is writeable.

Returns:
bool: True if writeable, false otherwise.

read(self: deviceaccess.ScalarRegisterAccessor) → 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. readAndGet: Convenience method combining read() and get().

Returns:
None: This function does not return a value.

readAndGet(self: deviceaccess.ScalarRegisterAccessor) → object

Convenience function to read and return the scalar value.

Returns:
scalar: The value after reading from device.

readLatest(self: deviceaccess.ScalarRegisterAccessor) → 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.ScalarRegisterAccessor) → 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(*args, **kwargs)

Overloaded function.

set(self: deviceaccess.ScalarRegisterAccessor, val: Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str]) -> None

Set the scalar value.

Args:
val (int | float | bool | str): New value to set in the buffer.

Returns:
None: This function does not return a value.

set(self: deviceaccess.ScalarRegisterAccessor, val: list) -> None

Set the scalar value from a list.

Args:
val (list): List containing a single value to set.

Returns:
None: This function does not return a value.

set(self: deviceaccess.ScalarRegisterAccessor, val: numpy.ndarray) -> None

Set the scalar value from a numpy array.

Args:
val (ndarray): Array containing a single value to set.

Returns:
None: This function does not return a value.

setAndWrite(self: deviceaccess.ScalarRegisterAccessor, newValue: Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str], versionNumber: deviceaccess.VersionNumber = <PyVersionNumber(versionNumber=v0)>) → None

Convenience function to set and write new value.

If versionNumber is not specified, a new version number is generated.

Args:
newValue (int | float | bool | str): New value to set and write. versionNumber (VersionNumber): Optional version number for the write operation.

Returns:
None: This function does not return a value.

setAsCooked(self: deviceaccess.ScalarRegisterAccessor, value: Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str]) → None

Set the cooked values in case the accessor is a raw accessor (which does not do data conversion).

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

Args:
value (float): The cooked value to set.

Returns:
None: This function does not return a value.

setDataValidity(self: deviceaccess.ScalarRegisterAccessor, 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.ScalarRegisterAccessor, versionNumber: deviceaccess.VersionNumberBase = <PyVersionNumber(versionNumber=v0)>) → None

Write the data to device.

The return value is true if old data was lost on the write transfer (e.g. due to a buffer overflow). In case of an unbuffered write transfer, the return value will always be false.

Args:

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

Returns:
bool: True if data was lost, false otherwise.

See Also:
setAndWrite: Convenience method combining set() and write(). writeIfDifferent: Only write if value has changed. writeDestructively: Optimized write that may destroy buffer.

writeDestructively(self: deviceaccess.ScalarRegisterAccessor, 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 the normal 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:
bool: True if data was lost, false otherwise.

writeIfDifferent(self: deviceaccess.ScalarRegisterAccessor, newValue: Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str], versionNumber: deviceaccess.VersionNumber = <PyVersionNumber(versionNumber=v0)>) → None

Convenience function to set and write new value if it differs from the current value.

The given version number is only used in case the value differs. If versionNumber is not specified, a new version number is generated only if the write actually takes place.

Args:
newValue (int | float | bool | str): New value to compare and potentially write. versionNumber (VersionNumber): Optional version number for the write operation.

Returns:
None: This function does not return a value.