Device enumeration functionality

The device enumeration functionality provides a way to enumerate accessible Digilent Waveforms devices, i.e., probe the USB bus and the network to find all Digilent Waveforms devices that can potentially be used.

The enumeration functionality also provides functionality to get basic information for all devices found, such as the device type, hardware revision, and serial number.

Lastly, the enumeration functionality allows user programs to examine device configurations, which provide a way to optimize the Digilent Waveforms device for a certain task by allocating resources such as buffer memory to certain instruments.

Using the device enumeration functionality

To use the device enumeration functionality you first need to initialize a DwfLibrary instance. The device enumeration functionality can then be accessed via its deviceEnum attribute, which is an instance of the DeviceEnumeration class:

from pydwf import DwfLibrary

dwf = DwfLibrary()

# Enumerate all Digilent Waveforms devices and return the count.
device_count = dwf.deviceEnum.enumerateDevices()

print("Number of Digilent Waveforms devices found:", device_count)

Alternatives to the device enumeration functionality

For most users, there is little reason to use the device enumeration API directly. Consider the following alternatives:

From the command line, it is easy to obtain a list of all Digilent Waveforms devices and their configurations like this:
```
python -m pydwf list -c
```
For Python scripts that want to select a specific device by serial number, or want to select a specific device configuration while opening the device to maximize the capabilities of a certain instrument (for example, to open the device with the largest possible AnalogIn or AnalogOut sample buffer sizes), consider using the pydwf.utilities.openDwfDevice() convenience function.

DeviceEnumeration reference

class DeviceEnumeration

The DeviceEnumeration class provides access to the device enumeration functionality of a DwfLibrary.

Attention

Users of pydwf should not create instances of this class directly.

It is instantiated during initialization of a DwfLibrary and subsequently assigned to its public deviceEnum attribute for access by the user.

enumerateDevices(enum_filter: DwfEnumFilter | None = None) → int

Build an internal list of available Digilent Waveforms devices and return the count of devices found.

This method must be called before using other DeviceEnumeration methods described below, because they obtain information about the enumerated devices from the internal device list that is built by this method.

Note

This method can take several seconds to complete.

Parameters:: enum_filter (Optional[DwfEnumFilter]) – Specify which devices to enumerate. If None, enumerate all devices.
Returns:: The number of Digilent Waveforms devices detected.
Return type:: int
Raises:: DwfLibraryError – The Digilent Waveforms devices cannot be enumerated.

enumerateStart(enum_filter: DwfEnumFilter | None = None) → None

Start device enumeration.

Note

This method is non-blocking (i.e., fast).

Note

This method was added in DWF version 3.17 to provide an alternative to the blocking behavior of the enumerateDevices() method.

Parameters:: enum_filter (Optional[DwfEnumFilter]) – Specify which devices to enumerate. If None, enumerate all devices.
Returns:: The number of Digilent Waveforms devices detected.
Return type:: int
Raises:: DwfLibraryError – The Digilent Waveforms devices cannot be enumerated.

enumerateStop() → int

Stop device enumeration.

This should be called after a preceding enumerateStart() invocation.

A enumerateStart() call followed by a enumerateStop() call essentially performs the same function as a single enumerateDevices() call, and takes approximately the same amount of time.

The advantage of using the Start/Stop methods is that the application can do useful work while the devices are being enumerated in a background thread.

Note

This method can take several seconds to complete.

Note

This method was added in DWF version 3.17.

Returns:: The number of Digilent Waveforms devices detected.
Return type:: int
Raises:: DwfLibraryError – The Digilent Waveforms devices cannot be enumerated.

enumerateInfo(device_index: int, options: str) → None

Get info of the current device.

It is not clear what this method does; the underlying DWF FDwfEnumInfo function is missing from the documentation.

An inquiry about this was made on the Digilent forum but the reply did not go into sufficient detail on the functionality provided.

Parameters:

device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
options (str) – The function or format of this parameter is not known.

Todo

Figure out what this method does.

Note

This method was added in DWF version 3.17.

Raises:: DwfLibraryError – The operation could not be performed.

deviceType(device_index: int) → Tuple[int, int]

Return the device ID and version (hardware revision) of the selected Digilent Waveforms device.

Note

This method returns the integer values as reported by the ‘FDwfEnumDeviceType()’ function and does not cast them to the DwfDeviceID and DwfDeviceVersion enumeration types.

This is done to prevent unknown devices from raising an exception.

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: A tuple of the DwfDeviceID and DwfDeviceVersion integer values of the selected Digilent Waveforms device.
Return type:: Tuple[int, int]
Raises:: DwfLibraryError – The device type and version cannot be retrieved.

deviceIsOpened(device_index: int) → bool

Check if the specified Digilent Waveforms device is already opened by this or any other process.

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: True if the Digilent Waveforms device is already opened, False otherwise.
Return type:: bool
Raises:: DwfLibraryError – The open state of the Digilent Waveforms device cannot be determined.

userName(device_index: int) → str

Retrieve the username of the selected Digilent Waveforms device.

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: The username of the Digilent Waveforms device, which is a short name indicating the device type (e.g., “Discovery2”, “DDiscovery”).
Return type:: str
Raises:: DwfLibraryError – The username of the Digilent Waveforms device cannot be retrieved.

deviceName(device_index: int) → str

Retrieve the device name of the selected Digilent Waveforms device.

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: The device name of the Digilent Waveforms device, which is a long name denoting the device type (e.g., “Analog Discovery 2”, “Digital Discovery”).
Return type:: str
Raises:: DwfLibraryError – The device name of the Digilent Waveforms device cannot be retrieved.

serialNumber(device_index: int) → str

Retrieve the 12-digit, unique serial number of the enumerated Digilent Waveforms device.

Parameters:

device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).

Returns:

The 12 hex-digit unique serial number of the Digilent Waveforms device.

The ‘SN:’ prefix returned by the underlying C API function (for most devices) is discarded.

Return type:

str

Raises:

DwfLibraryError – The serial number of the Digilent Waveforms device cannot be retrieved.
PyDwfError – The serial number of the device is not 12 characters long.

enumerateConfigurations(device_index: int) → int

Build an internal list of detected configurations for the specified Digilent Waveforms device.

This method must be called before using the configInfo() method described below, because that method obtains information from the internal device configuration list that is built by this method.

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: The count of configurations of the Digilent Waveforms device.
Return type:: int
Raises:: DwfLibraryError – The configuration list of the Digilent Waveforms device cannot be retrieved.

configInfo(config_index: int, info: DwfEnumConfigInfo) → int | str

Return information about a Digilent Waveforms device configuration.

Parameters:

config_index (int) – Zero-based index of the previously enumerated configuration (see the enumerateConfigurations() method described above).
info (DwfEnumConfigInfo) – Selects which configuration parameter to retrieve.

Note

For most values of the info parameter, this method returns an integer, but for some values it returns a string. Refer to the DwfEnumConfigInfo documentation for details.

This explains the somewhat unusual Union[int, str] return type of this method.

Returns:: The value of the selected configuration parameter, of the selected configuration.
Return type:: Union[int, str]
Raises:: DwfLibraryError – The requested configuration information of the Digilent Waveforms device cannot be retrieved.

analogInChannels(device_index: int) → int

Return the analog input channel count of the selected Digilent Waveforms device.

Warning

This method is obsolete.

Use either of the following instead:

method configInfo() to obtain the DwfEnumConfigInfo.AnalogInChannelCount configuration value;
AnalogIn.channelCount()

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: The number of analog input channels of the Digilent Waveforms device.
Return type:: int
Raises:: DwfLibraryError – The analog-in channel count of the Digilent Waveforms device cannot be retrieved.

analogInBufferSize(device_index: int) → int

Retrieve the analog input buffer size of the selected Digilent Waveforms device.

Warning

This method is obsolete.

Use either of the following instead:

method configInfo() to obtain the DwfEnumConfigInfo.AnalogInBufferSize configuration value;
AnalogIn.bufferSizeGet()

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: The analog input buffer size of the selected Digilent Waveforms device.
Return type:: int
Raises:: DwfLibraryError – The analog-in buffer size of the Digilent Waveforms device cannot be retrieved.

analogInBits(device_index: int) → int

Retrieve the analog input bit resolution of the selected Digilent Waveforms device.

Warning

This method is obsolete.

Use AnalogIn.bitsInfo() instead.

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: The analog input bit resolution of the selected Digilent Waveforms device.
Return type:: int
Raises:: DwfLibraryError – The analog-in bit resolution of the Digilent Waveforms device cannot be retrieved.

analogInFrequency(device_index: int) → float

Retrieve the analog input sample frequency of the selected Digilent Waveforms device.

Warning

This method is obsolete.

Use AnalogIn.frequencyInfo() instead.

Parameters:: device_index (int) – Zero-based index of the previously enumerated Digilent Waveforms device (see the enumerateDevices() method).
Returns:: The analog input sample frequency of the selected Digilent Waveforms device, in samples per second.
Return type:: float
Raises:: DwfLibraryError – The analog input sample frequency of the Digilent Waveforms device cannot be retrieved.

property dwf

Return the DwfLibrary instance of which we are an attribute.

Returns:: The DwfLibrary instance.
Return type:: DwfLibrary