deviceaccess module

This module offers the functionality of the DeviceAccess C++ library for python.

The ChimeraTK DeviceAccess library provides an abstract interface for register based devices. Registers are identified by a name and usually accessed though an accessor object. Since this library also allows access to other control system applications, it can be understood as the client library of the ChimeraTK framework.

More information on ChimeraTK can be found at the project’s github.io.

class deviceaccess.Device(aliasName: Optional[str] = None)

Bases: object

Construct Device from user provided device information

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

Parameters:aliasName (str) – The device alias/name in the dmap file for the hardware

Examples

Creating a device using a dmap file:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
# CARD_WITH_MODULES is an alias in the dmap file above
>>> dev = da.Device("CARD_WITH_MODULES")

Supports also with-statements:

>>> with da.Device('CARD_WITH_MODULES') as dev:
>>>     reg_value = dev.read('/PATH/TO/REGISTER')

activateAsyncRead() → None

Activate asynchronous read for all transfer elements where AccessMode.wait_for_new_data is set.

If this method is called while the device is not opened or has an error, this call has no effect. If it is called when no deactivated transfer element exists, this call also has no effect. On return, it is not guaranteed that all initial values have been received already.

See also

getVoidRegisterAccessor(): has a usage example.

close() → None

Close the Device.

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

Examples

Closing an open device:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> dev.close()

getCatalogueMetadata(metaTag: str) → str

Provides access to catalogue metadata. This method uses the metadata catalogue to access the value, defined at the beginning of a mapp file, i.e.: @TAG value By convention the tag is in uppercase.

Parameters:metaTag – Tag of the metadata, i.e.: MAPFILE_REVISION Returns: Return type:String containing the metadata

getOneDRegisterAccessor(userType, registerPathName: str, numberOfElements: int = 0, elementsOffset: int = 0, accessModeFlags: Optional[Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]] = None) → deviceaccess.OneDRegisterAccessor

Get a OneDRegisterAccessor object for the given register.

The OneDRegisterAccessor allows to read and write registers transparently by using the accessor object like a vector of the type UserType. If needed, the conversion to and from the UserType will be handled by a data converter matching the register description in e.g. a map file.

Parameters:

• userType (type or numpy.dtype) – The userType for the accessor. Can be of any of the numpy.dtype combinations of float, int, 32 or 64-bit. Integers are also supported as signed, unsigned, 8 and 16-bit. E.g. numpy.uint8, or numpy.float32. There are also str, bool.
• registerPathName (str) – The name of the register to read from.
• numberOfElements (int, optional) –

  Specifies the number of elements per channel to read from the register. 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 omitted 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.

• elementsOffset (int, 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.
• accessModeFlags (list, optional) – A list to specify the access mode. It allows e.g. to enable raw access. See AccessMode documentation for more details. Passing an access mode flag which is not supported by the backend or the given register will raise a NOT_IMPLEMENTED DeviceException.

Examples

Getting a One-D Register Accessor of type uint8 from WORD_STATUS; which is 1 element long:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(np.uint8, "BOARD/WORD_STATUS")
>>> acc.read()
>>> acc
OneDRegisterAccessor([255], dtype=uint8)

Getting a One-D Register Accessor of type float64 from register “WORD_CLK_MUX” is 4 elements long.

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(np.uint8, "BOARD/WORD_CLK_MUX")
>>> acc.read()
>>> acc
OneDRegisterAccessor([42., 43., 44., 45.], dtype=float32)

getRegisterCatalogue() → <sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc6569580>

Return the register catalogue with detailed information on all registers.

getScalarRegisterAccessor(userType, registerPathName: str, elementsOffset: int = 0, accessModeFlags: Optional[Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]] = None) → deviceaccess.ScalarRegisterAccessor

Get a ScalarRegisterAccessor object for the given register.

The ScalarRegisterObject allows to read and write registers transparently by using the accessor object like a variable of the type UserType. If needed, the conversion to and from the UserType will be handled by a data converter matching the register description in e.g. a map file.

Parameters:

• userType (type or numpy.dtype) – The userType for the accessor. Can be of any of the numpy.dtype combinations of float, int, 32 or 64-bit. Integers are also supported as signed, unsigned, 8 and 16-bit. E.g. numpy.uint8, or numpy.float32. There are also str, bool.
• registerPathName (str) – The name of the register to read from.
• elementsOffset (int, 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.
• accessModeFlags (list, optional) – A list to specify the access mode. It allows e.g. to enable raw access. See AccessMode documentation for more details. Passing an access mode flag which is not supported by the backend or the given register will raise a NOT_IMPLEMENTED DeviceException.

Examples

Getting a scalar Register Accessor of type int16 from WORD_STATUS:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int16, "ADC/WORD_STATUS")
>>> acc.read()
>>> acc
ScalarRegisterAccessor([32767], dtype=int16)

getTwoDRegisterAccessor(userType, registerPathName: str, numberOfElements: int = 0, elementsOffset: int = 0, accessModeFlags: Optional[Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]] = None) → deviceaccess.TwoDRegisterAccessor

Get a TwoDRegisterAccessor object for the given register.

This allows to read and write transparently 2-dimensional registers. The optional arguments allow to restrict the accessor to a region of interest in the 2D register.

Parameters:

• userType (type or numpy.dtype) – The userType for the accessor. Can be of any of the numpy.dtype combinations of float, int, 32 or 64-bit. Integers are also supported as signed, unsigned, 8 and 16-bit. E.g. numpy.uint8, or numpy.float32. There are also str, bool.
• registerPathName (str) – The name of the register to read from.
• numberOfElements (int, optional) –

  Specifies the number of elements per channel to read from the register. 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 omitted 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.

• elementsOffset (int, 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.
• accessModeFlags (list, optional) – A list to specify the access mode. It allows e.g. to enable raw access. See AccessMode documentation for more details. Passing an access mode flag which is not supported by the backend or the given register will raise a NOT_IMPLEMENTED DeviceException.

Examples

Getting a Two-D Register Accessor of type uint8 from DMA; which is 6 elements long and has 4 channels:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getTwoDRegisterAccessor(np.float32, "BOARD/DMA", 0, 0, [])
>>> acc.read()
>>> acc
TwoDRegisterAccessor([[12., 13., 14., 15., 16., 17.],
            [13., 15., 17., 19., 21., 23.],
            [14., 17., 20., 23., 26., 29.],
            [15., 19., 23., 27., 31., 35.]], dtype=float32)

Getting a Two-D Register Accessor of type float64 from register “WORD_CLK_MUX” is 4 elements long.

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getTwoDRegisterAccessor(np.uint8, "BOARD/WORD_CLK_MUX")
>>> acc.read()
>>> acc
TwoDRegisterAccessor([[42, 43, 44, 45]], dtype=uint8)

getVoidRegisterAccessor(registerPathName: str, accessModeFlags: Optional[Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]] = None) → deviceaccess.VoidRegisterAccessor

Get a VoidRegisterAccessor object for the given register.

The VoidRegisterAccessor allows to read and write registers. Getting a read accessor is only possible with the wait_for_new_data flag. This access mode will be rejected for write accessors.

Parameters:

• registerPathName (str) – The name of the register to read from.
• accessModeFlags (list, optional) – A list to specify the access mode. It allows e.g. to enable wait_for_new_data access. See AccessMode documentation for more details. Passing an access mode flag which is not supported by the backend or the given register will raise a NOT_IMPLEMENTED DeviceException.

Examples

Sending interrupts per Void Accessor:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/push.dmap")
>>> dev = da.Device("SHARED_RAW_DEVICE")
>>> dev.open()
>>> dev.activateAsyncRead()
>>>
>>> writeAcc = dev.getOneDRegisterAccessor(np.int32, "MODULE1/TEST_AREA")
>>> arr1to10 = np.array(range(1, 11), dtype=np.int32)
>>> writeAcc.set(arr1to10)
>>> writeAcc.write()
>>>
>>> readAcc = dev.getOneDRegisterAccessor(
>>>     np.int32, "MODULE1/TEST_AREA_PUSH", 0, 0, [da.AccessMode.wait_for_new_data])
>>> readAcc.read() # first read is always non-blocking
  OneDRegisterAccessor([ 1  2  3  4  5  6  7  8  9 10]], dtype=int32)
>>> # double values of writeAccReg
>>> writeAcc += arr1to10
>>> writeAcc.write()
>>> interruptAcc = dev.getVoidRegisterAccessor("DUMMY_INTERRUPT_2")
>>> interruptAcc.write() # interrupt needed, otherwise second read would be blocking
>>>
>>> readAcc.read()
  OneDRegisterAccessor(
      [ 2,  4,  6,  8, 10, 12, 14, 16, 18, 20], dtype=int32)

open(aliasName: Optional[str] = None) → None

Open a Device

This method has to be called after the initialization to get accessors. It can also re-opens a Device after close() was called. If no aliasName was giving during initialization, it is needed by this method.

Parameters:aliasName (str, optional) – The Device alias/name in the dmap file for the hardware

Examples

Opening a Device without aliasName, as it has already been supplied at creation:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()

Opening a Device with aliasName, as it has non been supplied at creation:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device()
>>> dev.open("CARD_WITH_MODULES")

read(registerPath: str, dtype: np.dtype = <class 'numpy.float64'>, numberOfWords: int = 0, wordOffsetInRegister: int = 0, accessModeFlags: Sequence[AccessMode] = None) → np.ndarray | np.number

Inefficient convenience function to read a register without obtaining an accessor. If no dtype is selected, the returned ndarray will default to np.float64. If numberOfWords is not specified, it takes the maximm minus the offset. If numberOfChannels is not specified, it takes the maximm possible.

write(registerPath: str, dataToWrite: np.ndarray | np.number, wordOffsetInRegister: int = 0, accessModeFlags: Sequence[AccessMode] = None) → None

Inefficient convenience function to write a register without obtaining an accessor. If no dtype is selected, the returned ndarray will default to np.float64.

class deviceaccess.GeneralRegisterAccessor

Bases: abc.ABC

This is a super class to avoid code duplication. It contains methods that are common for the inheriting accessors.

Note

As all accessors inherit from numpy’s ndarray, the behaviour concerning slicing and mathematical operations is simimlar. Result accessors share the attributes of the left operand, hence they are shallow copies of it. This leads to functionality that is not available in the C++ implementation. Please refer to the examples below.

Examples

Slicing and writing. Operations are shared with the original accessor.

>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> originAcc = dev.getTwoDRegisterAccessor(np.int32, "BOARD/DMA")
>>> originAcc.set(7)
>>> originAcc.write() # all elements are now 7.
>>> print(originAcc)
    [[7 7 7 7 7 7]
    [7 7 7 7 7 7]
    [7 7 7 7 7 7]
    [7 7 7 7 7 7]]
>>> channels = originAcc.getNChannels()
>>> elementsPerChannel = originAcc.getNElementsPerChannel()
>>> print(channels, elementsPerChannel) # there are 4 channels, each with 6 elements
    4 6
>>> slicedAcc = originAcc[:][1] # the second element of every channel
>>> slicedAcc.set(21) # set these to 21
>>> slicedAcc.write()
>>> print(originAcc) # originAcc is changed as well
    [[ 7  7  7  7  7  7]
     [21 21 21 21 21 21]
     [ 7  7  7  7  7  7]
     [ 7  7  7  7  7  7]]

Results from mathematical operations are shallow copies of the left operand.

>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> oneAcc = dev.getScalarRegisterAccessor(np.uint32, "ADC/WORD_CLK_CNT")
>>> oneAcc.set(72)
>>> oneAcc.write() # oneAcc is now 72
>>> otherAcc = dev.getScalarRegisterAccessor(np.uint32, "ADC/WORD_CLK_CNT_1")
>>> otherAcc.set(47)
>>> otherAcc.write() #  otherAcc is now 47.
>>> resultAcc = oneAcc + otherAcc # resultAcc's numpy buffer is now 119
>>> print(resultAcc)
    [119]
>>> resultAcc.write() # write() will also write into the register of oneAcc
>>> oneAcc.read()
>>> print(oneAcc)
    [119]
>>> otherAcc.read() # the buffer's and registers of the right operand are not touched
>>> print(otherAcc)
    [47]
>>> resultAcc.getName() # the resultAcc is a shallow copy of the left operand
    '/ADC/WORD_CLK_CNT'

dataValidity() → <sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18730>

Return current validity of the data.

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

getAccessModeFlags() → Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]

Returns the access modes flags, that were given at the initialization of the accessor.

Examples

Getting the access modes flags of a OneDRegisterAccessor with the wait_for_new_data flag:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(
  np.int32, "MODULE1/TEST_AREA_PUSH", 0, 0, [da.AccessMode.wait_for_new_data])
>>> acc.getAccessModeFlags()
  [da.AccessMode.wait_for_new_data]

getDescription() → str

Returns the description of this variable/register, if there is any.

Examples

Getting the description of a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.getDescription()
  ''

getId() → <sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a4a5e0>

Obtain unique ID for the actual implementation of this TransferElement.

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 to difference calls to Device.getScalarRegisterAccessor() will have a different ID even when accessing the very same register.

Examples

Getting the name of a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.getId()
  <_da_python_bindings.TransferElementID at 0x7f5298a8f400>

getName() → str

Returns the name that identifies the process variable.

Examples

Getting the name of a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.getName()
  '/ADC/WORD_CLK_CNT_1'

getUnit() → str

Returns the engineering unit.

If none was specified, it will default to “n./a.”

Examples

Getting the engineering unit of a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.getUnit()
  'n./a.'

getValueType() → Union[int8, uint8, int16, uint16, int32, uint32, int64, uint64, float, double, boolean, string]

Returns the type for the userType of this transfer element, that was given at the initialization of the accessor.

Examples

Getting the userType of a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.getValueType()
  numpy.int32

getVersionNumber() → <sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc6952f10>

Returns the version number that is associated with the last transfer (i.e. last read or write). See VersionNumber for details.

Examples

Getting the version number of a OneDRegisterAccessor:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(
  np.int32, "MODULE1/TEST_AREA_PUSH", 0, 0, [da.AccessMode.wait_for_new_data])
>>> acc.getVersionNumber()
  <_da_python_bindings.VersionNumber at 0x7f52b5f8a740>

interrupt() → None

Place a thread interrupted exception on the read queue of this accessor, so the thread currently waiting in a blocking read() will terminate. May only be called for accessors with AccessMode.wait_for_new_data.

isInitialised() → bool

Return if the accessor is properly initialized.

It is initialized if it was constructed passing the pointer to an implementation, it is not initialized if it was constructed only using the placeholder constructor without arguments. Which should currently not happen, as the registerPath is a required argument for this module, but might be true for other implementations.

Examples

Getting the initialized status of a OneDRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(
    np.int32, "MODULE1/TEST_AREA_PUSH", 0, 0, [da.AccessMode.wait_for_new_data])
>>> acc.isInitialised()
    True

isReadOnly() → bool

Check if transfer element is read only, i.e. it is readable but not writeable.

Examples

Getting the readOnly status of a OneDRegisterAccessor:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(
  np.int32, "MODULE1/TEST_AREA_PUSH", 0, 0, [da.AccessMode.wait_for_new_data])
>>> acc.isReadOnly()
  True

isReadable() → bool

Check if transfer element is readable.

It throws an exception if you try to read and isReadable() is not True.

Examples

Getting the readable status of a OneDRegisterAccessor:

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(
  np.int32, "MODULE1/TEST_AREA_PUSH", 0, 0, [da.AccessMode.wait_for_new_data])
>>> acc.isReadable()
  True

isWriteable() → bool

Check if transfer element is writeable.

It throws an exception if you try to write and isWriteable() is not True.

Examples

Getting the writeable status of a OneDRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(
  np.int32, "MODULE1/TEST_AREA_PUSH", 0, 0, [da.AccessMode.wait_for_new_data])
>>> acc.isReadable()
  False

read() → 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 is complete.

Examples

Reading from a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.read()
>>> acc
  ScalarRegisterAccessor([99], dtype=int32)

readLatest() → 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.

readNonBlocking() → 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 indicated 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.

setDataValidity(valid=<sphinx.ext.autodoc.importer._MockObject object>) → None

Associate a persistent data storage object to be updated on each write operation of this ProcessArray.

If no persistent data storage as associated previously, the value from the persistent storage is read and send to the receiver.

Note

A call to this function will be ignored, if the TransferElement does not support persistent data storage (e.g. read-only variables or device registers)

Parameters:valid (DataValidity) – DataValidity.ok or DataValidity.faulty

write() → bool

Write the data to device.

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

Examples

Writing to a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> reference = [199]
>>> acc.set(reference)
>>> acc.write()
  ScalarRegisterAccessor([199], dtype=int32)

writeDestructively() → bool

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

The application must expect the user buffer of the TransferElement to contain undefined data after calling this function.

class deviceaccess.NumpyGeneralRegisterAccessor(channels, elementsPerChannel, userType, accessor, accessModeFlags: Optional[Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]] = None)

Bases: deviceaccess.GeneralRegisterAccessor

read() → 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 is complete.

Examples

Reading from a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.read()
>>> acc
  ScalarRegisterAccessor([99], dtype=int32)

readLatest() → None

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.

readNonBlocking() → None

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

set(value) → None

Set the user buffer to the given value.

The value shape has to match the accessor, any mismatch will throw an exception. Different types will be converted to the userType of the accessor.

Parameters:value (numpy.array or compatible type) – The new content of the user buffer.

Examples

Setting a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.read()
    ScalarRegisterAccessor([74678], dtype=int32)
>>> acc.set([-23])
>>> acc.write()
    ScalarRegisterAccessor([-23], dtype=int32)

Setting a OneDRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getOneDRegisterAccessor(np.int32, "BOARD/WORD_CLK_MUX")
>>> acc.read()
    OneDRegisterAccessor([342011132 958674678 342011132 958674678], dtype=int32)
>>> acc.set([1, 9, 42, -23])
>>> acc.write()
    OneDRegisterAccessor([  1,   9,  42, -23], dtype=int32)

Setting a TwoDRegisterAccessor

>>> import deviceaccess as da
>>> dda.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getTwoDRegisterAccessor(np.int32, "BOARD/DMA")
>>> acc.read()
TwoDRegisterAccessor([[  0   4  16  36  64 100]
        [  0   0   0   0   0   0]
        [  1   9  25  49  81 121]
        [  0   0   0   0   0   0]], dtype=int32)
>>> channels = acc.getNChannels()
>>> elementsPerChannel = acc.getNElementsPerChannel()
>>> reference = [
>>>     [i*j+i+j+12 for j in range(elementsPerChannel)] for i in range(channels)]
>>> acc.set(reference)
>>> acc.write()
TwoDRegisterAccessor([[12, 13, 14, 15, 16, 17],
            [13, 15, 17, 19, 21, 23],
            [14, 17, 20, 23, 26, 29],
            [15, 19, 23, 27, 31, 35]], dtype=int32)

write() → None

Write the data to device.

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

Examples

Writing to a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> reference = [199]
>>> acc.set(reference)
>>> acc.write()
  ScalarRegisterAccessor([199], dtype=int32)

writeDestructively() → None

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

The application must expect the user buffer of the TransferElement to contain undefined data after calling this function.

class deviceaccess.OneDRegisterAccessor(userType, accessor, accessModeFlags: Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>])

Bases: deviceaccess.NumpyGeneralRegisterAccessor

Accessor class to read and write registers transparently by using the accessor object like a vector of the type UserType.

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

Note

As all accessors inherit from GeneralRegisterAccessor, please refer to the respective examples for the behaviour of mathematical operations and slicing with accessors.

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 using the operators.

getNElements() → int

Return number of elements/samples in the register.

class deviceaccess.ScalarRegisterAccessor(userType, accessor, accessModeFlags: Optional[Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]] = None)

Bases: deviceaccess.NumpyGeneralRegisterAccessor

Accessor class to read and write scalar registers transparently by using the accessor object like a vector of the type UserType.

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

Note

As all accessors inherit from GeneralRegisterAccessor, please refer to the respective examples for the behaviour of mathematical operations and slicing with accessors.

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 using the operators.

readAndGet() → numpy.number

Convenience function to read and return a value of UserType.

Examples

Reading and Getting from a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> dev.write("ADC/WORD_CLK_CNT_1", 37)
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.readAndGet()
  37

setAndWrite(newValue: numpy.number, versionNumber: Optional[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc6952f10>] = None) → None

Convenience function to set and write new value.

Parameters:

• newValue (numpy.number and compatible types) – The content that should be written to the register.
• versionNumber (VersionNumber, optional) – The versionNumber that should be used for the write action.

Examples

Reading and Getting from a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.setAndWrite(38)
>>> acc.readAndGet()
  38

writeIfDifferent(newValue: numpy.number, versionNumber: Optional[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc6952f10>] = None, validity: <sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18730> = <sphinx.ext.autodoc.importer._MockObject object>) → None

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

The given version number is only used in case the value differs.

Parameters:

• newValue (numpy.number and compatible types) – The contentthat should be written to the register.
• versionmNumber (VersionNumber, optional) – The versionNumber that should be used for the write action.

Examples

Reading and Getting from a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.setAndWrite(38)
>>> acc.writeIfDifferent(38) # will not write

class deviceaccess.TwoDRegisterAccessor(userType, accessor, accessModeFlags: Optional[Sequence[<sphinx.ext.autodoc.importer._MockObject object at 0x7f1fc7a18d00>]] = None)

Bases: deviceaccess.NumpyGeneralRegisterAccessor

Accessor class to read and write registers transparently by using the accessor object like a 2D array of the type UserType.

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

Note

As all accessors inherit from GeneralRegisterAccessor, please refer to the respective examples for the behaviour of mathematical operations and slicing with accessors.

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 using the operators.

getNChannels() → int

Return number of channels.

getNElementsPerChannel() → int

Return number of elements/samples per channel.

class deviceaccess.VoidRegisterAccessor

Bases: deviceaccess.GeneralRegisterAccessor, numpy.ndarray

Accessor class to read and write void registers transparently by using the accessor object..

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 using the operators.

read() → 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 is complete.

Examples

Reading from a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> acc.read()
>>> acc
  ScalarRegisterAccessor([99], dtype=int32)

readLatest() → 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.

readNonBlocking() → 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 indicated 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.

write() → bool

Write the data to device.

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

Examples

Writing to a ScalarRegisterAccessor

>>> import deviceaccess as da
>>> da.setDMapFilePath("deviceInformation/exampleCrate.dmap")
>>> dev = da.Device("CARD_WITH_MODULES")
>>> dev.open()
>>> acc = dev.getScalarRegisterAccessor(np.int32, "ADC/WORD_CLK_CNT_1")
>>> reference = [199]
>>> acc.set(reference)
>>> acc.write()
  ScalarRegisterAccessor([199], dtype=int32)

writeDestructively() → bool

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

The application must expect the user buffer of the TransferElement to contain undefined data after calling this function.

deviceaccess.getDMapFilePath() → str

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

deviceaccess.setDMapFilePath(dmapFilePath: str) → None

Set the location of the dmap file.

The library will parse this dmap file for the device(alias) lookup. Relative or absolute path of the dmap file (directory and file name).

Examples

Setting the location of the dmap file

>>> import deviceaccess as da
>>> da.setDMapFilePath('deviceInformation/exampleCrate.dmap')
>>> dmap_path = da.getDMapFilePath()
>>> print(dmap_path)
deviceInformation/exampleCrate.dmap