pydwf utilities

The pydwf.utilities package provides functionality built on top of the core functionality that is available in the pydwf core package. It provides high-level functions that reflect best-practice implementations for common use-cases of pydwf.

Currently, only a single utility function is provided by the pydwf.utilities module: pydwf.utilities.openDwfDevice(), which is documented below.

Using the pydwf.utilities functionality

To use functionality from the pydwf.utilities package, import the symbols you need from it:

"""Demonstrate use of the openDwfDevice function."""

from pydwf import DwfLibrary
from pydwf.utilities import openDwfDevice

dwf = DwfLibrary()

with openDwfDevice(dwf) as device:
    use_dwf_device(device)

The example above demonstrates the use of the pydwf.utilities.openDwfDevice() function. This function encapsulates a number of core pydwf functions to allow easy selection of devices and device configurations. It is documented below.

pydwf.utilities.openDwfDevice function reference

Open a device identified by its serial number, optionally selecting a preferred configuration.

This is a three-step process:

The first step this function performs is to select a device for opening.

To do this, device enumeration is performed, resulting in a list of all reachable Digilent Waveforms devices.

For this initial enumeration process the enum_filter parameter can be used to only list certain types of devices (for example, only Analog Discovery 2 devices, or Digital Discovery devices). If omitted (the default), all Digilent Waveforms devices will be listed.

Then, if the serial_number_filter parameter is given, the list will be filtered to exclude devices whose serial numbers do not match.

If the list that remains has a single device, this device will be used. If not, a PyDwfError is raised.
The next step is to select a device configuration for the selected device.

For many use cases, the default configuration that provides a balanced tradeoff works fine. If no score_func is provided, this default configuration will be used.

If a score_func parameter is provided, it should be a function (or lambda expression) that takes a single parameter configuration_info, which is a dictionary with DwfEnumConfigInfo keys, and parameters values for a specific device configuration.

The score_func should return None if the configuration is entirely unsuitable, or otherwise a score that reflects the suitability of that particular configuration for the task at hand.

The openDwfDevice method will go through all available device configurations, construct a dictionary of all parameters that describe the configuration, call the score_func with that dictionary as a parameter, and examine the score value it returns. If multiple suitable device configurations are found (i.e., the score_func does not return None), it will select the configuration with the highest score.

This may all sounds pretty complicated, but in practice this parameter is quite easy to define for most common use-cases.

As an example, to select a configuration that maximizes the analog input buffer size, simply use this:
```
from pydwf import DwfEnumConfigInfo
from pydwf.utilities import openDwfDevice

def maximize_analog_in_buffer_size(config_parameters):
    return config_parameters[DwfEnumConfigInfo.AnalogInBufferSize]

with openDwfDevice(dwf, score_func = maximize_analog_in_buffer_size) as device:
    use_device_with_big_analog_in_buffer(device)
```
As a final step, the selected device is opened using the selected device configuration, and the newly instantiated DwfDevice instance is returned.

Note

This method can take several seconds to complete. This long duration is caused by the use of the DeviceEnum.enumerateDevices() method.

Parameters:

dwf (DwfLibrary) – The DwfLibrary used to open the device.
enum_filter (Optional[DwfEnumFilter]) – An optional filter to limit the device enumeration to certain device types. If None, enumerate all devices.
serial_number_filter (str) – The serial number filter used to select a specific device. A device is considered to match if its 12-digit serial number ends with the serial number filter string (case is ignored).
device_id_filter (int) – The device ID filter to use.
device_version_filter (int) – The device version filter to use.
score_func (Optional[Callable[[Dict[DwfEnumConfigInfo, Any]], Optional[Any]]]) – A function to score a configuration of the selected device. See the description above for details.

Returns:

The DwfDevice created as a result of this call.

Return type:

DwfDevice

Raises:

PyDwfError – could not select a unique candidate device, or no usable configuration detected.