PROGRAMMER’S GUIDE AGILENT ACQIRIS INSTRUMENTS
Manual Part Number U1092-90003 Edition E-Rev: O, April 2012 The information in this document is subject to change without notice and may not be construed in any way as a commitment by Agilent Technologies, Inc. While Agilent makes every effort to ensure the accuracy and contents of the document it assumes no responsibility for any errors that may appear. All software described in the document is furnished under license. The software may only be used and copied in accordance with the terms of license.
CONTENTS 1. INTRODUCTION ................................................................................................................................................ 5 1.1. Message to the User ....................................................................................................................................... 5 1.2. Using this Manual .......................................................................................................................................... 5 1.3.
3.10.4. Stopping/Forcing a D1-style Acquisition ............................................................................................. 30 3.10.5. Simultaneous multibuffer Acquisition and Readout (SAR) ................................................................. 31 3.10.6. Analyzer and PeakTDC Autoswitch mode ............................................................................................. 32 3.11. D1-style Data Readout .................................................................
1. Introduction 1.1. Message to the User Congratulations on having purchased an Agilent Technologies Acqiris data conversion product. Acqiris Instruments are high-speed data acquisition modules designed for capturing high frequency electronic signals. To get the most out of the products we recommend that you read the accompanying product User Manual, this Programmer's Guide and the Programmer’s Reference manual carefully.
1.3. Conventions Used in This Manual The following conventions are used in this manual: This icon to the left of text warns that an important point must be observed. WARNING Denotes a warning, which advises you of precautions to take to avoid being electrically shocked. CAUTION Denotes a caution, which advises you of precautions to take to avoid electrical, mechanical, or operational damages. NOTE Denotes a note, which alerts you to important information.
2. Programming Environments & Getting Started Agilent Technologies supplies sample programs as a starting point for the development of user-specific Acqiris applications. For Windows systems there are samples for the Visual C/C++, and MATLAB.
The AqBx Generic functions family contains the following vi’s. The AqBx Examples section contains three very simple cases to show some basic functionality. The AqDx Digitizer functions family contains the following vi’s. The diagram also shows the AqBx tree. These AqBx functions are to be preferred over their AqDx equivalents. 2.2.1. LabView 7.x/8 with old LabView programs If you have an existing LabView program you can still use it or develop further under LabView 8.
2.2.2. AqDx Getting Started VI This VI demonstrates how to use some of the basic components of the AqDx Acqiris Digitizer Driver. It finds and initializes a digitizer, sets the basic parameters according to the controls on the front panel, and then acquires one waveform. Note that the front panel controls should be set to their desired values before the VI is run. 2.2.3. AqDx Example Scope VI This VI presents a basic, interactive virtual oscilloscope using the AqDx Digitizer Driver.
2.2.4. AqDx Accumulated Waveform Example VI This VI demonstrates how to use the Accumulate Waveform function of the Acqiris Digitizer Driver. It finds and initializes a digitizer, sets the basic parameters according to the controls on the front panel, and then acquires and accumulates waveforms as the user requests. Note that the front panel controls should be set to their desired values before the VI is run. 2.3. MATLAB MATLAB is a very powerful environment to analyze and display data.
3. Programming an Acqiris Instrument 3.1. Programming Hints When programming an Acqiris instrument it is important to remember that the Acqiris driver must be freshly loaded (this is usually automatic) by any process that uses the modules. This means that each process starts over with a completely clean view of the system and no knowledge of any previously determined calibration constants or settings. Thus a calibration ought to be done, or loaded, before the modules are used for any acquisitions.
3.2.1.
3.2.4. VXI Identification Instruments in IX20x VXI Carrier modules will also be found by the driver. The resource name will be in the form “VXI[board]::[logical_addr]::INSTR” like “VXI0::1::INSTR”. 3.2.5. PXI VISA & LabViewRT Identification The driver can also be used in the VISA environment. In this case the resource name has the following allowed forms: "PXI::::INSTR" "PXI0::-::INSTR" "PXI0::CHASSIS::SLOT::INSTR" 3.2.6.
The calls to Acqrs_InitWithOptions are needed to obtain the instrumentID’s. The physical digitizers were already initialized when AcqrsD1_multiInstrumentAutoDefine was called. The digitizers within a single MultiInstrument are numbered from 0 to (NbrModulesInInstrument – 1). In Acqiris CC10x compactPCI crates, the module 0 is always closest to the controller slot, i.e. module numbers increase with increasing front panel slot numbers.
The first part of the code above finds and initializes all individual digitizers, as shown in section 3.2.1. Of course, you could also use one of the other 2 methods of identifying individual digitizers. After AcqrsD1_multiInstrDefine has executed successfully, the instrumentID’s in the list idList become unavailable for further operations. You must use the returned multiInstrID to refer to the newly defined MultiInstrument.
3.2.11. Terminating an Application For an orderly shut down of your application, we recommend the following sequence: // Stop the instruments for (long i = 0; i < nbrInstruments; i++) { status = AcqrsD1_stopAcquisition(instrumentID[i]); } Acqrs_closeAll(); Stopping the acquisition of all instruments ensures that there is no further activity that could, for example, generate an interrupt.
Comments: • Channel numbers run from 1 to nbrChannels, not from 0! Segment numbers, however, run from 0 to (nbrSegments – 1). • If the desired sampling interval implies that multiple converters/channel will be needed a call to AcqrsD1_configChannelCombination will be needed before the call to AcqrsD1_configHorizontal. • Specifying more than 1 segment in AcqrsD1_configMemory implies the use of Sequence mode.
3.4. Configuring Averagers 3.4.1. Basic configuration The averagers have 2 operational modes, digitizer and averager, controlled with the function: AcqrsD1_configMode(instrID, mode, 0, 0); The value mode can be set to 0 (digitizer) or 2 (averager). The averager mode uses a number of additional configuration parameters, which describe the requested averaging conditions.
3.4.2. Dithering Dithering reduces the effect of non-ideal differential non-linearity of the analog-to-digital converter, by adding or subtracting small offsets to the input signal. The offset is constant during the acquisition of a single waveform, and then modified to another value during the next waveform.
long nbrPoints = ???; // Should be the ‘current’ number of points! long timeStampLo, timeStampHi, nbrReturnedSamples; double horPos, sampTime; // Read the Waveform directly to the Background buffer double bckGndWform[nbrPoints]; AcqrsD1_readRealWform(instrID, 1, 0, 0, nbrPoints, bckGndWform, &nbrReturnedSamples, &horPos, &sampTime, &timeStampLo, &timeStampHi); // Restore the settings of the averager AcqrsD1_configVertical(instrID, 1, fsr, offset, coupl, bwidth); AcqrsD1_configAvgConfig(instrID, channelNbr,
const long channelNbr = 0; double fsr, offset, threshold, base; threshold = - offset; // place the threshold at the middle of the screen base = threshold - fsr/10.
• Although not shown here, a call to AcqrsD1_configControlIO can be made in order to set a trigger veto time to be respected after the receipt of a Prepare for Trigger signal on a Control I/O connector. This feature is for AP101/AP201 analyzers only. • Also not shown, is a call to the function AcqrsD1_configAvgConfig to set a timeout value for the automatic completion of a segment in case the real trigger never arrives. This feature is for AP101/AP201 analyzers only. 3.5.2.
long channel = 1, gate =2; AcqrsD1_configAvgConfig(instrID, channel, "GateType", &gate); long preSamples = 0, postSamples = 0, maxGates = 1; double threshold = 0.0; // in Volts status = AcqrsD1_configAvgConfig(instrID, channel, "PreSamples", &preSamples); status = AcqrsD1_configAvgConfig(instrID, channel, "PostSamples", &postSamples); status = AcqrsD1_configAvgConfig(instrID, channel, "Threshold", &threshold); status = AcqrsD1_configAvgConfig(instrID, channel, "NbrMaxGates", &maxGates); 3.5.3.
Comments: • The value of the third argument to AcqrsD1_configMode must always be 0. • When in Zero-Suppress mode, the following digitizer parameters are ignored: • nbrSamples and nbrSegments of the function AcqrsD1_configMemory are replaced by “NbrSamples” and “NbrSegments” in the function AcqrsD1_configAvgConfig. • The value nbrSamples defines the target number of samples to acquire in each segment (trigger) before zero-suppression is applied.
3.6.3. U1084A Zero-Suppression mode – Readout configuration The function AcqrsD1_readData() may be used to read the acquired data. The entire acquisition must be read, reading partial acquisitions is not supported. There are no out-of-band segment descriptors in this mode, the segment descriptors are embedded in the acquisition data.
- Each Gate will start with a Gate Descriptor which describes the length of the gate and its position relative to the trigger of the segment. -If a segment does not contain any valid data, there will not be any Gate Descriptor or Gate Data, the next Segment Descriptor will follow immediately. 3.6.4.1. Segment Descriptor The Segment Descriptor is always 8 words (256 bits) and has the following format: 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 31 ..
3.6.4.3. Gate Data Each gate header is followed by gateLength samples of acquisition data. i.e. the next Gate Descriptor can be found by, next Gate Descriptorr = current header position + gateLength +2. The data is in 8-bit digitized raw unsigned format. Word [31..24] [23..16] [15..8] [7..0] 1 Sample 4 Sample 3 Sample 2 Sample 1 2 Sample 8 Sample 7 Sample 6 Sample 5 3 Sample 12 Sample 11 Sample 10 Sample 9 4 Sample 16 Sample 15 Sample 14 Sample 13 Etc.. … … … … 3.7.
// Configure peak interpolation ViInt32 enableInterpolation = 1; ViInt32 horzReso = 2; // Increase in horizontal resolution, in bits ViInt32 vertReso = 2; // Increase in vertical resolution, in bits AcqrsD1_configAvgConfig(instrID, 0, "InterpEnable", &enableInterpolation); AcqrsD1_configAvgConfig(instrID, 0, "TdcHistogramHorzRes", &horzReso); AcqrsD1_configAvgConfig(instrID, 0, "TdcHistogramVertRes", &vertReso); The values horzReso and vertReso specify the number of bits to use for the fractional part of t
3.10. Data Acquisition Instrument operation is preceded by configuring the instrument parameters and then starting the acquisition sequence. New settings are only loaded into the module when the acquisition is started; there is one exception to this rule as discussed for analyzer user gate definition in section 3.5.2 Readout configuration.
(B) More Efficient Polling: use this code fragment to release the polling thread for short periods: ViBoolean done = 0; long timeoutCounter = 100; while ((!done) && (--timeoutCounter > 0)) { AcqrsD1_acqDone(instrID, &done); // poll for status or Sleep(1); } if (timeoutCounter <= 0) // timeout, stop acquisition STOP ACQUISITION This code puts the polling thread to sleep for periods of 1 ms at a time, letting other threads of the application or other applications use the CPU time.
{ AcqrsD1_forceTrig(instrID); if (AcqrsD1_waitForEndOfAcquisition(instrID, timeOut) == ACQIRIS_ERROR_ACQ_TIMEOUT) { AcqrsD1_stopAcquisition(instrID); SCREAM, because a major error occurred } } Note that no timeout should ever occur when waiting for a 'forceTrig' to terminate, provided that the timeOut value was made large enough. If a timeout does occur, this would indicate a failure in the digitizer or the entire system.
3.10.5.1. U1084A Averager and SAR The U1084A Averager and Digitizer supports a simplified version of the Digitizer SAR mode. To enable it: In Averager mode: Call AcqrsD1_configMode with ‘mode = 2’ (Averaging mode) and ‘flags = 10’ (SAR mode). In Digitizer mode: Call AcqrsD1_configMode with ‘mode = 0’ (Normal mode) and ‘flags = 10’ (SAR mode). Control of the Averager in this mode is essentially the same as with SAR mode for Digitizers, except that the number of banks is fixed at two. 3.10.6.
automatically switches the banks, starts a new acquisition, a new processing and clears the AutoSwitch semaphore. 4 Once the software receives the ProcessingEnd interrupt, it can start the readout. status = AcqrsD1_waitForEndOfProcessing(instrID, timeout); AcqrsD1_readData(instrID, channel, &readParams, waveformArray, &wfDesc, &segDesc); Go to 2 to continue.
3.11. D1-style Data Readout For the reading of standard waveforms the AcqrsD1_readData routine should be used. The following older routines will remain available but will no longer be discussed: AcqrsD1_readCharWform AcqrsD1_readCharSequence AcqrsD1_readRealWform AcqrsD1_readRealSequence AcqrsD1_accumulateWform You should use the function AcqrsD1_readData for all new programs. The older functions will not give support for new instruments or new functionality.
• The value of segDesc->horPos is the time interval in seconds between the first data point and the nominal time origin of the trigger delay. It is always in the range [-sampTime, 0]. It is useful for a very precise positioning, to a fraction of the sampling interval, of the waveform. In many applications, it can be ignored. Refer to section 3.12, HORIZONTAL PARAMETERS IN ACQUIRED WAVEFORMS, for a detailed explanation of horPos.
long long char long long nbrSegments = 10; nbrPoints = 1000; *dataArrayP; currentSegmentPad; nbrSamplesNom, nbrSegmentsNom; AqReadParameters *readPar = new AqReadParameters; AqDataDescriptor *dataDesc = new AqDataDescriptor; AqSegmentDescriptor *segDesc = new AqSegmentDescriptor[nbrSegments]; readPar->dataType = 0; // 0 = byte readPar->readMode = 1; // 1 = sequence waveform readPar->nbrSegments = nbrSegments; readPar->firstSampleInSeg = 0; readPar->segmentOffset = nbrPoints; readPar->firstSegment = 0; rea
for (int n=0; n
AqReadParameters readParams; // Read Definitions AqDataDescriptor wfDesc; // Returned (common) waveform values AqSegmentDescriptorAvg segDesc; // Returned segment values long channel = 1, nbrSamples = 20000; double waveformArray[20000]; readParams.dataType = ReadReal64; // Request Volts readParams.readMode = ReadModeAvgW; readParams.nbrSegments = 1; readParams.firstSampleInSeg = 0; readParams.segmentOffset = nbrSamples; readParams.firstSegment = 0; // Read first segment readParams.
3.11.5.2. Averaged Waveforms as 32-bit Sums You must use the general-purpose function AcqrsD1_readData. Use this code fragment: AqReadParameters readParams;// Read Definitions AqDataDescriptor wfDesc; // Returned (common) waveform values AqSegmentDescriptorAvg segDesc; // Returned segment values long channel = 1, nbrSamples = 20000; long waveformArray[20000]; readParams.dataType = ReadInt32; // Request 32-bit sums readParams.readMode = ReadModeAvgW; readParams.nbrSegments = 1; readParams.
3.11.7.2. Raw data The complete data should only be read out using the gated data mode described below. An appropriate User Gate can be defined to access all of the data. 3.11.7.3. Gated data Data can be read for both user and threshold gate operation using readMode = 7 (ReadModeSSRW). The waveform descriptor structure contains the value actualDataSize giving the total number of data bytes read. A time stamp block, measuring the trigger time, will mark the beginning of each segment.
Peak region block 8 points 31..24 (8 bits) 23..16 (8 bits) 15..8 (8 bits) 7..0 (8 bits) 0x00 Valid Left Valid Right 31..24 (8 bits) 23..16 (8 bits) 15..8 (8 bits) 7..0 (8 bits) Sample(tmax) Sample(tmax-1) Sample(tmax-2) Sample(tmax-3) Sample(tmax+4) Sample(tmax+3) Sample(tmax+2) Sample(tmax+1) 15..8 (8 bits) 7..0 (8 bits) 0x00 Valid Left Valid Right 31..24 (8 bits) 23..16 (8 bits) 15..8 (8 bits) 7..
3.11.8.4. Reading the histogram The accumulated histogram can be read out using readMode = 9 (ReadModeHistogram). The dataType and dataArraySize must be selected to correspond to the size of the histogram and its bins. The waveform descriptor structure contains the value actualDataSize giving the total number of data bytes read. The individual histogram bins will be able to contain accumulated sums of either 2**32, as ViUInt32, or 2**16, as ViUInt16. Histogram bin is 32 bits wide 31..
With the function AcqrsD1_readData, use this code fragment: AqReadParameters readParams; // Read Definitions AqDataDescriptor dataDesc; // Returned waveform values AqSegmentDescriptor segDesc; // Returned segment values long channel = 1, nbrSamples = 4000000; char waveformArray[4000000]; readParams.dataType = ReadInt8; readParams.readMode = ReadModeStdW; readParams.nbrSegments = 1; readParams.firstSampleInSeg = 0; readParams.segmentOffset = nbrSamples; readParams.
const int NbrGates = 64; long channelNbr = 0; long configObj = AvgGate; long lastGate; AqGateParameters gatePara[NbrGates]; AcqrsD1_getSetupArray (instrID, channelNbr, configObj, NbrGates, gatePara, &lastGate); Make sure to use a pointer to the last argument, since it returns the number of gates. lastGate cannot exceed the number of gates being written. To read the gated waveforms, use the function AcqrsD1_readData.
1. Configure the APXXX for appropriate channel, timebase, trigger, and gate parameters. 2. Start the first acquisition. 3. Give the order to switch banks and start the next acquisition and data processing on the current acquisition as soon as possible. The processing can overlap with the data acquisition since it automatically deals with the memory bank that is not selected for acquisition. If you need to read the original data choose the "no processing" option. 4.
bool finished = false; while(!finished) { memoryBank = (memoryBank + 1)&0x1;// switch to other bank AcqrsD1_configMode(instrID, 3, 0, memoryBank); AcqrsD1_acquire(instrID); // start new acquisition AcqrsD1_processData(instrID, 0, 0);// start processing AcqrsD1_waitForEndOfProcessing(instrID, timeout); // At this point, you should check the return value! readParams.dataType = ReadReal64; readParams.readMode = ReadModePeak; readParams.nbrSegments = 1; readParams.firstSampleInSeg = 0; readParams.
3.12. Trigger Delay and Horizontal Waveform Position When using a digitizer the user has 3 instrument setup variables with which to position the acquired waveform in time: • sampInterval: the sampling interval (inverse of the sampling frequency) • nbrSamples: the number of samples to acquire • delayTime: the nominal trigger delay sampInterval Trigger delayTime nbrSamples By convention, the nominal trigger delay is taken relative to the beginning of the trace, i.e.
Acqiris digitizers feature a Trigger Time Interpolator (TTI), which measures the time between the trigger event and the next sampling clock to a fraction of the sampling interval. It permits very precise positioning of the acquired trace in highly zoomed displays, particularly when multiple acquisitions of the same signal are used. In many other applications, this value can be ignored.
sampling rate being used (see the product brochure/datasheet to confirm the resolution). The waveform readout function AcqrsD1_readData returns the time stamp value as 2 32-bit values. In order to do time differences, you should transform them into a 64-bit integer: • In Visual C/C++, use the 64-integer __int64 as follows: __int64 timeStamp = timeStampHi; timeStamp = timeStamp<<32 + (unsigned long)timeStampLo; Arithmetic operations between such integers can be done as with shorter integers.
NOTE: When using this capability please make sure that the module is correctly synchronized on the signal. This might require adjusting the threshold. If this is not the case the data will be useless and calibration can fail in rather obscure ways. 3.16.2. External Clock (Continuous) The continuous external clock mode (clockType = 1) permits the application to the digitizer of a continuous, constant frequency, external clock in order to sample at an arbitrary frequency.
Model Input Frequency range (MHz) sFmax vs.
// We assume that a normal calibration has been done, either // during initialization, or explicitly AcqrsD1_configExtClk(.. ) // Set to (cont) Ext Clk // Make sure to apply the same external frequency as the value // ‘inputFrequency’, set in the function call above Acqrs_calibrateEx(instrID, 2, 0, 0 ); The function Acqrs_calibrateEx with calType = 2 readjusts some timing calibration constants, but does not modify any vertical adjustment values, such as gain or offset.
AcqrsD1_stopAcquisition(instrID); AcqrsD1_readXXXWform(instrID, . . .); Note that the sampling rate and the time between bursts have no incidence on the configuration parameters of the digitizer, i.e. they appear nowhere. Example for Termination (2): if you wanted to acquire 5000 waveforms of 200 data points each, you would write: AcqrsD1_configMemory(instrID, 100000, 1); AcqrsD1_configExtClock(instrID, 4, threshold, 0, 0.0, 0.
3.17.1. Channel Numbering with AS bus In a MultiInstrument, input channels are numbered from 1 to nbrChannels. The number of channels can be retrieved with the function call: Acqrs_getNbrChannels(instrID, &nbrChannels); Channel 1 corresponds to channel 1 of module 0. Channel numbers increase first through module 0, then through modules 1, 2 etc.
In digitizers with trigger pattern capabilities, several trigger bits could be set simultaneously. However, no trigger pattern capabilities between different modules can be coded, i.e. only a single module in a MultiInstrument can be the trigger source, although the source in the single module might be a pattern. For these reasons, the module number must be coded explicitly.
3.18.1. Normal Acquisition (mode 0) The normal digitizer operating mode which is present on most instrument models. It also has sub-modes which may be enabled by using the ‘flags’ parameter of the AcqrsD1_configMode function. 3.18.1.1. ‘Start on Trigger’ in Normal Acquisition mode The ‘Start on Trigger’ mode is a sub-mode of Normal Acquisition mode, it begins data recording only upon receipt of a trigger signal, and stops after nbrSamples data points are acquired.
While this mode even ‘works’ for nbrSegments = 1, in practice the value of nbrSegments should be at least 3. It is important to note that after the acquisition of a segment, the digitizer automatically advances to the next memory section and immediately (with a dead time of ~ 1 μs) starts recording into it.
3.18.6. Frequency Counter (mode 6) This is an option available for the DC140 and DC135 digitizers. It is implemented with a signal counter that counts trigger signals from the user-requested channel. A time counter generates the user-programmed aperture time, during which the measurement is performed. The user-requested signal channel has to be programmed for the expected signal characteristics; the standard config functions should be used to set the full-scale, coupling, offset and trigger threshold.
3.19. Readout of Battery Backed-up Memories Acqiris digitizers with the battery back-up option permit retaining acquired waveforms during periods of time when the power might be interrupted. 3.19.1. Preparations before Power-Off A digitizer only remembers the digitized data array, but not all of the parameters that are needed to interpret the waveform. These parameters are normally retained in the driver, but are typically lost when power is lost or when the controlling application is terminated.
We also recommend reading the temperature when the instrument is stopped. The read operation may generate small signal perturbations through cross talk, if it is executed while an acquisition is in progress. 3.21. Building applications that can Hibernate The Acqrs_powerSystem function was implemented to be called from a routine that treats Windows events.
4. Appendix A: Estimating Data Transfer Times The time to transfer a waveform may be a significant part of the execution time of a program, and thus becomes an important design consideration for new applications. We present here a simple timing model with the aim of predicting the transfer time for digitizer readout as a function of the number of segments, number of samples, CPU speed and the operating system. 4.1.
5. Extra Type 300 / sampInterval + 98 digitizers with ≤ 1 GS/s maximum sampling rates 300 / sampInterval + 194 digitizers with 2 GS/s maximum sampling rates or DC271-FAMILY instruments set for a combine channel mode allowing 2 GS/s 300 / sampInterval + 386 DC271-FAMILY instruments set for a 4 GS/s combine channel mode The copying time Cpy per 8-bit sample is ~ (5 µs) / (Pentium CPU speed in MHz). Thus, for a 250 MHz Pentium Cpy is ~ 0.02 µs, and for a 500 MHz Pentium it is ~ 0.01 µs.
(B) DC270 connected to a 500 MHz Pentium with a MXI-3 interface: Transferring single records of 100'000 samples, recorded at 100 MS/s: M = 1 N = 100 000 Xfr = 0.012 Cpy = 0.01 Ovhd DMA = 100 Ovhd buffer = 5 Extra = 240 10 + 96 = 120 T1 = M ⋅ Ovhd DMA + M ⋅ N ⋅ Xfr = 100 + 1200 = 1300µs T2 = Ovhd DMA + M ⋅ Ovhd buffer + M ⋅ (N + Extra ) ⋅ Xfr + M ⋅ N ⋅ Cpy = 100 + 5 + 100120 ⋅ 0.012 + 100 000 ⋅ 0.01 = 2306 µs It is therefore more favorable to use the function AcqrsD1_readData for readMode = 0.
Comments: • We assume a 2 GS/s digitizer running at the highest sampling rate, direct connection of the digitizer to the host PCI bus or through the SBS-Bit3 interface (Acqiris model number IC200), Windows NT. • R = T2 T1 If R > 1.0, a loop over AcqrsD1_readData for readMode = 0 is faster than AcqrsD1_readData for readMode = 1 (ReadModeSeqW).
