API Reference

Complete API documentation for the ChimeraTK DeviceAccess Python bindings.

API Index

The entries below provide direct links to the most important module-level functions, classes, and enums.

setDMapFilePath(dmapFilePath)	Set the location of the dmap file.
getDMapFilePath()	Return the dmap file name which the library currently uses for looking up device(alias) names.
Device	Class for accessing a ChimeraTK device.
ScalarRegisterAccessor	Accessor class to read and write scalar registers transparently by using the accessor object like a variable.
OneDRegisterAccessor	Accessor class to read and write registers transparently by using the accessor object like a numpy array.
TwoDRegisterAccessor	Accessor class to read and write 2D registers transparently by using the accessor like a two-dimensional array.
VoidRegisterAccessor	Special accessor that represents a register with no user data (ChimeraTK::Void).
TransferGroup	Group of TransferElements for coordinated read and write operations.
ReadAnyGroup	Group for waiting on updates from multiple TransferElements with wait_for_new_data enabled.
DataConsistencyGroup
RegisterCatalogue
RegisterInfo
DataDescriptor
DataType	The actual enum representing the data type.
VersionNumber	Class for generating and holding version numbers without exposing a numeric representation.
AccessMode	Access mode flags for register access.
DataValidity	The current state of the data.

Core Classes

Device

Main class for opening and managing connections to devices.

ScalarRegisterAccessor

Accessor for single-valued registers.

OneDRegisterAccessor

Accessor for array-valued registers.

TwoDRegisterAccessor

Accessor for 2D array registers.

Type Mapping

Python types are automatically mapped to hardware types, Numpy types are also supported:

• int ↔ int32

• float ↔ float32

• str ↔ String registers

• list / array / numpy.ndarray ↔ Array registers

Main Module: deviceaccess

class deviceaccess.AccessMode

Bases: pybind11_object

Access mode flags for register access.

Note:

Using the raw flag makes code 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.

__init__(self: deviceaccess.AccessMode, value: int) → None

property name

raw = <AccessMode.raw: 0>

property value

wait_for_new_data = <AccessMode.wait_for_new_data: 1>

class deviceaccess.BackendRegisterInfoBase

Bases: pybind11_object

__init__(*args, **kwargs)

getDataDescriptor(self: deviceaccess.BackendRegisterInfoBase) → ChimeraTK::DataDescriptor

Return description of the actual payload data for this register.

Returns:

DataDescriptor: Object containing information about the data format.

getNumberOfChannels(self: deviceaccess.BackendRegisterInfoBase) → int

Return number of channels in register.

Returns:

int: Number of channels.

getNumberOfDimensions(self: deviceaccess.BackendRegisterInfoBase) → int

Return number of dimensions of this register.

Returns:

int: Number of dimensions (0=scalar, 1=1D array, 2=2D array).

getNumberOfElements(self: deviceaccess.BackendRegisterInfoBase) → int

Return number of elements per channel.

Returns:

int: Number of elements per channel.

getQualifiedAsyncId(self: deviceaccess.BackendRegisterInfoBase) → std::vector<unsigned long, std::allocator<unsigned long> >

Return the fully qualified async::SubDomain ID.

The default implementation returns an empty vector.

Returns:

list[int]: List of IDs forming the fully qualified async::SubDomain ID.

getRegisterName(self: deviceaccess.BackendRegisterInfoBase) → ChimeraTK::RegisterPath

Return full path name of the register.

Returns:

RegisterPath: Full path name of the register (including modules).

getSupportedAccessModes(self: deviceaccess.BackendRegisterInfoBase) → ChimeraTK::AccessModeFlags

Return all supported AccessModes for this register.

Returns:

list[AccessMode]: Flags indicating supported access modes.

getTags(self: deviceaccess.BackendRegisterInfoBase) → std::set<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, std::less<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >, std::allocator<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > > >

Get the list of tags associated with this register.

The default implementation returns an empty set.

Returns:

set[str]: Set of tags associated with this register.

isHidden(self: deviceaccess.BackendRegisterInfoBase) → bool

Return whether the register is “hidden”.

Hidden registers won’t be listed when iterating the catalogue, but can be explicitly iterated.

Returns:

bool: True if the register is hidden, false otherwise.

isReadable(self: deviceaccess.BackendRegisterInfoBase) → bool

Return whether the register is readable.

Returns:

bool: True if the register is readable, false otherwise.

isWriteable(self: deviceaccess.BackendRegisterInfoBase) → bool

Return whether the register is writeable.

Returns:

bool: True if the register is writeable, false otherwise.

class deviceaccess.DataConsistencyGroup

Bases: pybind11_object

__init__(self: deviceaccess.DataConsistencyGroup, matchingMode: ChimeraTK::DataConsistencyGroup::MatchingMode) → None

Create a data consistency group.

Args:

matchingMode (MatchingMode): Matching strategy used to determine whether group members are consistent.

add(self: deviceaccess.DataConsistencyGroup, element: deviceaccess.TransferElementBase) → None

Add a TransferElement to the group.

The same TransferElement can be part of multiple DataConsistencyGroup instances.

Args:

element (TransferElementBase): Element to add. It must be readable and use AccessMode.wait_for_new_data.

getMatchingMode(self: deviceaccess.DataConsistencyGroup) → ChimeraTK::DataConsistencyGroup::MatchingMode

Get the current MatchingMode of this DataConsistencyGroup.

Returns:

MatchingMode: The matching mode used by this group.

isConsistent(self: deviceaccess.DataConsistencyGroup) → bool

Check whether the group is currently in a consistent state.

Returns:

bool: True if a consistent state is reached, False otherwise.

update(self: deviceaccess.DataConsistencyGroup, updatedId: ChimeraTK::TransferElementID) → bool

Process an update notification for one TransferElement.

Call this after an update was received from ReadAnyGroup.

Args:

updatedId (TransferElementID): ID of the element that received an update.

Returns:

bool: True if the group is in a consistent state after processing the update. False if the updated ID was not added to this group.

Note:

For MatchingMode.historized, ReadAnyGroup only forwards consistent updates, so this function normally returns true.

class deviceaccess.DataDescriptor

Bases: pybind11_object

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: deviceaccess.DataDescriptor, arg0: deviceaccess.DataDescriptor) -> None

2. __init__(self: deviceaccess.DataDescriptor, type: deviceaccess.DataType) -> None

Construct a DataDescriptor from a DataType object.

The DataDescriptor will describe the passed DataType with no raw type.

Args:

type (DataType): The data type to describe.

3. __init__(self: deviceaccess.DataDescriptor) -> None

Default constructor.

Initializes the DataDescriptor with fundamental type set to “undefined”.

fundamentalType(self: deviceaccess.DataDescriptor) → ChimeraTK::DataDescriptor::FundamentalType

Get the fundamental data type.

Returns:

FundamentalType: The fundamental data type.

isIntegral(self: deviceaccess.DataDescriptor) → bool

Return whether the data is integral or not.

May only be called for numeric data types. Examples: int or float.

Returns:

bool: True if the data is integral, false otherwise.

isSigned(self: deviceaccess.DataDescriptor) → bool

Return whether the data is signed or not.

Only valid for numeric data types.

Returns:

bool: True if the data is signed, false otherwise.

minimumDataType(self: deviceaccess.DataDescriptor) → deviceaccess.DataType

Get the minimum data type required to represent the described data type.

This is the minimum data type needed in the host CPU to represent the value.

Returns:

DataType: The minimum required data type.

nDigits(self: deviceaccess.DataDescriptor) → int

Return the approximate maximum number of digits needed to represent the value.

This includes a decimal dot (if not an integral data type) and the sign. May only be called for numeric data types.

Note: This number should only be used for displaying purposes. For some data types this might be a large number (e.g. 300), which indicates that a different representation than plain decimal numbers should be chosen.

Returns:

int: Approximate maximum number of digits (base 10).

nFractionalDigits(self: deviceaccess.DataDescriptor) → int

Return the approximate maximum number of digits after the decimal dot.

This is expressed in base 10 and excludes the decimal dot itself. May only be called for non-integral numeric data types.

Note: This number should only be used for displaying purposes. There is no guarantee that the full precision can be displayed with the given number of digits.

Returns:

int: Approximate maximum number of fractional digits (base 10).

rawDataType(self: deviceaccess.DataDescriptor) → deviceaccess.DataType

Get the raw data type.

This describes the data conversion from ‘cooked’ to raw data type on the device. The conversion does not change the shape of the data but describes the data type of a single data point.

Most backends will have type ‘none’ (no raw data conversion available).

Returns:

DataType: The raw data type.

setRawDataType(self: deviceaccess.DataDescriptor, rawDataType: deviceaccess.DataType) → None

Set the raw data type.

This is useful e.g. when a decorated register should no longer allow raw access, in which case you should set DataType.none.

Args:

rawDataType (DataType): The raw data type to set.

transportLayerDataType(self: deviceaccess.DataDescriptor) → deviceaccess.DataType

Get the data type on the transport layer.

This is always a 1D array of the specific data type. The raw transfer might contain data for more than one register.

Examples:

• The multiplexed data of a 2D array

• A text string containing data for multiple scalars mapped to different registers

• The byte sequence of a “struct” with data for multiple registers of different types

Note: Currently all implementations return ‘none’. There is no public API to access the transport layer data yet.

Returns:

DataType: The transport layer data type.

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.

Boolean = <TheType.Boolean: 12>

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

Boolean = <TheType.Boolean: 12>

Void = <TheType.Void: 13>

__init__(self: deviceaccess.DataType.TheType, value: int) → None

float32 = <TheType.float32: 9>

float64 = <TheType.float64: 10>

int16 = <TheType.int16: 3>

int32 = <TheType.int32: 5>

int64 = <TheType.int64: 7>

int8 = <TheType.int8: 1>

property name

none = <TheType.none: 0>

string = <TheType.string: 11>

uint16 = <TheType.uint16: 4>

uint32 = <TheType.uint32: 6>

uint64 = <TheType.uint64: 8>

uint8 = <TheType.uint8: 2>

property value

Void = <TheType.Void: 13>

__init__(self: deviceaccess.DataType, arg0: ChimeraTK::DataType::TheType) → None

float32 = <TheType.float32: 9>

float64 = <TheType.float64: 10>

getAsString(self: deviceaccess.DataType) → str

Get the data type as string.

Returns:

str: Data type as string.

int16 = <TheType.int16: 3>

int32 = <TheType.int32: 5>

int64 = <TheType.int64: 7>

int8 = <TheType.int8: 1>

isIntegral(self: deviceaccess.DataType) → bool

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

Returns:

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

isNumeric(self: deviceaccess.DataType) → bool

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

Returns:

bool: True if the data type is numeric, false otherwise.

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

Returns:

bool: True if the data type is signed, false otherwise.

none = <TheType.none: 0>

string = <TheType.string: 11>

uint16 = <TheType.uint16: 4>

uint32 = <TheType.uint32: 6>

uint64 = <TheType.uint64: 8>

uint8 = <TheType.uint8: 2>

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.

__init__(self: deviceaccess.DataValidity, value: int) → None

faulty = <DataValidity.faulty: 1>

property name

ok = <DataValidity.ok: 0>

property value

class deviceaccess.Device

Bases: pybind11_object

Class for accessing a ChimeraTK device.

The device can be opened and closed, and provides methods to obtain register accessors. In addition, convenience methods to read and write registers directly are available. The class also provides methods to inspect the device state, obtain the register catalogue and metadata, and set exception conditions.

__init__(*args, **kwargs)

Overloaded function.

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

Initialize device and associate a backend.

Note:

The device is not opened after initialization.

Args:

aliasName (str): The ChimeraTK device descriptor for the device.

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

Create device instance without associating a backend yet.

A backend has to be explicitly associated using the open() method, which takes the alias or CDD as an argument.

activateAsyncRead(self: deviceaccess.Device) → None

Activate asynchronous read for all TransferElements 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 reopened using open() without arguments.

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

Get metadata from the device catalogue.

Args:

metaTag (str): The metadata parameter name to retrieve.

Returns:

str: The metadata value.

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 reading and writing registers transparently by using the accessor object like a vector of the specified data type.

Args:

userType (numpy.dtype): The data type for register access (numpy dtype). registerPathName (str): Full path name of the register. numberOfElements (int): Number of elements to access (0 for the entire register). elementsOffset (int): Word offset in the register to skip initial elements. accessModeFlags (list[AccessMode]): Optional flags to control register access details.

Returns:

OneDRegisterAccessor: OneDRegisterAccessor for the specified register.

See Also:

getScalarRegisterAccessor(): For single-value registers. getTwoDRegisterAccessor(): For 2D array registers. getVoidRegisterAccessor(): For trigger-only registers. read(): Convenience function for one-time reads. write(): Convenience function for one-time writes.

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

Return the register catalogue with detailed information on all registers.

Returns:

RegisterCatalogue: RegisterCatalogue containing all register information.

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 reading and writing registers transparently by using the accessor object like a variable of the specified data type.

Args:

userType (numpy.dtype): The data type for register access (numpy dtype). registerPathName (str): Full path name of the register. elementsOffset (int): Word offset in the register to access other than the first word. accessModeFlags (list[AccessMode]): Optional flags to control register access details.

Returns:

ScalarRegisterAccessor: ScalarRegisterAccessor for the specified register.

See Also:

getOneDRegisterAccessor(): For 1D array registers. getTwoDRegisterAccessor(): For 2D array registers. getVoidRegisterAccessor(): For trigger-only registers. read(): Convenience function for one-time reads. write(): Convenience function for one-time writes.

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 reading and writing 2-dimensional registers transparently.

Args:

userType (numpy.dtype): The data type for register access (numpy dtype). registerPathName (str): Full path name of the register. numberOfElements (int): Number of elements per channel (0 for all). elementsOffset (int): First element index for each channel to read. accessModeFlags (list[AccessMode]): Optional flags to control register access details.

Returns:

TwoDRegisterAccessor: TwoDRegisterAccessor for the specified register.

See Also:

getOneDRegisterAccessor(): For 1D array registers. getScalarRegisterAccessor(): For single-value registers. getVoidRegisterAccessor(): For trigger-only registers. read(): Convenience function for one-time reads. write(): Convenience function for one-time writes.

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

Get a VoidRegisterAccessor object for the given register.

Args:

registerPathName (str): Full path name of the register. accessModeFlags (list[AccessMode]): Optional flags to control register access details.

Returns:

VoidRegisterAccessor: VoidRegisterAccessor for the specified register.

See Also:

getScalarRegisterAccessor(): For scalar value registers. getOneDRegisterAccessor(): For 1D array registers. getTwoDRegisterAccessor(): For 2D array registers. getRegisterCatalogue(): Browse all available registers.

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.

Returns:

bool: True if the device is functional, False otherwise.

isOpened(self: deviceaccess.Device) → bool

Check if the device is currently opened.

Returns:

bool: True if the device is opened, False otherwise.

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.

Args:

aliasName (str): The device alias name from the DMAP file.

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.

Args:

registerPath (str): Full path name of the register. dtype (numpy.dtype): Data type for the read operation (default: float64). numberOfWords (int): Number of elements to read (0 for scalar or entire register). wordOffsetInRegister (int): Word offset in the register to skip initial elements. accessModeFlags (list[AccessMode]): Optional flags to control register access details.

Returns:

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

See Also:

getScalarRegisterAccessor(): For efficient repeated scalar access. getOneDRegisterAccessor(): For efficient repeated 1D array access. getTwoDRegisterAccessor(): For efficient repeated 2D array access. write(): Convenience function for one-time writes.

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.

Args:

message (str): Exception message describing the error condition.

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

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

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 register without obtaining an accessor.

This method is overloaded to handle different data types. The appropriate overload is selected based on the type of dataToWrite.

Warning:

This function is inefficient as it creates and discards a register accessor in each call. For better performance, use register accessors instead: getScalarRegisterAccessor(), getOneDRegisterAccessor(), getTwoDRegisterAccessor().

Args:

registerPath (str): Full path name of the register. dataToWrite (int | float | bool | str | ndarray): Data to write. Type determines operation:

• Scalar (int, float, bool, str): Write a scalar value to a single-element register.

• 1D array (ndarray): Write 1D array data to a 1D register.

• 2D array (ndarray): Write 2D array data to a 2D register.

wordOffsetInRegister (int): Word offset in the register to skip initial elements (default: 0). accessModeFlags (list[AccessMode]): Optional flags to control register access (default: []). dtype (numpy.dtype | None): Optional data type override. If None, type is inferred from data (default:

None).

Examples:

>>> import ChimeraTK.DeviceAccess as da
>>> import numpy as np
>>> da.setDMapFilePath('testCrate.dmap')
>>> device = da.Device('TEST_CARD')
>>> device.open()
>>> # Write scalar value
>>> device.write('MYSCALAR', 42.5)
>>> # Write 1D array
>>> device.write('MYARRAY', np.array([1.0, 2.0, 3.0]))
>>> # Write 2D array
>>> device.write('MY2DARRAY', np.array([[1, 2], [3, 4]]))

See Also:

getScalarRegisterAccessor(): For efficient repeated scalar access. getOneDRegisterAccessor(): For efficient repeated 1D array access. getTwoDRegisterAccessor(): For efficient repeated 2D array access. read(): Convenience function for one-time reads.

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

__init__(self: deviceaccess.FundamentalType, value: int) → None

boolean = <FundamentalType.boolean: 2>

property name

nodata = <FundamentalType.nodata: 3>

numeric = <FundamentalType.numeric: 0>

string = <FundamentalType.string: 1>

undefined = <FundamentalType.undefined: 4>

property value

class deviceaccess.MatchingMode

Bases: pybind11_object

Enum describing the matching mode of a DataConsistencyGroup.

Members:

none : No consistency matching. Effectively disables consistency checks for the group.

exact : Require an exact VersionNumber match across all current values of the group’s members.

historized : Allow matching against historized values to find a consistent state across group members.

__init__(self: deviceaccess.MatchingMode, value: int) → None

exact = <MatchingMode.exact: 1>

historized = <MatchingMode.historized: 2>

property name

none = <MatchingMode.none: 0>

property value

class deviceaccess.Notification

Bases: pybind11_object

Notification returned by ReadAnyGroup wait methods.

__init__(self: deviceaccess.Notification) → None

Create an invalid notification.

accept(self: deviceaccess.Notification) → bool

Accept the notification and process the associated update.

Returns:

None: This function does not return a value.

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

Return the ID of the TransferElement for which this notification was generated.

Returns:

TransferElementID: ID of the associated TransferElement.

getTransferElement(self: deviceaccess.Notification) → None

Return the TransferElement for which this notification was generated.

Raises:

RuntimeError: Always raised because this method is not implemented.

isReady(self: deviceaccess.Notification) → bool

Tell whether this notification is valid and has not been accepted yet.

Returns:

bool: True if this notification is ready to be accepted, false otherwise.

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.

__init__(self: deviceaccess.OneDRegisterAccessor) → None

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

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

Returns:

ndarray: Array containing the register data.

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.

Returns:

list[AccessMode]: List of access mode flags.

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.

Args:

element (int): Element index to read.

Returns:

int: The cooked value at the specified element.

getDescription(self: deviceaccess.OneDRegisterAccessor) → str

Return the description of this variable/register.

Returns:

str: The description string.

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.

Returns:

TransferElementID: The unique accessor ID.

getNElements(self: deviceaccess.OneDRegisterAccessor) → int

Return number of elements/samples in the register.

Returns:

int: Number of elements in the register.

getName(self: deviceaccess.OneDRegisterAccessor) → str

Return the name that identifies the process variable.

Returns:

str: The register name.

getUnit(self: deviceaccess.OneDRegisterAccessor) → str

Return the engineering unit.

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

Returns:

str: The engineering unit string.

getValueType(self: deviceaccess.OneDRegisterAccessor) → dtype

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

This can be used to determine the type at runtime.

Returns:

numpy.dtype: Type information object.

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

Check if the accessor is initialised.

Returns:

bool: True if initialised, false otherwise.

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

Check if accessor is readable.

Returns:

bool: True if readable, false otherwise.

isWriteable(self: deviceaccess.OneDRegisterAccessor) → bool

Check if accessor is writeable.

Returns:

bool: True if writeable, false otherwise.

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.

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.OneDRegisterAccessor) → object

Convenience function to read and return the register data.

Returns:

ndarray: Array containing the register data after reading.

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.

Returns:

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

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.

Returns:

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

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.

Args:

newValue (list | ndarray): New values to set in the buffer.

Returns:

None: This function does not return a value.

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.

Args:

newValue (list | ndarray): New values 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.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.

Args:

element (int): Element index to write. value (float): The cooked value to set.

Returns:

None: This function does not return a value.

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

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(). writeDestructively: Optimized write that may destroy buffer.

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.

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.

class deviceaccess.ReadAnyGroup

Bases: pybind11_object

Group for waiting on updates from multiple TransferElements with wait_for_new_data enabled.

__init__(self: deviceaccess.ReadAnyGroup) → None

Create an empty ReadAnyGroup.

add(self: deviceaccess.ReadAnyGroup, element: deviceaccess.TransferElementBase) → None

Add a TransferElement to the group.

This is only allowed before finalise() has been called. The given element may not already be part of a ReadAnyGroup or TransferGroup, otherwise an exception is thrown. The element must be readable.

Returns:

None: This function does not return a value.

finalise(self: deviceaccess.ReadAnyGroup) → None

Finalise the group.

After this, add() may no longer be called and read/wait methods may be used.

Returns:

None: This function does not return a value.

interrupt(self: deviceaccess.ReadAnyGroup) → None

Interrupt blocking operations running on this group.

processPolled(self: deviceaccess.ReadAnyGroup) → None

Process polled TransferElements and update them if new values are available.

Returns:

None: This function does not return a value.

readAny(self: deviceaccess.ReadAnyGroup) → ChimeraTK::TransferElementID

Wait until one of the elements in this group has received an update.

Returns:

TransferElementID: ID of the element whose update has been processed.

readAnyNonBlocking(self: deviceaccess.ReadAnyGroup) → ChimeraTK::TransferElementID

Return immediately and process an update if one is available.

Returns:

TransferElementID: ID of the processed element, or an invalid ID if no update is available.

readUntil(*args, **kwargs)

Overloaded function.

1. readUntil(self: deviceaccess.ReadAnyGroup, id: ChimeraTK::TransferElementID) -> None

Wait until the given TransferElementID has received an update and store it in its user buffer.

Returns:

None: This function does not return a value.

2. readUntil(self: deviceaccess.ReadAnyGroup, element: deviceaccess.TransferElementBase) -> None

Wait until the given TransferElement has received an update and store it in its user buffer.

Returns:

None: This function does not return a value.

readUntilAll(*args, **kwargs)

Overloaded function.

1. readUntilAll(self: deviceaccess.ReadAnyGroup, ids: List[ChimeraTK::TransferElementID]) -> None

Wait until all given TransferElementID values have received updates and store them in their user buffers.

Returns:

None: This function does not return a value.

2. readUntilAll(self: deviceaccess.ReadAnyGroup, elements: list) -> None

Wait until all given TransferElements have received updates and store them in their user buffers.

Returns:

None: This function does not return a value.

waitAny(self: deviceaccess.ReadAnyGroup) → ChimeraTK::ReadAnyGroup::Notification

Wait until any element in this group has received an update, but do not process the update.

Returns:

Notification: Notification object for the pending update.

waitAnyNonBlocking(self: deviceaccess.ReadAnyGroup) → ChimeraTK::ReadAnyGroup::Notification

Return immediately with a notification if an update is available.

Returns:

Notification: Notification object for a pending update, or an invalid notification if none is available.

class deviceaccess.RegisterCatalogue

Bases: pybind11_object

__init__(self: deviceaccess.RegisterCatalogue, arg0: deviceaccess.RegisterCatalogue) → None

Catalogue of register information.

getNumberOfRegisters(self: deviceaccess.RegisterCatalogue) → int

Get number of registers in the catalogue.

Returns:

int: Number of registers in the catalogue.

getRegister(self: deviceaccess.RegisterCatalogue, registerPathName: ChimeraTK::RegisterPath) → ChimeraTK::RegisterInfo

Get register information for a given full path name.

Args:

registerPathName (str): Full path name of the register.

Returns:

RegisterInfo: Register information.

Raises:

ChimeraTK::logic_error: If register does not exist in the catalogue.

hasRegister(self: deviceaccess.RegisterCatalogue, registerPathName: ChimeraTK::RegisterPath) → bool

Check if register with the given path name exists.

Args:

registerPathName (str): Full path name of the register.

Returns:

bool: True if register exists in the catalogue, false otherwise.

hiddenRegisters(self: deviceaccess.RegisterCatalogue) → list

Return list of all hidden registers in the catalogue.

Returns:

list[deviceaccess.RegisterInfo]: A list of hidden RegisterInfo objects.

class deviceaccess.RegisterInfo

Bases: pybind11_object

__init__(self: deviceaccess.RegisterInfo, arg0: deviceaccess.RegisterInfo) → None

Catalogue of register information.

getDataDescriptor(self: deviceaccess.RegisterInfo) → ChimeraTK::DataDescriptor

Return description of the actual payload data for this register.

Returns:

DataDescriptor: Object containing information about the data format.

getNumberOfChannels(self: deviceaccess.RegisterInfo) → int

Return the number of channels in the register.

Returns:

int: Number of channels.

getNumberOfDimensions(self: deviceaccess.RegisterInfo) → int

Return the number of dimensions of this register.

Returns:

int: Number of dimensions (0=scalar, 1=1D array, 2=2D array).

getNumberOfElements(self: deviceaccess.RegisterInfo) → int

Return the number of elements per channel.

Returns:

int: Number of elements per channel.

getQualifiedAsyncId(self: deviceaccess.RegisterInfo) → std::vector<unsigned long, std::allocator<unsigned long> >

Get the fully qualified async::SubDomain ID.

If the register does not support wait_for_new_data it will be empty. Note: At the moment using async::Domain and async::SubDomain is not mandatory yet, so the ID might be empty even if the register supports wait_for_new_data.

Returns:

list[int]: List of IDs forming the fully qualified async::SubDomain ID.

getRegisterName(self: deviceaccess.RegisterInfo) → str

Return the full path name of the register.

Returns:

RegisterPath: Full path name of the register (including modules).

getSupportedAccessModes(self: deviceaccess.RegisterInfo) → list

Return all supported AccessModes for this register.

Returns:

list[AccessMode]: Flags indicating supported access modes.

getTags(self: deviceaccess.RegisterInfo) → std::set<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, std::less<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >, std::allocator<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > > >

Get the list of tags that are associated with this register.

Returns:

set[str]: Set of tags associated with this register.

isReadable(self: deviceaccess.RegisterInfo) → bool

Check whether the register is readable.

Returns:

bool: True if the register is readable, false otherwise.

isValid(self: deviceaccess.RegisterInfo) → bool

Check whether the RegisterInfo object is valid.

Returns:

bool: True if the object contains a valid implementation, false otherwise.

isWriteable(self: deviceaccess.RegisterInfo) → bool

Check whether the register is writeable.

Returns:

bool: True if the register is writeable, false otherwise.

class deviceaccess.RegisterPath

Bases: pybind11_object

Class to store a register path name.

Elements of the path are separated by a “/” character, but an alternative separator character such as “.” can optionally be specified as well. Different equivalent notations are converted into a standardised notation automatically.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: deviceaccess.RegisterPath) -> None

Create an empty RegisterPath.

Returns:

RegisterPath: Empty register path.

2. __init__(self: deviceaccess.RegisterPath, other: deviceaccess.RegisterPath) -> None

Create a RegisterPath by copying another RegisterPath.

Args:

other (RegisterPath): Path to copy.

3. __init__(self: deviceaccess.RegisterPath, path: str) -> None

Create a RegisterPath from a path string.

Args:

path (str): Register path string.

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

Check whether the path ends with the given suffix.

Args:

suffix (RegisterPath): Suffix to check.

Returns:

bool: True if this path ends with suffix, false otherwise.

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

Split path into components.

Returns:

list[str]: List of path components.

getWithAltSeparator(self: deviceaccess.RegisterPath) → str

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

Returns:

str: Register path with alternative separator.

length(self: deviceaccess.RegisterPath) → int

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

Returns:

int: Length of the register path.

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

Set alternative separator.

Args:

altSeparator (str): Alternative separator character to use instead of “/”. Use an empty string to reset to default.

Returns:

None: This function does not return a value.

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

Check whether the path starts with the given prefix.

Args:

prefix (RegisterPath): Prefix to check.

Returns:

bool: True if this path starts with prefix, false otherwise.

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

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.

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.

Args:

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

Returns:

None: This function does not return a value.

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

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

exception deviceaccess.ThreadInterrupted

Bases: Exception

class deviceaccess.TransferElementBase

Bases: pybind11_object

__init__(*args, **kwargs)

class deviceaccess.TransferElementID

Bases: pybind11_object

__init__(*args, **kwargs)

isValid(self: deviceaccess.TransferElementID) → bool

Check whether the ID is valid.

Returns:

bool: True if the ID is valid, False otherwise.

class deviceaccess.TransferGroup

Bases: pybind11_object

Group of TransferElements for coordinated read and write operations.

A TransferGroup allows triggering one read or write call for all added accessors.

__init__(self: deviceaccess.TransferGroup) → None

Create an empty TransferGroup.

addAccessor(self: deviceaccess.TransferGroup, element: deviceaccess.TransferElementBase) → None

Add an accessor to the group.

A TransferElement can only be part of one TransferGroup. TransferGroup can only be used with transfer elements that do not have AccessMode.wait_for_new_data.

Args:

element (TransferElementBase): Accessor to add to the group.

isReadOnly(self: deviceaccess.TransferGroup) → bool

Check whether all accessors in the group are read only.

Returns:

bool: True if all accessors are read only, false otherwise.

isReadable(self: deviceaccess.TransferGroup) → bool

Check whether all accessors in the group are readable.

Returns:

bool: True if all accessors are readable, false otherwise.

isWriteable(self: deviceaccess.TransferGroup) → bool

Check whether all accessors in the group are writable.

Returns:

bool: True if all accessors are writable, false otherwise.

read(self: deviceaccess.TransferGroup) → None

Trigger a read transfer for all accessors in the group.

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

Trigger a write transfer for all accessors in the group.

Args:

versionNumber (VersionNumber): Optional version number used for the write operation. If not set, a new version number is generated.

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

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.

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.

__init__(self: deviceaccess.VersionNumber) → None

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.

Returns:

VersionNumber: Null version number instance.

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

Returns:

datetime: Time stamp of the version number.

class deviceaccess.VersionNumberBase

Bases: pybind11_object

__init__(*args, **kwargs)

getVersionNumberAsString(self: deviceaccess.VersionNumberBase) → str

Return the human readable string representation of the version number.

Returns:

str: Version number as string.

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.

__init__(self: deviceaccess.VoidRegisterAccessor) → None

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

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.

Returns:

list[AccessMode]: List of access mode flags.

getDescription(self: deviceaccess.VoidRegisterAccessor) → str

Return the description of this variable/register.

Returns:

str: The description string.

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.

Returns:

TransferElementID: The unique TransferElement ID.

getName(self: deviceaccess.VoidRegisterAccessor) → str

Return the name that identifies the process variable.

Returns:

str: The register name.

getUnit(self: deviceaccess.VoidRegisterAccessor) → str

Return the engineering unit.

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

Returns:

str: The engineering unit string.

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

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.VoidRegisterAccessor) → deviceaccess.VersionNumberBase

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.VoidRegisterAccessor) → 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.VoidRegisterAccessor) → bool

Check if the accessor is initialised.

Returns:

bool: True if initialised, false otherwise.

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

Check if accessor is readable.

Returns:

bool: True if readable, false otherwise.

isWriteable(self: deviceaccess.VoidRegisterAccessor) → bool

Check if accessor is writeable.

Returns:

bool: True if writeable, false otherwise.

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.

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

Returns:

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

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.

Returns:

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

setDataValidity(self: deviceaccess.VoidRegisterAccessor, 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.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.

Args:

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

version number is generated.

Returns:

bool: True if old data was lost on the write transfer.

See Also:

writeDestructively: Optimized write that may destroy buffer.

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.

Args:

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

version number is generated.

Returns:

bool: True if old data was lost on the write transfer.

deviceaccess.getDMapFilePath() → str

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

Returns:

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

deviceaccess.setDMapFilePath(dmapFilePath: str) → None

Set the location of the dmap file.

Args:

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

Returns:

None: This function does not return a value.

Legacy Module: mtca4u

Note

The mtca4u module is a legacy interface. New code should use the deviceaccess module instead.

mtca4u.get_info(outputStream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

prints details about the module and the deviceaccess library against which it was linked

Parameters

outputStream: optional

default: sys.stdout

Returns

Examples

>>> import mtca4u
>>> mtca4u.get_info()
mtca4uPy v02.03.00, linked with mtca4u-deviceaccess v$ChimeraTK-DeviceAccess_VERSION}

mtca4u.set_dmap_location(dmapFileLocation)

Sets the location of the dmap file to use

The library will check the user specified device Alias names (when creating devices) in this dmap file. Once set, the library will look at this dmap file through out the program lifetime. This is true until a new dmap file is set again using set_dmap_location

Parameters

dmapFileLocation: string

Path to the desired dmap file.

Returns

Examples

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> device = mtca4u.Device("my_card") # my_card is a alias in my_example_dmap_file.dmap

See Also

get_dmap_location: View the current dmap file which the library uses for device name (alias) lookup. Device : Open device using specified alias names or using device id and mapfile

mtca4u.get_dmap_location()

Get the dmap file which is currently in use by the library.

Method returns the file path of the dmap file the library currently uses. This is the dmap file the library uses to look up the device name(alias) and its details

Parameters

Returns

string: File path of the dmap file the library currently uses.

Examples

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> dmapPath = mtca4u.get_dmap_location()
>>> print dmapPath # prints '../my_example_dmap_file.dmap'

See Also

set_dmap_location : set dmap file path for the library. Device : Open device using specified alias names or using device id and mapfile

class mtca4u.Device(cddOrAlias)

Bases: object

Construct Device from user provided device information

This constructor is used to open a device listed in the dmap file.

Parameters

aliasstr

The device alias/name in the dmap file for the hardware

Examples

Creating a device using dmap file:

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> device = mtca4u.Device("my_card") # my_card is a alias in my_example_dmap_file.dmap

__init__(cddOrAlias)

read(moduleName='', registerName=None, numberOfElementsToRead=0, elementIndexInRegister=0, registerPath=None)

Reads out Fixed point converted values from the opened device

This method uses the map file to return Fixed Point converted values from a register. It can read the whole register or an arbitary number of register elements. Data can also be read from an offset within the register (through the ‘elementIndexInRegister’ parameter).

Note

Both moduleName and registerName parameters are ignored when registerPath is provided.

Parameters

moduleNamestr, optional

The name of the device module to which the register belongs to. If the register is not contained in a module, then provide an empty string as the parameter value.

registerNamestr, optional

The name of the register to read from.

numberOfElementsToReadint, optional

Specifies the number of register elements that should be read out. The width and fixed point representation of the register element are internally obtained from the map file.

The method returns all elements in the register if this parameter is ommitted or when its value is set as 0.

If the value provided as this parameter exceeds the register size, an array with all elements upto the last element is returned

elementIndexInRegisterint, optional

This is a zero indexed offset from the first element of the register. When an elementIndexInRegister parameter is specified, the method reads out elements starting from this element index. The elemnt at the index position is included in the read as well.

registerPathstr, optional

When provided, it takes precedences over moduleName and registerName for location lookup.

Returns

readoutValues: numpy.array, dtype == numpy.float64

The return type for the method is a 1-Dimensional numpy array with datatype numpy.float64. The returned numpy.array would either contain all elements in the register or only the number specified by the numberOfElementsToRead parameter

Examples

register “WORD_STATUS” is 1 element long..

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> boardWithModules = mtca4u.Device("device_name")
>>> boardWithModules.read("BOARD", "WORD_STATUS")
array([15.0], dtype=float64)
>>> boardWithModules.read(registerPath="/BOARD/WORD_STATUS")
array([15.0], dtype=float64)

register “WORD_CLK_MUX” is 4 elements long.

>>> import mtca4u
>>> device = mtca4u.Device("device_name")
>>> device.read("", "WORD_CLK_MUX")
array([15.0, 14.0, 13.0, 12.0], dtype=float64)
>>> device.read("", "WORD_CLK_MUX", 0)
array([15.0, 14.0, 13.0, 12.0], dtype=float64)

read out select number of elements from specified locations:

>>> device.read("", "WORD_CLK_MUX", 1)
array([15.0], dtype=float64)
>>> device.read("", "WORD_CLK_MUX", 1, 2 )
array([13.0], dtype=float64)
>>> device.read("", "WORD_CLK_MUX", 0, 2 )
array([13.0, 12.0], dtype=float64)
>>> device.read("", "WORD_CLK_MUX", 5, 2 )
array([13.0, 12.0], dtype=float64)
>>> device.read("", "WORD_CLK_MUX", numberOfElementsToRead=1, elementIndexInRegister=2 )
array([13.0], dtype=float64)
>>> device.read("", "WORD_CLK_MUX", elementIndexInRegister=2 )
array([13.0, 12.0], dtype=float64)

See Also

Device.read_raw : Read in ‘raw’ bit values from a device register

write(moduleName='', registerName=None, dataToWrite=None, elementIndexInRegister=0, registerPath=None)

Sets data into a desired register

This method writes values into a register on the board. The method internally uses a fixed point converter that is aware of the register width on the device and its fractional representation. This Fixed point converter converts the input into corresponding Fixed Point representaions that fit into the decive register.

Note

Both moduleName and registerName parameters are ignored when registerPath is provided.

Parameters

moduleNamestr, optional

The name of the device module which has the register to write into. If module name is not applicable to the register, then provide an empty string as the parameter value.

registerNamestr, optional

Mapped name of the register to write to

dataToWriteint, float, list of int/float, numpy.array(dtype numpy.float32/64), numpy.array(dtype = numpy.int32/64)

The data to be written in to the register. it may be a numpy.float32/64 or a numpy.int32/64 array or a list with int or float values . Each value in this array represents an induvidual element of the register. dataToWrite may also take on int/float type when single vaues are passesed

elementIndexInRegisterint, optional

This is a zero indexed offset from the first element of the register. When an elementIndexInRegister parameter is specified, the method starts the write from this index

registerPathstr, optional

When provided, it takes precedences over moduleName and registerName for location lookup.

Returns

Examples

register “WORD_STATUS” is 1 element long and belongs to module “BOARD”.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> boardWithModules = mtca4u.Device("device_name")
>>> boardWithModules.write("BOARD", "WORD_STATUS", 15)
>>> boardWithModules.write("BOARD", "WORD_STATUS", 15.0)
>>> boardWithModules.write("BOARD", "WORD_STATUS", [15])
>>> boardWithModules.write("BOARD", "WORD_STATUS", [15.0])

>>> boardWithModules.write(registerPath = "/BOARD/WORD_STATUS",
                           dataToWrite = [15.0])

>>> dataToWrite = numpy.array([15.0])
>>> boardWithModules.write("BOARD", "WORD_STATUS", dataToWrite)

register “WORD_CLK_MUX” is 4 elements long.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> device = mtca4u.Device("device_name")
>>> dataToWrite = numpy.array([15.0, 14.0, 13.0, 12.0])
>>> device.write("", "WORD_CLK_MUX", dataToWrite)
>>> dataToWrite = numpy.array([13, 12])
>>> device.write("", "WORD_CLK_MUX", dataToWrite, 2)
>>> device.write("", "WORD_CLK_MUX", 2.78) # writes value to first element of register
>>> device.write("", "WORD_CLK_MUX", 10, elementIndexInRegister=3)

See Also

Device.write_raw : Write ‘raw’ bit values to a device register

read_raw(moduleName='', registerName=None, numberOfElementsToRead=0, elementIndexInRegister=0, registerPath=None)

Returns ‘raw values’ (Without fixed point conversion applied) from a device’s register

This method returns the raw bit values contained in the queried register. The returned values are not Fixed Point converted, but direct binary values contained in the register elements.

Note

Both moduleName and registerName parameters are ignored when registerPath is provided.

Parameters

moduleNamestr, optional

The name of the device module to which the register to read from belongs. If module name is not applicable to the register, then provide an empty string as the parameter value.

registerNamestr, optional

The name of the device register to read from.

numberOfElementsToReadint, optional

Specifies the number of register elements that should be read out. The method returns all elements in the register if this parameter is ommitted or when its value is set as 0. If the value provided as this parameter exceeds the register size, an array will all elements upto the last element is returned

elementIndexInRegisterint, optional

This is a zero indexed offset from the first element of the register. When an elementIndexInRegister parameter is specified, the method reads out elements starting from this element index. The element at the index position is included in the read as well.

registerPathstr, optional

When provided, it takes precedences over moduleName and registerName for location lookup.

Returns

readInRawValues: numpy.array, dtype == numpy.int32

The method returns a numpy.int32 array containing the raw bit values of the register elements. The length of the array either equals the number of elements that make up the register or the number specified through the numberOfElementsToRead parameter

Examples

register “WORD_STATUS” is 1 element long.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> boardWithModules = mtca4u.Device("device_name")
>>> boardWithModules.read_raw("BOARD", "WORD_STATUS")
array([15], dtype=int32)
>>> boardWithModules.read_raw(registerPath="/BOARD/WORD_STATUS")
array([15], dtype=int32)

register “WORD_CLK_MUX” is 4 elements long.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> device = mtca4u.Device("device_name")
>>> device.read_raw("", "WORD_CLK_MUX")
array([15, 14, 13, 12], dtype=int32)
>>> device.read_raw("", "WORD_CLK_MUX", 0)
array([15, 14, 13, 12], dtype=int32)
>>> device.read_raw("", "WORD_CLK_MUX", 1)
array([15], dtype=int32)
>>> device.read_raw("", "WORD_CLK_MUX", 1, 2 )
array([13], dtype = int32)
>>> device.read_raw("", "WORD_CLK_MUX", 0, 2 )
array([13, 12], dtype=int32)
>>> device.read_raw("", "WORD_CLK_MUX", numberOfElementsToRead=1, elementIndexInRegister=2 )
array([13], dtype=int32)
>>> device.read_raw("", "WORD_CLK_MUX", elementIndexInRegister=2 )
array([13, 12], dtype=int32)

See Also

Device.read : Read in Fixed Point converted bit values from a device register

write_raw(moduleName='', registerName=None, dataToWrite=None, elementIndexInRegister=0, registerPath=None)

Write raw bit values (no fixed point conversion applied) into the register

Provides a way to put in a desired bit value into individual register elements.

Note

Both moduleName and registerName parameters are ignored when registerPath is provided.

Parameters

moduleNamestr, optional

The name of the device module that has the register we intend to write to. If module name is not applicable to the register, then provide an empty string as the parameter value.

registerNamestr, optional

The name of the desired register to write into.

dataToWritenumpy.array, dtype == numpy.int32

The array holding the bit values to be written into the register. The numpy array is expected to contain numpy.int32 values

elementIndexInRegisterint, optional

This is a zero indexed offset from the first element of the register. When an elementIndexInRegister parameter is specified, the method starts the write from this index

registerPathstr, optional

When provided, it takes precedences over moduleName and registerName for location lookup.

Returns

Examples

register “WORD_STATUS” is 1 element long and is part of the module “BOARD”.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> boardWithModules = mtca4u.Device("device_name")
>>> _dataToWrite = numpy.array([15], dtype=int32)
>>> boardWithModules.write_raw("BOARD", "WORD_STATUS", dataToWrite=_dataToWrite)
>>> boardWithModules.write_raw(registerPath = "/BOARD/WORD_STATUS",
                                dataToWrite=_dataToWrite)

register “WORD_CLK_MUX” is 4 elements long.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> device = mtca4u.Device("device_name")
>>> dataToWrite = numpy.array([15, 14, 13, 12], dtype=int32)
>>> device.write_raw("", "WORD_CLK_MUX", dataToWrite)
>>> dataToWrite = numpy.array([13, 12], dtype=int32)
>>> device.write_raw("MODULE1", "WORD_CLK_MUX", dataToWrite, 2)

See Also

Device.write : Write values that get fixed point converted to the device

read_dma_raw(moduleName='', DMARegisterName=None, numberOfElementsToRead=0, elementIndexInRegister=0, registerPath=None)

Read in Data from the DMA region of the card

This method can be used to fetch data copied to a dma memory block. The method assumes that the device maps the DMA memory block to a register made up of 32 bit elements.

Note

Deprecated since 1.0.0; use Device.read_raw instead.

Parameters

moduleNamestr, optional

The name of the device module that has the register we intend to write to. If module name is not applicable to the device, then provide an empty string as the parameter value.

DMARegisterNamestr, optional

The register name to which the DMA memory region is mapped

numberOfElementsToReadint, optional

This optional parameter specifies the number of 32 bit elements that have to be returned from the mapped dma register. When this parameter is not specified or is provided with a value of 0, every element in the DMA memory block is returned.

If the value provided as this parameter exceeds the register size, an array with all elements upto the last element is returned

elementIndexInRegisterint, optional

This parameter specifies the index from which the read should commence.

registerPathstr, optional

When provided, it takes precedences over moduleName and registerName for location lookup.

Returns

arrayOfRawValues: numpy.array, dtype == numpy.int32

The method returns a numpy.int32 array containing the raw bit values contained in the DMA register elements. The length of the array either equals the number of 32 bit elements that make up the whole DMA region or the number specified through the numberOfElementsToRead parameter

Examples

Use Device.read_raw: In the example, register “AREA_DMA_VIA_DMA” is the DMA mapped memory made up of 32 bit elements.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> device = mtca4u.Device("device_name")
>>> device.read__raw("", "AREA_DMA_VIA_DMA", 10)
array([0, 1, 4, 9, 16, 25, 36, 49, 64, 81], dtype=int32)

See Also

Device.read_raw : Use this method for the same purpose instead.

read_sequences(moduleName='', regionName=None, registerPath=None)

Read in all sequences from a Multiplexed data Region

This method returns the demultiplexed sequences in the memory area specified by regionName. The data is returned as a 2D numpy array with the coulums representing induvidual sequences

Note

Both moduleName and regionName parameters are ignored when registerPath is provided.

Parameters

moduleNamestr, optional

The name of the device module that has the register we intend to write to. If module name is not applicable to the device, then provide an empty string as the parameter value.

regionNamestr, optional

The name of the memory area containing the multiplexed data.

registerPathstr, optional

When provided, it takes precedences over moduleName and regionName for location lookup.

Returns

2DarrayOfValues: numpy.array, dtype == numpy.double

The method returns a 2D numpy.double array containing extracted induvidual sequences as the columns

Examples

“DMA” is the Multiplexed data region name. This region is defined by ‘AREA_MULTIPLEXED_SEQUENCE_DMA’ in the mapfile.

>>> import mtca4u
>>> mtca4u.set_dmap_location("../my_example_dmap_file.dmap")
>>> device = mtca4u.Device("device_name")
>>> device.read_sequences("BOARD.0", "DMA")
array([[   0.,    1.,    4.,    9.,   16.],
       [  25.,   36.,   49.,   64.,   81.],
       [ 100.,  121.,  144.,  169.,  196.],
       [ 225.,  256.,  289.,  324.,  361.]
       [ 400.,  441.,  484.,  529.,  576.]], dtype=double)
>>> device.read_sequences(registerPath= '/BOARD.0/DMA')
array([[   0.,    1.,    4.,    9.,   16.],
       [  25.,   36.,   49.,   64.,   81.],
       [ 100.,  121.,  144.,  169.,  196.],
       [ 225.,  256.,  289.,  324.,  361.]
       [ 400.,  441.,  484.,  529.,  576.]], dtype=double)

Each column of the 2D matrix represents an extracted sequence:

>>> data = device.read_sequences("BOARD.0", "DMA")
>>> adc0_values = data[:,0] # array([0., 25., 100., 225., 400.])
>>> adc1_values = data[:,1] # array([1., 36., 49., 64., 81.])
>>> adc3_values = data[:,3] # array([9., 64., 169., 324., 529.])

getCatalogueMetadata(parameterName)

Reads out metadata form the device catalogue

The available metadata depends on the use backend. E.g. for NumericAddressedBackends, metadata will come from the map file.

Parameters

parameterNamestr

Name of the metadata parameter to read.

Returns

metadataValue: str

The value corresponding to the given parameterName.

See Also

• User Guide for usage patterns and best practices

• Examples for practical code samples

• Getting Started for installation and basic usage

• Frequently Asked Questions for common questions