Device control functionality

The device control functionality provides a way to open specific Digilent Waveforms devices, and to close all previously opened devices. It is complemented by the methods provided be the DwfDevice class.

Using the device control functionality

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

from pydwf import DwfLibrary

dwf = DwfLibrary()

# Open the first available Digilent Waveforms device, and close it immediately.
device = dwf.deviceControl.open(-1)
device.close()

Alternatives to the device control functionality

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

  • The DeviceControl.open() method is occasionally useful, but the pydwf.utilities.openDwfDevice() convenience function provides a more powerful alternative.

  • The DeviceControl.closeAll() method is not recommended for general use. Devices can and should be closed individually, either by calling their DwfDevice.close() method explicitly, or by using their context manager feature.

  • The device control API of the underlying C library supports several more functions that work on a previously opened Digilent Waveforms device. In pydwf, these functions are available as methods of the DwfDevice class.

DeviceControl reference

class DeviceControl

The DeviceControl class provides access to the device control 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 deviceControl attribute for access by the user.

open(device_index: int, config_index: int | None = None) → DwfDevice

Open a Digilent Waveforms device identified by the device index, using a specific device configuration index if specified.

Note

This method combines the functionality of the C API functions ‘FDwfDeviceOpen()’ and ‘FDwfDeviceConfigOpen()’ into a single method. The call that is actually made depends on the value of the config_index parameter.

Note

This method can take several seconds to complete.

Parameters:

  • device_index (int) –

    The zero-based index of the previously enumerated device (see the DeviceEnum.enumerateDevices() method).

    To automatically enumerate all connected devices and open the first discovered device, use the value -1 for this parameter.

  • config_index (Optional[int]) – The zero-based index of the device configuration to use (see the DeviceEnum.enumerateConfigurations() method). If None, open the default (first) device configuration.

See also

The pydwf.utilities.openDwfDevice() convenience function provides a more powerful way to select and open a device and, if desired, specify its device configuration.

Returns:

The DwfDevice instance created as a result of this call.

Return type:

DwfDevice

Raises:

DwfLibraryError – The specified device or configuration cannot be opened.

openEx(options: str, separator: str = ',') → DwfDevice

Open a device using options given as a string.

This provides an extended (hence the ‘Ex’ prefix) version of the :py:meth:open method.

The following table lists the options that can be specified in the options string, as listed in the DWF documentation. Not all of these have been verified to work.

Options for the openEx method

option

description

index:#

Connect to device by enumeration 0 based index.

sn:##########

Open by serial number. (The devices will be enumerated).

name:device-name

Open by device name number. (The devices will be enumerated).

config:#

Use configuration (0-based index).

ip:#.#.#.#/host

Connect to network device identified by IP address or hostname.

ip:user:pass*@#.#.#.#/*host

Connect to network device (with username and password).

user:username

Provide username.

pass:password

Provide password.

secure:#

Enable TLS communication encryption (0/1).

Todo

Figure out the precise syntax and semantics of options.

Note

This method was added in DWF version 3.17.

Parameters:

  • options (str) – A string listing options, separated by a ‘separator’ string (see below).

  • separator (str) – The separator string that separating options. Default: a single comma (‘,’).

Returns:

The DwfDevice instance created as a result of this call.

Return type:

DwfDevice

Raises:

DwfLibraryError – The operation could not be performed.

closeAll() → None

Close all Digilent Waveforms devices opened by the calling process.

This method does not close all Digilent Waveforms devices across all processes.

Raises:

DwfLibraryError – The close all operation failed.

property dwf

Return the DwfLibrary instance of which we are an attribute.

Returns:

The DwfLibrary instance.

Return type:

DwfLibrary