1. Instrument Driver Programming Basics
What is an instrument driver?
An instrument driver is a set of software routines that control a programmable instrument. Each routine corresponds to a programmatic operation such as configuring, reading from, writing to, and triggering the instrument. Instrument drivers simplify instrument control and reduce test program development time by eliminating the need to learn the programming protocol for each instrument.
The Structure of an Instrument Driver
All instrument drivers have the same basic hierarchy. Instrument drivers are written from low-level components that are used to program the instrument. These low-level calls are combined to form application functions that simplify programming the instrument. These application functions present only the common instrument features and capabilities, whereas low-level functions are organized into a modular assortment containing all the instrument configuration and measurement capabilities. The component functions fit into six categories: Initialize, Configuration, Action/Status, Data, Utility, and Close. Below is a model structure of a program written with an instrument driver.
This model represents the basic programming structure of a program written with an instrument driver.
All instrument drivers have an Initialize function. It is the first instrument driver function called and establishes communication with the instrument. Optionally, it can also perform instrument identification query and reset operations. Initialization also places the instrument in a specific state, usually its default power on state.
Configuration functions are collections of software routines that configure the instrument to perform a desired operation. The number of Configuration functions depends on the complexity of the instrument. After the Configuration functions are called, the instrument is ready to take measurements.
The Action/Status category contains two types of functions. Action functions cause the instrument to initiate or terminate test and measurement operations such as arming the triggering system or generating a stimulus. Action functions differ from Configuration functions in that they do not change instrument settings; instead, they order the instrument to carry out an action based on its current configuration settings.
Status functions return the current status of the instrument or of pending operations. Specific routines in this category and the actual operations they perform are at the discretion of the instrument driver developer, and are usually created as required by other functions.
Data functions include calls to transfer data to or from the instrument. Examples of Data function operations include reading a measured value or waveform from a measurement instrument, and downloading waveforms or digital patterns to a source instrument. Specific routines in this category depend on the instrument.
Utility functions perform a variety of operations auxiliary to the most-used instrument driver calls. These functions include the majority of the template instrument driver calls (described below) such as reset, self-test, revision, and error query, and may include other custom routines such as calibration or storing/recalling instrument configurations.
All instrument drivers include a Close function. The Close function terminates the software connection to the instrument and deallocates system resources used during that instrument session.
2. Getting Started with NI-SCOPE
The NI-SCOPE instrument driver is the application programming interface (API) that allows interactive programming of your National Instruments high-speed digitizer in LabVIEW, LabWindows/CVI, Microsoft Visual C++, and Microsoft Visual Basic. All information in this section, along with more in-depth details on programming with the NI-SCOPE instrument driver, can be found in the NI High-Speed Digitizers Help at ni.com/manuals.
NI-SCOPE provides the same functionality and example programs in all supported programming environments. For simplicity, the included LabVIEW examples are referred to in this document, but equivalent examples using other development environments also ship with NI-SCOPE. The following steps illustrate the structure of a typical signal acquisition program using a National Instruments high-speed digitizer and NI-SCOPE:
Step 1: Initialize
C Function: niScope_Init
Step 2: Configure
After you have opened a session with the high-speed digitizer, you need to configure the hardware settings. The most common configuration settings for a high-speed digitizer are vertical, horizontal, and trigger settings.
The Configure Vertical function call adjusts the vertical range of each or both digitizer channels. This is the full-scale (peak-to-peak) voltage range at the digitizer input. For example, a vertical range of 10V means the digitizer can measure a signal between -5V to +5V. For optimum resolution, choose the smallest vertical range that still contains the entire range of the input signal.
niScope Configure Vertical.vi
C Function: niScope_ConfigureVertical
The Configure Vertical function also configures the vertical offset, channel coupling (AC or DC), and probe attenuation settings.
The Configure Horizontal function call adjusts the sample rate and the min record length of all channels on your digitizer. Sample rate is the frequency at which digitized samples are stored specified in samples per second. The min record length is the minimum number of samples to store for each record in the acquisition. The total acquisition time is equal to the min record length divided by the sample rate (samples/sec).
niScope Configure Horizontal Timing.vi
C Function: niScope_ConfigureHorizontalTiming
The Configure Horizontal function call also configures the reference position parameter, which determines the number of pretrigger versus post trigger samples acquired.
There are several kinds of triggering available for use with NI-SCOPE and NI high-speed digitizers. The niScope Configure Trigger Edge.vi is a polymorphic VI with the different options for triggering.
niScope Configure Trigger.vi
C Function: niScope_ConfigureTrigger
For complete descriptions of the different triggering options, refer to the Triggering section of the High-Speed Digitizer Development library or chapter 3 of the NI High-Speed Digitizers Help at ni.com/manuals.
The Auto Setup function can be used to automatically set the vertical range, sample rate, minimum record length, and the trigger level.
niScope Auto Setup.vi
C Function: niScope_AutoSetup
The Auto Setup function senses the input signal and automatically configures the instrument settings. This function is best used in simple applications and as a tool for less experienced programmers to get started.
Step 3: Acquire Data
After the digitizer is configured for your application, you may start the acquisition. Acquiring data can be separated into two parts, initiating the acquisition and fetching the data from the digitizer's onboard memory.
The Initiate Acquisition function arms the board to begin taking data after the trigger has occurred. If immediate triggering has been configured, then the board starts acquiring data immediately.
C Function: niScope_InitiateAcquisition
The Fetch function transfers the acquired data from the digitizer memory to your program. The Fetch function is also a polymorphic VI, which allows you to select between single waveform or multiple waveforms. You can also select the format of data in which you want to fetch the waveform.
niScope Fetch Cluster.vi
C Function: niScope_Fetch
In LabVIEW, NI-SCOPE has different functions for single waveform and multiple waveform acquisitions. Fetch is used with single waveform acquisitions and Multi Fetch is used with multiple waveform acquisitions. For more information on the Fetch functions refer to the NI High-Speed Digitizers Help at ni.com/manuals.
The Read function combines the initiate acquisition, wait for complete, and retrieve data calls into one function. It does not return until the entire operation is complete.
niScope Read Cluster.vi
C Function: niScope_Read
Although Fetch functions require an addition function to initiate an acquisition, they offer several advantages to the Read function, including freeing the host computer processor for other operations while you wait for the digitizer to acquire data. For more information on the Read and Fetch functions refer to the NI High-Speed Digitizers Help at ni.com/manuals.
Step 4: Error Checking
niScope Error Message.vi
C Function: niScope_error_message
For additional information on error handling, consult your NI-SCOPE Function Reference Help file or your NI-SCOPE VI Reference Help, which is installed with the NI-SCOPE instrument driver.
Step 5: Close
C Function: niScope_Close
It is important to close the session because it releases any temporary buffers created to transfer data between the digitizer and the host computer memory.
Putting it all Together
The following diagram illustrates a flow diagram of a typical acquisition. This section includes a brief overview of basic programming with NI-SCOPE and National Instruments high-speed digitizers. For a more complete overview of all the functions and available features refer to the NI High-Speed Digitizers Help and the Getting Started Guide for your device at ni.com/manuals.
NI-SCOPE Basic Signal Acquisition Flowchart
[+] Enlarge Image
NI-SCOPE Getting Started LabVIEW Example with Auto Setup
[+] Enlarge Image
NI-SCOPE LabVIEW Programming with Configure Vertical, Horizontal, and Trigger Functions
3. Signal Measurements with NI-SCOPE
National Instruments NI-SCOPE instrument driver for high-speed digitizers includes over 50 built-in measurements and analysis functions. Waveform measurements offer another method for fetching data from a National Instruments high-speed digitizer/oscilloscope, but instead of time-domain waveforms, the results are scalar or array measurements. Scalar measurements refer to calculations such as rise time and frequency, which take the time-domain data and produce a single value, while array measurements transform the time-domain data into a new waveform, such as an FFT amplitude spectrum.
Scalar measurements are measurements on waveforms that produce a single value result. For example, you use scalar measurements to find voltage peak-to-peak, frequency, and overshoot. For a complete list of scalar measurements refer to the NI High-Speed Digitizers Help at ni.com/manuals.
The Fetch Measurement function call is used to acquire the scalar measurement that you request.
niScope Fetch Measurement.vi
C Function: niScope_FetchMeasurement
For some scalar measurements such as rise time, fall time and duty cycle positive, reference levels can be customized to give you control over your scalar measurements. Reference levels are high, low, and mid-range values configured in terms of the percentage of the waveform you acquire. By default, the low level is 10% of the total acquisition, the mid level is 50%, and the high level falls after 90% of the desired samples have been acquired. You can customize the percentages used for reference levels by changing the reference level attributes. In LabVIEW, this is done with property nodes.
The following diagram depicts the flow of a typical acquisition and scalar measurement.
Scalar Measurement Flowchart
More information on scalar measurements can be found in the NI High-Speed Digitizers Help at ni.com/manuals.
Array measurements are measurements on waveforms that result in an array of values such as FFT amplitude spectrum. For a complete list of array measurements refer to the NI High-Speed Digitizers Help at ni.com/manuals.
Fetch Array Measurement
The Fetch Array Measurement function call is used to retrieve the array of measurement data that you request.
niScope Fetch Array Measurement Cluster.vi
C Function: niScope_FetchArrayMeasurement
The following diagram shows the flow of a typical acquisition with array measurements.
Array Measurement Flowchart
More information on array measurements can be found in the NI High-Speed Digitizers Help at ni.com/manuals.