dwfpy Design
The design of the dwfpy package consists of three layers: Python bindings, low-level API, and high-level API.
Bindings
The dwfpy bindings give you raw access to the C API of the DWF DLL. In order to provide a natural look-and-feel while working in Python, the following API changes have been made:
The naming of the DWF API has been adapted to match Python naming conventions.
The DWF function API has been declared using the ctypes CFUNCTYPE prototypes, which allow you to pass Python types such as int, instead of ctypes types such as c_int.
Error handling is performed automatically, i.e. the C functions return value is checked and an exception is thrown when appropriate.
Function return values are directly returned as a scalar or tuple.
For instance, the DWF C API to get the minimum and maximum offset voltage of an analog-out channel is:
int FDwfAnalogOutNodeOffsetInfo(HDWF hdwf, int idxChannel, AnalogOutNode node, double *pMin, double *pMax);
When working with the dwfpy bindings, it can be used as follows:
import dwfpy as dwf
import dwfpy.bindings as dwfb
with dwf.Device() as device:
min_offset, max_offset = dwfb.dwf_analog_out_node_offset_info(device.handle, 0, dwfb.ANALOG_OUT_NODE_CARRIER)
Typically, you do not work with the dwfpy bindings. Instead, use the low-level or high-level API.
Low-Level API
The dwfpy low-level API is designed to map the bindings to a more structured API.
Functional units of the device have been grouped into objects.
Channels and nodes are abstracted as collections, using a dict-like API.
For instance, the DWF C API to set the offset voltage of the analog_out channel 1 (arbitary waveform generator) is:
int FDwfAnalogOutNodeOffsetSet(HDWF hdwf, int idxChannel, AnalogOutNode node, double vOffset);
When working with the dwfpy low-level API, it can be used as follows:
import dwfpy as dwf
with dwf.Device() as device:
device.analog_output.channels[0].nodes[dwf.AnalogOutputNode.CARRIER].offset = 1.23
High-Level API
The dwfpy high-level API is designed to perform multiple common actions with a single line of Python code.
For instance, to start channel 1 of the arbitary waveform generator to output a sine-wave, using a frequency of 1kHz and an amplitude of 1Vpp, you would write:
import dwfpy as dwf
with dwf.Device() as device:
device.analog_output['ch1'].setup(function='sine', frequency=1e3, amplitude=1, start=True)