This is an old revision of the document!
Overview
WaveForms™ provides an interface that allows users to interact with Digilent Analog Design hardware, such as the Analog Discovery™ and Electronics Explorer™. While the WaveForms application offers a refined graphical interface, the WaveForms SDK provides access to a public application programming interface (API) that gives users the ability to create custom PC applications. This WaveForms SDK manual describes the main components and architecture of the WaveForms system and details each function contained in the WaveForms API. The SDK package also offers examples demonstrating how to identify, connect to, and control analog hardware devices.
1 The System
The WaveForms system is comprised of multiple components. The most visible component is the WaveForms Application; a suite of graphical instrument panels that give full access to the analog and digital instruments in the connected hardware. The WaveForms application uses the WaveForms Runtime to control all signal generation and acquisition. The WaveForms Runtime is comprised of the DWF Dynamic Library and several configuration files. This library is located in:
- Windows in System Directory: C: \Windows\System32\dwf.dll
- Linux: /usr/lib/libdwf.so.x.x.x
The static library is located on Windows in the install path:
- Windows 32bit: C:\Program Files\Digilent\WaveFormsSDK\lib\x86
- Windows 64bit: C:\Program Files (x86)\Digilent\WaveFormsSDK\lib\x64
The C header file is located in:
- Windows: C:\Program Files\Digilent\WaveFormsSDK\inc
- Windows 64bit: C:\Program Files (x86)\Digilent\WaveFormsSDK\inc
- Linux: /usr/local/include/digilent/waveforms
Working code examples are provided with the SDK to demonstrate basic use of each API function set. You can find samples in the installation directory, which are located here:
- Windows 32bit: C:\Program Files\Digilent\WaveFormsSDK\samples
- Windows 64bit: C:\Program Files (x86)\Digilent\WaveFormsSDK\samples
- Linux: /usr/local/share/digilent/waveforms/samples
The DWF Library uses the Adept Runtime, which provides basic communication with the targeted hardware instruments (i.e. Analog Discovery and Electronics Explorer). Although the Adept Runtime is an integral part of the WaveForms System, knowledge of its structure is not required to write custom applications.
The requirements for Linux version are the libusb-1.0-0, Digilent Adept Runtime, and the included FTDI drivers:
$ sudo apt-get install linusb-1.0-0 digilent.adept.runtime_#/ftdi.drivers_# $ sudo bash install.sh digilent.adept.runtime_# $ sudo bash install.sh
1.1 The API
Everything needed to write custom applications is included in the WaveForms SDK, which provides the header/library files and documentation to access the API for the DWF Library. A custom application must properly link to these files to make the appropriate API function calls. Every function in the WaveForms public API is declared in the dwf.h header file.
Basic usage of the WaveForms API can be broken down into the following steps:
- Call enumeration functions to discover connected hardware devices.
- Call FDwfDeviceOpen function to establish a connection to specific hardware device.
- Call function to enable instrument within hardware device.
- Call functions to configure instrument and acquire/generate signals.
- Call function to disable instrument.
- Call FDwfDeviceClose function to disconnect from device.
There are nine main groups of API functions, each named with different prefixes:
Main Groups of API Functions | Instrument Function | Prefix |
Device Enumeration | Controls the enumeration of connected and supported devices. | DwfEnum |
Device Control | Controls opening and closing specific devices. | DwfDevice |
AnalogIn (Oscilloscope) | Acquires samples from each enabled channel synchronously. | DfwAnalogIn |
AnalogOut (Arbitrary Waveform Generator) | Drives signals from each channel independently. | DfwAnalogOut |
AnalogIO | Acquires and drives various analog signals. | DfwAnalogIO |
DigitalIn (Logic Analyzer) | Acquires samples from digital I/O pins. | DfwDigitalIn |
DigitalOut (Pattern Generator) | Drives digital I/O signals. | DfwDigitalOut |
DigitalIO | Acquires and drives digital I/O signals. | DfwDigitalIO |
System | Obtain basic system information that is instrument and device independent. | DfwGet |
Each instrument is directly controlled using three types of functions in the API:
API Functions | Instrument Function | Example |
Reset function | This function resets all of the instrument parameters to default values. | FDwfAnalogInReset |
FDwfAnalogOutReset | ||
FDwfDigitalIOReset | ||
Configure function | This function configures and/or starts the instrument. | FDwfAnalogInConfigure |
FDwfAnalogOutConfigure | ||
FDwfDigitalIOConfigure | ||
Status function | This function polls and reads all information from the instrument. | FDwfAnalogInStatus |
FDwfAnalogOutStatus | ||
FDwfDigitalIOStatus |
Note: Although there are multiple “Status” functions for each instrument, these functions are the only ones that actually read data from the device.
There are a number of type definitions and corresponding constants in the dwf.h include file. The majority of them are used as parameters. When a hardware device is opened, a handle is returned (HDWF), which is used to access and finally close in all instrument API functions.
1.2 Calling API Functions
The API functions are C style and return a Boolean value: TRUE if the call is successful, FALSE if unsuccessful. This Boolean value is an integer type definition, not the standard c-type bool. In general, the API functions contain variations of the following parameters:
Parameters | Parameter Function |
*Info | Returns detailed information about the parameter support for the instrument (i.e., minimum/maximum values, supported modes, etc.) |
*Set | Sets an instrument parameter. When the AutoConfigure is enabled (by default), the instrument is reconfigured and stopped. |
*Get | Gets the actual instrument parameter. Use this function to get the actual set value. For instance an arbitrary voltage offset is set and get returns the real DAC output value. |
*Status | Returns the parameter value from the device. |
The API functions won’t fail when a parameter pointer is NULL or when a setting (*Set) parameter value is out of limits. To verify the actual setting value, use the *Get API return the actual value.
The supported discrete parameters are retrieved in bit field value. To decode the capabilities of the device use the IsBitSet macro. int fsfilter; FDwfAnalogInChannelFilterInfo(h, &fsfilter) if(IsBitSet(fsfilter, filterAverage)){ FDwfAnalogInChannelFilterSet(hdwf, 0, filterAverage) }
System
FDwfGetLastError(DWFERC * pdwferc) |
Parameters: |
- pdwferc - Variable to receive error code. |
The function above is used to retrieve the last error code in the calling process. The error code is cleared when other API functions are called and is only set when an API function fails during execution. Error codes are declared in dwf.h:
API Error Codes | Error Code Definition |
dwfercNoErc | No error occurred. |
dwfercUnknownError | Call waiting on pending API time out. |
dwfercApiLockTimeout | Call waiting on pending API time out. |
dwfercAlreadyOpened | Device already opened. |
dwfercNotSupported | Device not supported. |
dwfercInvalidParameter0 | Parameter 0 was invalid in last API call. |
dwfercInvalidParameter1 | Parameter 1 was invalid in last API call. |
dwfercInvalidParameter2 | Parameter 2 was invalid in last API call. |
dwfercInvalidParameter3 | Parameter 3 was invalid in last API call. |
FDwfGetLastErrorMsg(char szError[512]) |
Parameters: |
- szError - Pointer to buffer to receive error string. |
The function above is used to retrieve the last error message. This may consist of a chain of messages, separated by a new line character, that describe the events leading to the failure.
FDwfGetVersion(char szVersion[32]) |
Parameters: |
- szVersion - Pointer to buffer to receive version string. |
The function above is used to retrieve the version string. The version string is composed of major, minor, and build numbers (i.e. “2.0.19”).
3 Device Enumeration
The FDwfEnum functions are used to discover all connected, compatible devices.
FDwfEnum(ENUMFILTER enumfilter, int * pnDevice) |
Parameters: |
- enumfilter – Filter value to be used for device enumeration. Use the enumfilterAll constant to discover all compatible devices. |
- pnDevice – Integer pointer to return count of found devices by reference. |
Calling the function above will build an internal list of detected devices filtered by the enumfilter parameter. The function above must be called before using other FDwfEnum functions because they obtain information about enumerated devices from this list identified by the device index.
FDwfEnumDeviceType(int idxDevice, DEVID* pDeviceId, DEVVER* pDeviceRevision) |
Parameters: |
- idxDevice – Index of the enumerated device for which to return the type and revision. |
- pDeviceId – Variable to return the device id. |
- pDeviceRevision – Pointer to DEVVER instance to return the device revision by reference. |
The function above is used to return the device ID and version ID.
FDwfEnumDeviceIsOpened(int idxDevice, BOOL* pfIsUsed) |
Parameters: |
- idxDevice – Index of the enumerated device. |
- pfIsUsed – Pointer to variable to receive Boolean indicating if the device is in use. |
The function above is used to retrieve a Boolean specifying if a device is already opened by this, or any other process.
FDwfEnumUserName(int idxDevice, char szUserName[32]) |
Parameters |
- idxDevice – Index of the enumerated device. |
- szUserName – Pointer to character array to return the user name string by reference. |
The function above is used to retrieve the user name of the enumerated device.
FDwfEnumDeviceName(int idxDevice, char szDeviceName[32]) |
Parameters: |
- idxDevice – Index of the enumerated device. |
- szDeviceName – Pointer to character array to return the device name by reference. |
The function above is used to retrieve the device name of the enumerated device.
FDwfEnumSN(int idxDevice, char szSN[32]) |
Parameters: |
- idxDevice – Index of the enumerated device. |
- szSN – Pointer to character array to return the serial number by reference. |
The function above is used to retrieve the 12-digit, unique serial number of the enumerated device.
4 Device Control
FDwfDeviceOpen(int idxDevice, HDWF *phdwf) |
Parameters: |
- idxDevice – Index of the enumerated device. |
- phdwf – Pointer to HDWF variable to receive opened interface handle by reference. |
The function above opens a device identified by the enumeration index and retrieves a handle. To automatically enumerate all connected devices and open the first discovered device, use index -1.
FDwfDeviceClose(HDWF hdwf) |
Parameters: |
- hdwf – Interface handle to be closed. |
The function above is used to close an interface handle when access to the device is no longer needed. Once the function above has returned, the specified interface handle can no longer be used to access the device.
FDwfDeviceCloseAll() |
Parameters: None. |
The function above is used to close all opened devices by the calling process. It does not close all devices across all processes.
FDwfDeviceAutoConfigureSet(HDWF hdwf, BOOL fAutoConfigure) |
Parameters: |
- hdwf – Interface handle. |
- fAutoConfigure– Value for this option: TRUE if enabled, FALSE if disabled. |
The function above enables or disables the AutoConfig setting for a specific device. When this setting is enabled, the device is automatically configured every time an instrument parameter is set. For example, when AutoConfigure is enabled, FDwfAnalogOutConfigure does not need to be called after FDwfAnalogOutRunSet. This adds latency to every Set function; just as much latency as calling the corresponding Configure function directly afterward.
FDwfDeviceAutoConfigureGet(HDWF hdwf, BOOL* fAutoConfigure) |
Parameters: |
- hdwf – Interface handle. |
- fAutoConfigure– Pointer to variable to receive the current value of this option. |
The function above returns the AutoConfig setting in the device. See the function description for FDwfDeviceAutoConfigureSet for details on this setting.
DwfDeviceReset(HDWF hdwf) |
Parameters: |
- hdwf – Interface handle. |
The function above resets and configures all device and instrument parameters to default values.
FDwfDeviceTriggerInfo(HDWF hdwf, int* pfstrigsrc) |
Parameters: |
- hdwf – Interface handle. |
- pfstrigsrc – Variable to receive the supported trigger sources. |
The function above returns the supported trigger source options for the global trigger bus. They are returned (by reference) as a bit field. This bit field can be parsed using the IsBitSet Macro. Individual bits are defined using the TRIGSRC constants in dwf.h.
The global trigger bus allows multiple instruments to trigger each other. These trigger source options are:
Trigger Source Options | Trigger Source Function |
---|---|
trigsrcNone | The trigger pin is high impedance, input. This is the default setting. |
trigsrcPC | Trigger from PC, this can be used to synchronously start multiple instruments. |
trigsrcDetectorAnalogIn | Trigger detector on analog in channels. |
trigsrcDetectorDigitalIn | Trigger on digital input channels. |
trigsrcAnalogIn | Trigger on device instruments, these output high when running. |
trigsrcDigitalIn | Trigger on device instruments, these output high when running. |
trigsrcDigitalOut | Trigger on device instruments, these output high when running. |
trigsrcAnalogOut1 | Trigger on device instruments, these output high when running. |
trigsrcAnalogOut2 | Trigger on device instruments, these output high when running. |
trigsrcAnalogOut3 | Trigger on device instruments, these output high when running. |
trigsrcAnalogOut4 | Trigger on device instruments, these output high when running. |
trigsrcExternal1 | External trigger signal. |
trigsrcExternal2 | External trigger signal. |
trigsrcExternal3 | External trigger signal. |
trigsrcExternal4 | External trigger signal. |
FDwfDeviceTriggerSet(HDWF hdwf, int idxPin, TRIGSRC trigsrc) |
Parameters: |
- hdwf – Interface handle. |
- idxPin – External trigger, I/O pin index. |
- trigsrc – Trigger source to set. |
The function above is used to configure the trigger I/O pin with a specific TRIGSRC option.
FDwfDeviceTriggerGet(HDWF hdwf, int idxPin, TRIGSRC* ptrigsrc) |
Parameters: |
- hdwf – Interface handle. |
- idxPin - External trigger, I/O pin index. |
- ptrigsrc – Variable to receive the current trigger source. |
The function above returns the configured trigger setting for a trigger I/O pin. The trigger source can be “none”, an internal instrument, or an external trigger.
FDwfDeviceTriggerPC(HDWF hdwf) |
Parameters: |
- hdwf – Interface handle. |
The function above generates one pulse on the PC trigger line.
5 Analog In (Oscilloscope)
The Analog In instrument states:
The states are defined in dwf.h DwfState type.
Ready: Initial state. After FDwfAnalogInConfigure or any FDwfAnalogIn*Set function call goes to this state. With FDwfAnalogInConfigure, reconfigure goes to Configure state.
Configure: The needed configurations are performed and auto trigger is reset.
Prefill: Prefills the buffer with samples needed before trigger.
Armed: Waits for the trigger.
Running:
- Single acquisition mode: remains in this state to acquire samples after trigger according trigger position parameter.
- Scan screen and shift modes: remains in this state until configure or any set function of this instrument.
- Record mode: the time period according record length parameter.
Done: Final state.
5.1 Control
FDwfAnalogInReset(HDWF hdwf) |
Parameters: |
- hdwf – Interface handle. |
The function above resets and configures all AnalogIn instrument parameters to default values.
FDwfAnalogInConfigure(HDWF hdwf, BOOL fReconfigure, BOOL fStart) |
Parameters: |
- hdwf – Interface handle. |
- fReconfigure – Configure the device. |
- fStart – Start the acquisition. |
The function above is used to configure the instrument and start or stop the acquisition. To reset the Auto trigger timeout, set fReconfigure to TRUE.
FDwfAnalogInStatus(HDWF hdwf, BOOL fReadData, STS* psts) |
Parameters: |
- hdwf – Interface handle. |
- fReadData – TRUE if data should be read. |
- psts – Variable to receive the acquisition state. |
The function above is used to check the state of the acquisition. To read the data from the device, set fReadData to TRUE. For single acquisition mode, the data will be read only when the acquisition is finished.
Note: To ensure simultaneity of information and data, all of the following AnalogInStatus* functions do not communicate with the device. These functions only return information and data from the last FDwfAnalogInStatus call.