The DwfDevice class

The DwfDevice class represents a previously opened Digilent Waveforms device. It is the entry point to all useful functionality of the Digilent Waveforms device.

Using the DwfDevice class

To obtain a DwfDevice instance you first need to initialize a DwfLibrary instance. The DwfLibrary can then be used to obtain a DwfDevice, either by using the DeviceControl.open() method or by using the pydwf.utilities.openDwfDevice() convenience function.

After the program is done using a device, it should be closed. This can be done explicitly, via the DwfDevice.close() method, or implicitly, by using the DwfDevice as a so-called context manager for itself. The latter method is often preferable, since it guarantees that the device will be closed even when an exception occurs while using it:

from pydwf import DwfLibrary
from pydwf.utilities import openDwfDevice

dwf = DwfLibrary()

with openDwfDevice(dwf) as device:
     # When we leave the 'with' statement, the device is guaranteed to be closed.
     print("Trigger sources supported by this device:", device.triggerInfo())

     # This is true even if an exception is raised inside the 'with' statement's body:
     raise RuntimeError("yikes!")

After obtaining a DwfDevice, you can use the dozen or so methods it provides. These methods are documented as part of the DwfDevice class in the next section.

Twelve attributes are provided to access particular sub-APIs of a DwfDevice instance. Depending on the type of task that you are using your Digilent Waveforms device for, one or several of these attributes will be your main handle to configure instruments and to send or receive data:

analogIn provides a multi-channel oscilloscope;
analogOut provides a multi-channel analog signal generator;
analogIO provides voltage, current, and temperature monitoring and control;
analogImpedance provides measurement of impedance and other quantities;
digitalIn provides a multi-channel digital logic analyzer;
digitalOut provides a multi-channel digital pattern generator;
digitalIO provides static digital I/O functionality;
protocol.uart provides UART protocol configuration, send, and receive functionality;
protocol.spi provides SPI protocol configuration, send, and receive functionality;
protocol.i2c provides I²C protocol configuration, send, and receive functionality;
protocol.can provides CAN protocol configuration, send, and receive functionality;
protocol.swd provides SWD protocol configuration, send, and receive functionality.

DwfDevice reference

class DwfDevice

The DwfDevice represents a single Digilent Waveforms test and measurement device.

Attention

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

Use DeviceControl.open() or pydwf.utilities.openDwfDevice() to obtain a valid DwfDevice instance.

The main test and measurement functionality of a Digilent Waveforms device is provided as multiple sub-interfaces (instruments, protocols, and measurements). To access those, use one of the twelve attributes described below.

DwfDevice attributes

analogIn

Provides access analog input (oscilloscope) functionality.

Type:: AnalogIn

analogOut

Provides access to the analog output (waveform generator) functionality.

Type:: AnalogOut

analogIO

Provides access to the analog I/O (voltage source, monitoring) functionality.

Type:: AnalogIO

analogImpedance

Provides access to the analog impedance measurement functionality.

Type:: AnalogImpedance

digitalIn

Provides access to the dynamic digital input (logic analyzer) functionality.

Type:: DigitalIn

digitalOut

Provides access to the dynamic digital output (pattern generator) functionality.

Type:: DigitalOut

digitalIO

Provides access to the static digital I/O functionality.

Type:: DigitalIO

protocol.uart

Provides access to the UART protocol functionality.

Type:: ProtocolUART

protocol.can

Provides access to the CAN protocol functionality.

Type:: ProtocolCAN

protocol.spi

Provides access to the SPI protocol functionality.

Type:: ProtocolSPI

protocol.i2c

Provides access to the I²C protocol functionality.

Type:: ProtocolI2C

protocol.swd

Provides access to the SWD protocol functionality.

Type:: ProtocolSWD

DwfDevice properties and methods

property dwf: DwfLibrary

Return the DwfLibrary instance that was used to create (open) this DwfDevice instance.

This is useful if we have a DwfDevice, but we need its DwfLibrary.

Returns:: The DwfLibrary that was used to create (open) this DwfDevice instance.
Return type:: DwfLibrary

property digitalUart: ProtocolUART: Old attribute-style access to the device’s UART functionality.

Warning

This attribute is obsolete. Use protocol.uart instead.

property digitalSpi: ProtocolSPI: Old attribute-style access to the device’s SPI functionality.

Warning

This attribute is obsolete. Use protocol.spi instead.

property digitalI2c: ProtocolI2C: Old attribute-style access to the device’s I²C functionality.

Warning

This attribute is obsolete. Use protocol.i2c instead.

property digitalCan: ProtocolCAN: Old attribute-style access to the device’s CAN functionality.

Warning

This attribute is obsolete. Use protocol.can instead.

property digitalSwd: ProtocolSWD: Old attribute-style access to the device’s SWD functionality.

Warning

This attribute is obsolete. Use DwfDevice.protocol.swd instead.

close() → None

Close the device.

This method should be called when access to the device is no longer needed.

Once this method returns, the DwfDevice can no longer be used.

Raises:: DwfLibraryError – The device cannot be closed.

autoConfigureSet(auto_configure: int) → None

Enable or disable the autoconfiguration setting of the device.

When this setting is enabled (the default), any change to an instrument setting is automatically transmitted to the Digilent Waveforms hardware device, without the need for an explicit call to the instrument’s configure() method.

This adds a small amount of latency to every Set() method; just as much latency as calling the corresponding configure() method explicitly after the Set() method would add.

Autoconfiguration is enabled by default, and there is little reason to turn it off unless the user program wants to make frequent changes to many settings at once between measurements.

With value 3, configuration will be applied dynamically, without stopping the instrument.

Parameters:

auto_configure (int) –

The new autoconfiguration setting.

Possible values for this option:

0 — disable
1 — enable
3 — dynamic

Raises:

DwfLibraryError – The value cannot be set.

autoConfigureGet() → int

Return the autoconfiguration setting of the device.

Returns:

The current autoconfiguration setting.

Possible values for this option:

0 — disable
1 — enable
3 — dynamic

Return type:

int

Raises:

DwfLibraryError – The value cannot be retrieved.

reset() → None

Reset all device and instrument settings to default values.

The new settings are applied immediately if autoconfiguration is enabled.

Raises:: DwfLibraryError – The device cannot be reset.

enableSet(enable: bool) → None

Enable or disable the device.

Parameters:: enable (bool) – True for enable, False for disable.
Raises:: DwfLibraryError – The device’s enabled state cannot be set.

triggerInfo() → list[DwfTriggerSource]

Return the available trigger source options for the global trigger bus.

Refer to the section on triggering for more information.

The four main instruments (AnalogIn, AnalogOut, DigitalIn, and DigitalOut) can be configured to start their operation (data acquisition for the In instruments; signal generation for the Out instruments) immediately after some event happens. This is called triggering.

Each of the instruments can be configured independently to use any of the trigger sources available inside the device. This method returns a list of all trigger sources that are available to each of the instruments.

Returns:: A list of available trigger sources.
Return type:: list[DwfTriggerSource]
Raises:: DwfLibraryError – The list of supported trigger sources cannot be retrieved.

triggerSet(pin_index: int, trigger_source: DwfTriggerSource) → None

Configure the trigger I/O pin with a specific trigger source option.

Digilent Waveforms devices have dedicated digital I/O pins that can be used either as trigger inputs or trigger outputs. Use this method to select which line of the global triggering bus is driven on those pins, e.g. to trigger some external device or to monitor the Digilent Waveforms device’s internal trigger behavior.

Pass DwfTriggerSource.None_ to disable trigger output on the pin. This is the default setting, and the appropriate value to use when the intention is to have some external trigger signal drive the pin.

Refer to the section on triggering for more information.

Parameters:

pin_index (int) – The trigger pin to configure.
trigger_source (DwfTriggerSource) – The trigger source to select.

Raises:

DwfLibraryError – The trigger source cannot be set.

triggerGet(pin_index: int) → DwfTriggerSource

Return the selected trigger source for a trigger I/O pin.

Refer to the section on triggering for more information.

Parameters:: pin_index (int) – The pin for which to obtain the selected trigger source.
Returns:: The trigger source setting for the selected pin.
Return type:: DwfTriggerSource
Raises:: DwfLibraryError – The trigger source cannot be retrieved.

triggerPC() → None

Generate a trigger pulse on the PC trigger line.

The generated pulse will trigger any instrument that is configured with trigger source DwfTriggerSource.PC, and currently armed (i.e., waiting for a trigger).

Raises:: DwfLibraryError – The PC trigger line cannot be pulsed.

triggerSlopeInfo() → list[DwfTriggerSlope]

Return the supported trigger slope options.

Returns:: A list of supported trigger slope values.
Return type:: list[DwfTriggerSlope]
Raises:: DwfLibraryError – The trigger slope options cannot be retrieved.

paramSet(parameter: DwfDeviceParameter, value: int) → None

Set a device parameter value.

Device parameters are settings of a specific DwfDevice. Refer to the device parameters section for more information.

This method sets a device parameter value of a currently opened DwfDevice.

Warning

The device parameter values are not checked to make sure they correspond to a valid value for the current device.

Parameters:

parameter (DwfDeviceParameter) – The device parameter to set.
value (int) – The value to assign to the parameter.

Raises:

DwfLibraryError – The specified device parameter cannot be set.

paramGet(parameter: DwfDeviceParameter) → int

Get a device parameter value.

Device parameters are settings of a specific DwfDevice. Refer to the device parameters section for more information.

Parameters:: parameter (DwfDeviceParameter) – The device parameter to get.
Returns:: The integer value of the parameter.
Return type:: int
Raises:: DwfLibraryError – The value of the specified device parameter cannot be retrieved.