deviceaccess.Device

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.

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

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

Methods

`__init__`(args, *kwargs)	Overloaded function.
`activateAsyncRead`(self)	Activate asynchronous read for all TransferElements with wait_for_new_data flag.
`close`(self)	Close the device.
`getCatalogueMetadata`(self, metaTag)	Get metadata from the device catalogue.
`getOneDRegisterAccessor`(self, userType, ...)	Get a OneDRegisterAccessor object for the given register.
`getRegisterCatalogue`(self)	Return the register catalogue with detailed information on all registers.
`getScalarRegisterAccessor`(self, userType, ...)	Get a ScalarRegisterAccessor object for the given register.
`getTwoDRegisterAccessor`(self, userType, ...)	Get a TwoDRegisterAccessor object for the given register.
`getVoidRegisterAccessor`(self, ...)	Get a VoidRegisterAccessor object for the given register.
`isFunctional`(self)	Check whether the device is working as intended.
`isOpened`(self)	Check if the device is currently opened.
`open`(args, *kwargs)	Overloaded function.
`read`(self, registerPath[, dtype, ...])	Convenience function to read a register without obtaining an accessor.
`setException`(self, message)	Set the device into an exception state.
`write`(args, *kwargs)	Overloaded function.

__init__(*args, **kwargs)

Overloaded function.

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

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

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.

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.

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