deviceaccess module

class deviceaccess.AccessMode

Bases: pybind11_object

Access mode flags for register access.

Note:

Using the raw flag will make your code intrinsically dependent on the backend type, since the actual raw data type must be known.

Members:

raw : This access mode disables any possible conversion from the original hardware data type into the given UserType. Obtaining the accessor with a UserType unequal to the actual raw data type will fail and throw an exception.

wait_for_new_data : This access mode makes any read blocking until new data has arrived since the last read. This flag may not be supported by all registers (and backends), in which case an exception will be thrown.

property name

class deviceaccess.DataType

Bases: pybind11_object

The actual enum representing the data type. It is a plain enum so the data type class can be used like a class enum, i.e. types are identified for instance as DataType::int32.

class TheType

Bases: pybind11_object

Members:

none : The data type/concept does not exist, e.g. there is no raw transfer (do not confuse with Void)

int8

uint8

int16

uint16

int32

uint32

int64

uint64

float32

float64

string

Boolean

Void

property name

getAsString(self: deviceaccess.DataType) → str

Get the data type as string.

return:

Data type as string.

rtype:

str

isIntegral(self: deviceaccess.DataType) → bool

Return whether the raw data type is an integer. False is also returned for non-numerical types and ‘none’.

return:

True if the data type is an integer, false otherwise.

rtype:

bool

isNumeric(self: deviceaccess.DataType) → bool

Returns whether the data type is numeric. Type ‘none’ returns false.

return:

True if the data type is numeric, false otherwise.

rtype:

bool

isSigned(self: deviceaccess.DataType) → bool

Return whether the raw data type is signed. True for signed integers and floating point types (currently only signed implementations). False otherwise (also for non-numerical types and ‘none’).

return:

True if the data type is signed, false otherwise.

rtype:

bool

class deviceaccess.DataValidity

Bases: pybind11_object

The current state of the data.

Note:

This is a flag to describe the validity of the data. It should be used to signalize whether or not to trust the data currently. It MUST NOT be used to signalize any communication errors with a device, rather to signalize the consumer after such an error that the data is currently not trustable, because we are performing calculations with the last known valid data, for example.

Members:

ok : The data is considered valid

faulty : The data is not considered valid

property name

class deviceaccess.Device

Bases: pybind11_object

Class to access a ChimeraTK device.

The device can be opened and closed, and provides methods to obtain register accessors. Additionally, convenience methods to read and write registers directly are provided. The class also offers methods to check the device state, obtain the register catalogue, Metadata and to set exception conditions.

activateAsyncRead(self: deviceaccess.Device) → None

Activate asynchronous read for all transfer elements with wait_for_new_data flag.

If called while the device is not opened or has an error, this call has no effect. When this function returns, it is not guaranteed that all initial values have been received already.

close(self: deviceaccess.Device) → None

Close the device.

The connection with the alias name is kept so the device can be re-opened using the open() function without argument.

getCatalogueMetadata(self: deviceaccess.Device, metaTag: str) → str

Get metadata from the device catalogue.

param metaTag:

The metadata parameter name to retrieve.

type metaTag:

str

return:

The metadata value.

rtype:

str

getOneDRegisterAccessor(self: deviceaccess.Device, userType: object, registerPathName: str, numberOfElements: int = 0, elementsOffset: int = 0, accessModeFlags: list = []) → ChimeraTK::PyOneDRegisterAccessor

Get a OneDRegisterAccessor object for the given register.

The OneDRegisterAccessor allows to read and write registers transparently by using the accessor object like a vector of the type UserType.

param userType:

The data type for register access (numpy dtype).

type userType:

dtype

param registerPathName:

Full path name of the register.

type registerPathName:

str

param numberOfElements:

Number of elements to access (0 for entire register).

type numberOfElements:

int, optional

param elementsOffset:

Word offset in register to skip initial elements.

type elementsOffset:

int, optional

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode], optional

return:

OneDRegisterAccessor for the specified register.

rtype:

OneDRegisterAccessor

getRegisterCatalogue(self: deviceaccess.Device) → ChimeraTK::RegisterCatalogue

Return the register catalogue with detailed information on all registers.

return:

Register catalogue containing all register information.

rtype:

RegisterCatalogue

getScalarRegisterAccessor(self: deviceaccess.Device, userType: object, registerPathName: str, elementsOffset: int = 0, accessModeFlags: list = []) → ChimeraTK::PyScalarRegisterAccessor

Get a ScalarRegisterAccessor object for the given register.

The ScalarRegisterAccessor allows to read and write registers transparently by using the accessor object like a variable of the type UserType.

param userType:

The data type for register access (numpy dtype).

type userType:

dtype

param registerPathName:

Full path name of the register.

type registerPathName:

str

param elementsOffset:

Word offset in register to access another but the first word.

type elementsOffset:

int, optional

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode], optional

return:

ScalarRegisterAccessor for the specified register.

rtype:

ScalarRegisterAccessor

getTwoDRegisterAccessor(self: deviceaccess.Device, userType: object, registerPathName: str, numberOfElements: int = 0, elementsOffset: int = 0, accessModeFlags: list = []) → ChimeraTK::PyTwoDRegisterAccessor

Get a TwoDRegisterAccessor object for the given register.

This allows to read and write transparently 2-dimensional registers.

param userType:

The data type for register access (numpy dtype).

type userType:

dtype

param registerPathName:

Full path name of the register.

type registerPathName:

str

param numberOfElements:

Number of elements per channel (0 for all).

type numberOfElements:

int, optional

param elementsOffset:

First element index for each channel to read.

type elementsOffset:

int, optional

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode], optional

return:

TwoDRegisterAccessor for the specified register.

rtype:

TwoDRegisterAccessor

getVoidRegisterAccessor(self: deviceaccess.Device, registerPathName: str, accessModeFlags: list = []) → ChimeraTK::PyVoidRegisterAccessor

Get a VoidRegisterAccessor object for the given register.

param registerPathName:

Full path name of the register.

type registerPathName:

str

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode]

return:

VoidRegisterAccessor for the specified register.

rtype:

VoidRegisterAccessor

isFunctional(self: deviceaccess.Device) → bool

Check whether the device is working as intended.

Usually this means it is opened and does not have any errors.

return:

True if device is functional, false otherwise.

rtype:

bool

isOpened(self: deviceaccess.Device) → bool

Check if the device is currently opened.

return:

True if device is opened, false otherwise.

rtype:

bool

open(*args, **kwargs)

Overloaded function.

1. open(self: deviceaccess.Device, aliasName: str) -> None

Open a device by the given alias name from the DMAP file.

param aliasName:

The device alias name from the DMAP file.

type aliasName:

str

2. open(self: deviceaccess.Device) -> None

(Re-)Open the device.

Can only be called when the device was constructed with a given aliasName.

read(self: deviceaccess.Device, registerPath: str, dtype: object = dtype('float64'), numberOfWords: int = 0, wordOffsetInRegister: int = 0, accessModeFlags: list = []) → object

Convenience function to read a register without obtaining an accessor.

Warning:

This function is inefficient as it creates and discards a register accessor in each call. For better performance, use register accessors instead.

param registerPath:

Full path name of the register.

type registerPath:

str

param dtype:

Data type for the read operation (default: float64).

type dtype:

dtype, optional

param numberOfWords:

Number of elements to read (0 for scalar or entire register).

type numberOfWords:

int, optional

param wordOffsetInRegister:

Word offset in register to skip initial elements.

type wordOffsetInRegister:

int, optional

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode], optional

return:

Register value (scalar, 1D array, or 2D array depending on register type).

rtype:

scalar, ndarray, or list[list]

setException(self: deviceaccess.Device, message: str) → None

Set the device into an exception state.

All asynchronous reads will be deactivated and all operations will see exceptions until open() has successfully been called again.

param message:

Exception message describing the error condition.

type message:

str

write(*args, **kwargs)

Overloaded function.

1. write(self: deviceaccess.Device, registerPath: str, dataToWrite: 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]]], wordOffsetInRegister: int = 0, accessModeFlags: list = [], dtype: object = None) -> None

Convenience function to write a 2D register without obtaining an accessor.

Warning:

This function is inefficient as it creates and discards a register accessor in each call. For better performance, use register accessors instead.

param registerPath:

Full path name of the register.

type registerPath:

str

param dataToWrite:

2D array data to write to the register.

type dataToWrite:

list[list]

param wordOffsetInRegister:

Word offset in register to skip initial elements.

type wordOffsetInRegister:

int, optional

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode], optional

param dtype:

Optional data type override (default: inferred from data).

type dtype:

dtype or None

2. write(self: deviceaccess.Device, registerPath: str, dataToWrite: Union[List[ChimeraTK::Boolean], List[int], List[int], List[int], List[int], List[int], List[int], List[int], List[int], List[float], List[float], List[str]], wordOffsetInRegister: int = 0, accessModeFlags: list = [], dtype: object = None) -> None

Convenience function to write a 1D register without obtaining an accessor.

Warning:

This function is inefficient as it creates and discards a register accessor in each call. For better performance, use register accessors instead.

param registerPath:

Full path name of the register.

type registerPath:

str

param dataToWrite:

1D array data to write to the register.

type dataToWrite:

list or ndarray

param wordOffsetInRegister:

Word offset in register to skip initial elements.

type wordOffsetInRegister:

int, optional

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode], optional

param dtype:

Optional data type override (default: inferred from data).

type dtype:

dtype or None

3. write(self: deviceaccess.Device, registerPath: str, dataToWrite: Union[ChimeraTK::Boolean, int, int, int, int, int, int, int, int, float, float, str], wordOffsetInRegister: int = 0, accessModeFlags: list = [], dtype: object = None) -> None

Convenience function to write a scalar register without obtaining an accessor.

Warning:

This function is inefficient as it creates and discards a register accessor in each call. For better performance, use register accessors instead.

param registerPath:

Full path name of the register.

type registerPath:

str

param dataToWrite:

Scalar value to write to the register.

type dataToWrite:

int, float, or str

param wordOffsetInRegister:

Word offset in register (for multi-word registers).

type wordOffsetInRegister:

int, optional

param accessModeFlags:

Optional flags to control register access details.

type accessModeFlags:

list[AccessMode], optional

param dtype:

Optional data type override (default: inferred from data).

type dtype:

dtype or None

class deviceaccess.FundamentalType

Bases: pybind11_object

This is only used inside the DataDescriptor class; defined outside to prevent too long fully qualified names.

Members:

numeric

string

boolean

nodata

undefined

property name

class deviceaccess.OneDRegisterAccessor

Bases: TransferElementBase

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

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.

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

Return current validity of the data.

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

return:

The current data validity state.

rtype:

DataValidity

get(self: deviceaccess.OneDRegisterAccessor) → object

Return the register data as an array (without a previous read).

return:

Array containing the register data.

rtype:

ndarray

getAccessModeFlags(self: deviceaccess.OneDRegisterAccessor) → 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.

return:

List of access mode flags.

rtype:

list[AccessMode]

getAsCooked(self: deviceaccess.OneDRegisterAccessor, element: int) → 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 transfer.

param element:

Element index to read.

type element:

int

return:

The cooked value at the specified element.

rtype:

int

getDescription(self: deviceaccess.OneDRegisterAccessor) → str

Returns the description of this variable/register.

return:

The description string.

rtype:

str

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

Obtain unique ID for the actual implementation of this accessor.

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

return:

The unique accessor ID.

rtype:

TransferElementID

getNElements(self: deviceaccess.OneDRegisterAccessor) → int

Return number of elements/samples in the register.

return:

Number of elements in the register.

rtype:

int

getName(self: deviceaccess.OneDRegisterAccessor) → str

Returns the name that identifies the process variable.

return:

The register name.

rtype:

str

getUnit(self: deviceaccess.OneDRegisterAccessor) → str

Returns the engineering unit.

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

return:

The engineering unit string.

rtype:

str

getValueType(self: deviceaccess.OneDRegisterAccessor) → dtype

Returns the numpy dtype for the value type of this accessor.

This can be used to determine the type at runtime.

return:

Type information object.

rtype:

numpy.dtype

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

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

This refers to the last read or write operation.

return:

The version number of the last transfer.

rtype:

VersionNumber

interrupt(self: deviceaccess.OneDRegisterAccessor) → None

Interrupt a blocking read operation.

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

isInitialised(self: deviceaccess.OneDRegisterAccessor) → bool

Check if the accessor is initialised.

return:

True if initialised, false otherwise.

rtype:

bool

isReadOnly(self: deviceaccess.OneDRegisterAccessor) → bool

Check if accessor is read only.

This means it is readable but not writeable.

return:

True if read only, false otherwise.

rtype:

bool

isReadable(self: deviceaccess.OneDRegisterAccessor) → bool

Check if accessor is readable.

return:

True if readable, false otherwise.

rtype:

bool

isWriteable(self: deviceaccess.OneDRegisterAccessor) → bool

Check if accessor is writeable.

return:

True if writeable, false otherwise.

rtype:

bool

read(self: deviceaccess.OneDRegisterAccessor) → 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.

readAndGet(self: deviceaccess.OneDRegisterAccessor) → object

Convenience function to read and return the register data.

return:

Array containing the register data after reading.

rtype:

ndarray

readLatest(self: deviceaccess.OneDRegisterAccessor) → 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.

return:

True if new data was available, false otherwise.

rtype:

bool

readNonBlocking(self: deviceaccess.OneDRegisterAccessor) → 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.

return:

True if new data was available, false otherwise.

rtype:

bool

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

Set the values of the array.

param newValue:

New values to set in the buffer.

type newValue:

list or ndarray

setAndWrite(self: deviceaccess.OneDRegisterAccessor, newValue: Union[List[ChimeraTK::Boolean], List[int], List[int], List[int], List[int], List[int], List[int], List[int], List[int], List[float], List[float], List[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.

param newValue:

New values to set and write.

type newValue:

list or ndarray

param versionNumber:

Optional version number for the write operation.

type versionNumber:

VersionNumber

setAsCooked(self: deviceaccess.OneDRegisterAccessor, element: int, 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 transfer.

param element:

Element index to write.

type element:

int

param value:

The cooked value to set.

type value:

float

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

Set the data validity of the accessor.

param validity:

The data validity state to set.

type validity:

DataValidity

write(self: deviceaccess.OneDRegisterAccessor, 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.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumber

return:

True if data was lost, false otherwise.

rtype:

bool

writeDestructively(self: deviceaccess.OneDRegisterAccessor, 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.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumber

return:

True if data was lost, false otherwise.

rtype:

bool

class deviceaccess.RegisterPath

Bases: pybind11_object

Class to store a register path name. Elements of the path are separated by a “/” character, but an separation character (e.g. “.”) can optionally be specified as well. Different equivalent notations will be converted into a standardised notation automatically.

endsWith(self: deviceaccess.RegisterPath, arg0: deviceaccess.RegisterPath) → bool

getComponents(self: deviceaccess.RegisterPath) → List[str]

Split path into components.

return:

list of path components.

rtype:

list[str]

getWithAltSeparator(self: deviceaccess.RegisterPath) → str

Obtain path with alternative separator character instead of “/”. The leading separator will be omitted.

return:

Register path with alternative separator.

rtype:

str

length(self: deviceaccess.RegisterPath) → int

Get the length of the path (including leading slash).

return:

Length of the register path.

rtype:

int

setAltSeparator(self: deviceaccess.RegisterPath, altSeparator: str) → None

Set alternative separator.

param altSeparator:

Alternative separator character to use instead of “/”. Use an empty string to reset to default.

type altSeparator:

str

startsWith(self: deviceaccess.RegisterPath, arg0: deviceaccess.RegisterPath) → bool

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.

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

Return current validity of the data.

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

return:

The current data validity state.

rtype:

DataValidity

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).

return:

The current value in the buffer.

rtype:

scalar

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.

return:

List of access mode flags.

rtype:

list[AccessMode]

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.

return:

The cooked value.

rtype:

float

getDescription(self: deviceaccess.ScalarRegisterAccessor) → str

Returns the description of this variable/register.

return:

The description string.

rtype:

str

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.

return:

The unique transfer element ID.

rtype:

TransferElementID

getName(self: deviceaccess.ScalarRegisterAccessor) → str

Returns the name that identifies the process variable.

return:

The register name.

rtype:

str

getUnit(self: deviceaccess.ScalarRegisterAccessor) → str

Returns the engineering unit.

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

return:

The engineering unit string.

rtype:

str

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.

return:

Type information object.

rtype:

type

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.

return:

The version number of the last transfer.

rtype:

VersionNumber

interrupt(self: deviceaccess.ScalarRegisterAccessor) → None

Interrupt a blocking read operation.

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

isInitialised(self: deviceaccess.ScalarRegisterAccessor) → bool

Check if the accessor is initialised.

return:

True if initialised, false otherwise.

rtype:

bool

isReadOnly(self: deviceaccess.ScalarRegisterAccessor) → bool

Check if accessor is read only.

This means it is readable but not writeable.

return:

True if read only, false otherwise.

rtype:

bool

isReadable(self: deviceaccess.ScalarRegisterAccessor) → bool

Check if accessor is readable.

return:

True if readable, false otherwise.

rtype:

bool

isWriteable(self: deviceaccess.ScalarRegisterAccessor) → bool

Check if accessor is writeable.

return:

True if writeable, false otherwise.

rtype:

bool

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.

readAndGet(self: deviceaccess.ScalarRegisterAccessor) → object

Convenience function to read and return the scalar value.

return:

The value after reading from device.

rtype:

scalar

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.

return:

True if new data was available, false otherwise.

rtype:

bool

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.

return:

True if new data was available, false otherwise.

rtype:

bool

set(*args, **kwargs)

Overloaded function.

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

Set the scalar value.

param val:

New value to set in the buffer.

type val:

int, float, bool, or str

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

Set the scalar value from a list.

param val:

List containing a single value to set.

type val:

list

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

Set the scalar value from a numpy array.

param val:

Array containing a single value to set.

type val:

ndarray

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.

param newValue:

New value to set and write.

type newValue:

int, float, bool, or str

param versionNumber:

Optional version number for the write operation.

type versionNumber:

VersionNumber

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.

param value:

The cooked value to set.

type value:

float

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

Set the data validity of the accessor.

param validity:

The data validity state to set.

type validity:

DataValidity

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.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumber

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.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumberl

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.

param newValue:

New value to compare and potentially write.

type newValue:

int, float, bool, or str

param versionNumber:

Optional version number for the write operation.

type versionNumber:

VersionNumber

exception deviceaccess.ThreadInterrupted

Bases: Exception

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.

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

Return current validity of the data.

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

return:

The current data validity state.

rtype:

DataValidity

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.

return:

Current buffer content as a 2D array-like object.

rtype:

ndarray or list

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.

return:

List of access mode flags.

rtype:

list[AccessMode]

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.

param channel:

Channel index.

type channel:

int

param element:

Element index within the channel.

type element:

int

return:

The cooked value.

rtype:

float

getDescription(self: deviceaccess.TwoDRegisterAccessor) → str

Returns the description of this variable/register.

return:

The description string.

rtype:

str

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.

return:

The unique transfer element ID.

rtype:

TransferElementID

getNChannels(self: deviceaccess.TwoDRegisterAccessor) → int

Return number of channels in the register.

return:

Number of channels.

rtype:

int

getNElementsPerChannel(self: deviceaccess.TwoDRegisterAccessor) → int

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

return:

Number of elements per channel.

rtype:

int

getName(self: deviceaccess.TwoDRegisterAccessor) → str

Returns the name that identifies the process variable.

return:

The register name.

rtype:

str

getUnit(self: deviceaccess.TwoDRegisterAccessor) → str

Returns the engineering unit.

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

return:

The engineering unit string.

rtype:

str

getValueType(self: deviceaccess.TwoDRegisterAccessor) → dtype

Returns the type_info for the value type of this accessor.

This can be used to determine the type at runtime.

return:

Type information object.

rtype:

type

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

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

This refers to the last read or write operation.

return:

The version number of the last transfer.

rtype:

VersionNumber

interrupt(self: deviceaccess.TwoDRegisterAccessor) → None

Interrupt a blocking read operation.

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

isInitialised(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if the accessor is initialised.

return:

True if initialised, false otherwise.

rtype:

bool

isReadOnly(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if accessor is read only.

This means it is readable but not writeable.

return:

True if read only, false otherwise.

rtype:

bool

isReadable(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if accessor is readable.

return:

True if readable, false otherwise.

rtype:

bool

isWriteable(self: deviceaccess.TwoDRegisterAccessor) → bool

Check if accessor is writeable.

return:

True if writeable, false otherwise.

rtype:

bool

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.

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.

return:

True if new data was available, false otherwise.

rtype:

bool

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.

return:

True if new data was available, false otherwise.

rtype:

bool

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.

param newValue:

New values to set, shaped as [channels][elements] or a 2D numpy array.

type newValue:

list[list[UserType]] or ndarray

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.

param channel:

Channel index.

type channel:

int

param element:

Element index within the channel.

type element:

int

param value:

The cooked value to set.

type value:

float

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

Set the data validity of the accessor.

param validity:

The data validity state to set.

type validity:

DataValidity

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

Write the buffered data to the 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.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumber

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.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumber

class deviceaccess.VersionNumber

Bases: VersionNumberBase

Class for generating and holding version numbers without exposing a numeric representation.

Version numbers are used to resolve competing updates that are applied to the same process variable. For example, they can help in breaking an infinite update loop that might occur when two process variables are related and update each other.

They are also used to determine the order of updates made to different process variables.

getNullVersion() → deviceaccess.VersionNumber

Get a VersionNumber which is not set (null version).

The null version is guaranteed to be smaller than all version numbers generated with the default constructor and can be used to initialise version numbers that are not yet used for data transfers.

return:

Null version number instance.

rtype:

VersionNumber

getTime(self: deviceaccess.VersionNumberBase) → boost::posix_time::ptime

Get the time stamp associated with this version number.

Note:

This Python binding currently returns a fixed placeholder time (1990-01-01 00:00:00).

return:

Time stamp of the version number.

rtype:

datetime

class deviceaccess.VoidRegisterAccessor

Bases: pybind11_object

Special accessor that represents a register with no user data (ChimeraTK::Void).

This accessor is typically used to model triggers or actions that do not carry a payload. There is no user buffer to read or write values from; read()/write() only perform transfer synchronisation and version-tagged signalling.

Note

Create instances via Device.getVoidRegisterAccessor(). There is no get()/set() as there is no value to access. Use write()/writeDestructively() to trigger an action and read()/readNonBlocking()/readLatest() to synchronise with incoming events.

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

Return current validity of the data.

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

return:

The current data validity state.

rtype:

DataValidity

getAccessModeFlags(self: deviceaccess.VoidRegisterAccessor) → 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.

return:

List of access mode flags.

rtype:

list[AccessMode]

getDescription(self: deviceaccess.VoidRegisterAccessor) → str

Returns the description of this variable/register.

return:

The description string.

rtype:

str

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

Obtain unique ID for the actual implementation of this accessor.

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

return:

The unique transfer element ID.

rtype:

TransferElementID

getName(self: deviceaccess.VoidRegisterAccessor) → str

Returns the name that identifies the process variable.

return:

The register name.

rtype:

str

getUnit(self: deviceaccess.VoidRegisterAccessor) → str

Returns the engineering unit.

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

return:

The engineering unit string.

rtype:

str

getValueType(self: deviceaccess.VoidRegisterAccessor) → std::type_info

Returns the type_info for the value type of this accessor.

This can be used to determine the type at runtime.

return:

Type information object.

rtype:

type

getVersionNumber(self: deviceaccess.VoidRegisterAccessor) → deviceaccess.VersionNumberBase

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

This refers to the last read or write operation.

return:

The version number of the last transfer.

rtype:

VersionNumber

interrupt(self: deviceaccess.VoidRegisterAccessor) → None

Interrupt a blocking read operation.

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

isInitialised(self: deviceaccess.VoidRegisterAccessor) → bool

Check if the accessor is initialised.

return:

True if initialised, false otherwise.

rtype:

bool

isReadOnly(self: deviceaccess.VoidRegisterAccessor) → bool

Check if accessor is read only.

This means it is readable but not writeable.

return:

True if read only, false otherwise.

rtype:

bool

isReadable(self: deviceaccess.VoidRegisterAccessor) → bool

Check if accessor is readable.

return:

True if readable, false otherwise.

rtype:

bool

isWriteable(self: deviceaccess.VoidRegisterAccessor) → bool

Check if accessor is writeable.

return:

True if writeable, false otherwise.

rtype:

bool

read(self: deviceaccess.VoidRegisterAccessor) → None

Read from the device to synchronise with the latest event.

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.

readLatest(self: deviceaccess.VoidRegisterAccessor) → bool

Read the latest event, discarding intermediate updates 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.

return:

True if new data was available, false otherwise.

rtype:

bool

readNonBlocking(self: deviceaccess.VoidRegisterAccessor) → bool

Read the next event, if available.

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 state before returning. Also this function is not guaranteed to be lock free. The return value will be always true in this mode.

return:

True if new data was available, false otherwise.

rtype:

bool

setDataValidity(self: deviceaccess.VoidRegisterAccessor, arg0: ChimeraTK::DataValidity) → None

Set the data validity of the accessor.

param validity:

The data validity state to set.

type validity:

DataValidity

write(self: deviceaccess.VoidRegisterAccessor, versionNumber: deviceaccess.VersionNumber = <PyVersionNumber(versionNumber=v0)>) → bool

Trigger a write to the device (no payload).

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.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumber

writeDestructively(self: deviceaccess.VoidRegisterAccessor, versionNumber: deviceaccess.VersionNumber = <PyVersionNumber(versionNumber=v0)>) → bool

Like write(), but allows the implementation to destroy the content of internal buffers 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 internal buffers to contain undefined data after calling this function.

param versionNumber:

Version number to use for this write operation. If not specified, a new version number is generated.

type versionNumber:

VersionNumber

deviceaccess.getDMapFilePath() → str

Returns the dmap file name which the library currently uses for looking up device(alias) names.

return:

Path of the dmap file (directory and file name).

rtype:

str

deviceaccess.setDMapFilePath(dmapFilePath: str) → None

Set the location of the dmap file.

param dmapFilePath:

Relative or absolute path of the dmap file (directory and file name).

type dmapFilePath:

str