Getting Started with WaveForms SDK

WaveForms SDK is a set of tools provided within the WaveForms installation that are used to develop custom software solutions that use Digilent Test and Measurement devices. The WaveForms SDK API is available in several programming languages, making it easy to use across many different platforms.

Normally, Test and Measurement devices are controlled and configured through the WaveForms application with a personal computer. Such a setup may be impossible in a given context, or an amount of automated signal measurement may be required beyond what WaveForms' scripting environment allows. WaveForms SDK gives the necessary tools to help craft the perfect solution for any problem.

This guide demonstrates the usage of some basic instruments and presents some patterns to help develop your own application. It is written with Python in mind, but users of other languages will still find it useful to illustrate the principles of working with the SDK.

Inventory

SDK Overview

WaveForms SDK is included with WaveForms and is installed alongside the application. The SDK is available to use with C/C++, C#, Python, and Visual Basic through a dynamic library (a module that contains data that can be used by other applications).

Another important file is the one that contains the definition of all constants. If you want to use the SDK from Python, this file is a Python module, while for C/C++ applications, the constants are defined in a header file.

Working code examples for each supported programming language are provided with the SDK and may be found at the following locations:

  • Windows 32-bit: C:\Program Files\Digilent\WaveFormsSDK\samples
  • Windows 64-bit: C:\Program Files (x86)\Digilent\WaveFormsSDK\samples
  • Linux: /usr/share/digilent/waveforms/samples
  • macOS: /Applications/WaveForms.app/Contents/Resources/SDK/samples

Workflow

1. Importing the Constants and Loading the Dynamic Library

The WaveForms SDK Python functions use C-compatible data types, so along with the dynamic library and the module containing the constants, you will also need the ctypes module, which is installed together with Python by default.

As the first step of your project import the dwfconstants.py file to your project directory (it is located among the sample codes, in the py folder), then load the necessary modules and the dynamic library.

Optional: Importing the Constants from the Project Directory

Alternatively, you can import the dwfconstants.py file from the project directory, simplifying this way the code. Copy the file into your project, then import it like any other module, but include the directory name in the import path.

2. Connecting the Test & Measurement Device

The next step is to “open” your device. If you have only one Test & Measurement device connected, the simplest method is to ask the WaveForms SDK to connect to the first available device.

Optional: Connecting to a Specific Device

If you have multiple Test & Measurement devices connected, opening the first available device might not be the best option. If you want to open a specific type of device, use the function presented to the right.

Optional: Error Checking

You can check for errors, to know whether your device was connected to or not.

3. Using Instruments

Oscilloscope

3.1 Initialize the Scope

Before measuring with the oscilloscope, it must be set up. Change the values to fit your needs.

3.2 Measure a Voltage

You can measure voltages, like with the Voltmeter instrument in WaveForms.

3.3 Record a Signal

The most important feature of the oscilloscope is, that it can record signals. The recorded voltages can be stored in a list.

3.4 Reset the Scope

After usage, reset the oscilloscope to the default settings.

Optional: Triggering

Before recording a signal, you might want to set up triggering. Set the trigger parameters to fit your needs.

You can define custom trigger source names, to make the usage of the function easier.

Waveform Generator

3.1 Generate a Signal

Use the waveform generator to generate different signals.

You can define custom function names, to make the usage of the function easier.

3.2 Reset the Wavegen

After usage, reset the wavegen to the default settings.

Power Supplies
3.1 Analog Discovery Supplies

The Analog Discovery has only fixed supplies, so just a limited number of functions are available.

3.1 Analog Discovery 2 and Analog Discovery Studio Supplies

These devices have variable positive and negative supplies, so a voltage level can also be set.

3.1 Analog Discovery Pro 3X50 and Digital Discovery Supplies

Devices with digital supplies have only positive voltage supplies with a variable voltage level between 1.2 and 3.3 Volts.

3.1 Analog Discovery Pro 5250 6V Power Supply

You can set not only the voltage for the 6V power supply on the Analog Discovery 5250, but also the current limit, up to 1A.

3.1 Analog Discovery Pro 5250 25V Power Supplies

The positive and negative isolated 25V power supplies are similar to the 6V one, but with a maximum current limit of 500mA.

Optional: Power Supplies Wrapper Function

To make the usage of the above functions easier, you can create a wrapper function, which is able to call the function you need.

3.2 Reset the Supplies

After usage, reset the supplies to the default settings.

Digital Multimeter - Only on ADP5250

3.1 Initialize the DMM

Before measuring with the digital multimeter, it must be enabled.

3.2 Measure With the DMM

This function was not tested.

You can use the digital multimeter to measure AC, or DC voltages (in Volts), with an input impedance of 10MΩ, or 10GΩ, low (<100mA), or high AC, or DC currents (up to 10A), resistance, conductance, temperature and more, with automatic, or fixed range.

3.3 Reset the DMM

After usage, reset the instrument to the default settings.

Logic Analyzer

3.1 Initialize the Logic Analyzer

Before measuring with the logic analyzer, it must be set up. Change the values to fit your needs.

3.2 Record Logic Signals

Record logic signals in a list of lists, then select the one specific for the required DIO line.

3.3 Reset the Logic Analyzer

After usage, reset the logic analyzer to the default settings.

Optional: Triggering

Before recording a signal, you might want to set up triggering. Set the trigger parameters to fit your needs.

Pattern Generator

3.1 Generate Logic Signals

Configure the pattern generator to generate logic signals.

You can use a DIO line for pattern generation only if the respective line is configured as input and set to LOW state by the static I/O instrument (these are the default settings for all lines).

You can define custom function and trigger source names, to make the usage of the function easier.

3.2 Reset the Pattern Generator

After usage, reset the pattern generator to the default settings.

Static I/O

3.1 Set Pins As Input Or As Output

Each digital pin of the Test & Measurement device can be used only as input, or as output at a time. The default settings for each line are input states.

3.2 Get Pin State

Read the state of a DIO line with the following code snippet:

3.3 Set Pin State

To set the state of a DIO line, it must be set as output!

3.4 Reset the Static I/O

After usage, reset the instrument to the default settings.

Optional: Limiting DIO Channel Current

Test & Measurement devices with digital supplies (the Digital Discovery and the Analog Discovery Pro 3×50) also have options to limit the output current of a DIO channel.

This function was not tested.

Optional: DIO Channel Pull Up/Down

Test & Measurement devices with digital supplies (the Digital Discovery and the Analog Discovery Pro 3×50) also have options to pull a DIO channel up, or down.

This function was not tested.

Protocol: UART

3.1 Initialize the Interface

Before using a communication interface, it must be initialized by setting the communication parameters to the desired values.

3.2 Receive Data

Use the function to the right to read data on an initialized UART interface.

3.3 Send Data

Use the function to the right to send data on an initialized UART interface to another device.

3.4 Reset the Interface

After usage, reset the instrument to the default settings.

Protocol: SPI

3.1 Initialize the Interface

Before using a communication interface, it must be initialized by setting the communication parameters to the desired values.

3.2 Receive Data

Use the function to the right to read data on an initialized SPI interface.

3.3 Send Data

Use the function to the right to send data on an initialized SPI interface to another device.

3.4 Exchange Data

You might want to receive data from a slave device while you are sending commands to it. In this case the data exchanging function can be used.

3.5 Spy on SPI communication

If two other devices, a master and a slave, are communicating using the initialized communication interface, the Test & Measurement device can be used to spy on this communication (record both incoming and outgoing data).

This function was not tested.

3.6 Reset the Interface

After usage, reset the instrument to the default settings.

Protocol: I2C

3.1 Initialize the Interface

Before using a communication interface, it must be initialized by setting the communication parameters to the desired values.

3.2 Receive Data

Use the function to the right to read data on an initialized I2C interface.

3.3 Send Data

Use the function to the right to send data on an initialized I2C interface to another device.

3.4 Exchange Data

You might want to receive data from a slave device while you are sending commands to it. In this case the data exchanging function can be used.

3.5 Spy on I2C communication

If two other devices, a master and a slave, are communicating using the initialized communication interface, the Test & Measurement device can be used to spy on this communication (record both incoming and outgoing data).

This function was not tested.

3.6 Reset the Interface

After usage, reset the instrument to the default settings.

The code snippets above present basic functionality of some instruments. For more possibilities (advanced features and more instruments) check the documentation of the WaveForms SDK and the available sample scripts.

4. Disconnecting the Device

When your script is exiting, it is very important to close the opened connections, to make the device available for other software (like the WaveForms application).

Creating Modules

To avoid copying several hundred lines of code into every project, you can create Python modules from the functions controlling the instruments. These modules then can be imported in your project.

To create a module, create a new file with the desired name and the extension *.py, then copy the respective functions into that file. Don't forget to also import the dwfconstants file into every module.

Place your modules in a separate folder, name this folder (for example WF_SDK is a good name as it is suggestive), then copy the dwfconstants.py file into the same folder.

Don't forget to correct the import path of the dwfconstants.py file, if you import it from the project directory. The name of the parent directory (WF_SDK), followed by a dot must be added before the file name.

If you import the file from the installation folder, no changes have to be made.

You can download the archive containing the module and some test files here.

Open the drop-downs below to see the content of the created modules.

Device Control - device.py

Oscilloscope Control - scope.py

Waveform Generator Control - wavegen.py

Power Supplies Control - supplies.py

Digital Multimeter Control - supplies.py

This module contains untested functions.

Logic Analyzer Control - logic.py

Pattern Generator Control - pattern.py

Static I/O Control - static.py

This module contains untested functions.

Protocol: UART Interface - protocol/uart.py

Protocol: SPI Interface - protocol/spi.py

This module contains untested functions.

Protocol: I2C Interface - protocol/i2c.py

This module contains untested functions.

As the created function set will be used as a module, an initializer is needed, to let the text editors recognize the module. This file contains only the description of the module and imports every file in the module, to make the functions accessible. The created file has to be named __init__.py and must be put in the module directory.

After the file is created, your module will be recognized: the module name in the text editor will be colored (this depends on the editor) and if you hover the mouse on the module name, the module description appears.

Remember, that any submodule (the protocol folder in this case) also needs initialization:

Testing

Copy your module folder (WF_SDK in this case) into the project directory, then create a new Python script. Import the necessary modules, then use your functions to control the Test & Measurement device.

In the drop-downs below, several examples and a project template will be presented.

Note: The example using the oscilloscope and the waveform generator won't work on devices without analog I/O capability (Digital Discovery).

Note: Name your test scripts “test_testname.py”. This will be important if you want to install the module as a package.

Empty Project Template

Fill in this template. Be creative, use any instrument in any configuration.

Using the Oscilloscope and the Waveform Generator

This example generates a sinusoidal signal on a wavegen channel, then records it on a scope channel. Connect the respective channels together on your device!

Using the Logic Analyzer and the Pattern Generator

This example generates a PWM signal on a DIO line and reads it back with the logic analyzer. As the same line is used both as input and as output, no external connections have to be made.

Using the Static I/O and the Power Supplies

Connect LEDs and series resistors to each DIO channel of your device. Use the positive, or the digital power supply to provide current to the LEDs, then use the Static I/O instrument to sink the currents (turn the LEDs on/off).

Controlling the Pmod CLS and the Pmod MAXSonar with UART

Connect the UART interface of both Pmods to your Test & Measurement device as presented below. Pay special attention to the jumpers on the Pmod CLS. Use the positive, or the digital power supply to provide current to the Pmods, then receive and send data with the protocol instrument.

Controlling the Pmod CLS and the Pmod ALS with SPI

Connect the SPI interface of both Pmods to your Test & Measurement device as presented below. Pay special attention to the jumpers on the Pmod CLS. Use the positive, or the digital power supply to provide current to the Pmods, then receive and send data with the protocol instrument.

Controlling the Pmod CLS and the Pmod TMP2 with I2C

Connect the I2C interface of both Pmods to your Test & Measurement device as presented below. Pay special attention to the jumpers on the Pmod CLS. Use the positive, or the digital power supply to provide current to the Pmods, then receive and send data with the protocol instrument.

Installing the Package

Once you completed the package, you might want to install it, like other Python packages and use it on new projects as well. To do so, you must create some additional files in the project folder.

First, exclude the test scripts from the final package. Create a file named MANIFEST.in, with the content: 

global-exclude test_*

The installer needs the list of dependencies to install your package. Specify this list on a file called requirements.txt: 

setuptools==58.1.0
wheel==0.37.1

Finally, create a README.md file with the description of your package, then create the installer. The installer is the file named setup.py, with the following content: 

from setuptools import setup
 
with open("README.md", "r") as f:
    long_description = f.read()
 
setup(
   name = "WF_SDK",
   version = "1.0",
   description = "This module realizes communication with Digilent Test & Measurement devices",
   license = "MIT",
   long_description = long_description,
   author = "author_name",
   author_email = "author_email_address",
   url = "https://digilent.com/reference/test-and-measurement/guides/waveforms-sdk-getting-started",
   packages = ["WF_SDK", "WF_SDK.protocol"],
)

Once the necessary files are created, open a terminal, go to the project folder and install your package with the following command: 

pip install .

Alternatively, you can install the package from the GitHub repository, with the command: 

pip install git+https://github.com/Digilent/WaveForms-SDK-Getting-Started#egg=WF_SDK

Note: Use “pip3” instead of “pip”, if you are using Python 3.

Other Programming Languages

Realizing the same package in other programming languages is also possible. To check the C++ version of the package and some test programs, follow this link.

Next Steps

For more guides on how to use your Digilent Test & Measurement Device, return to the device's Resource Center, linked from the Test and Measurement page of this wiki.

For more information on the WaveForms SDK visit the WaveForms SDK Resource Center.

For more information on WaveForms visit the WaveForms Reference Manual.

For technical support, please visit the Test and Measurement section of the Digilent Forums.