The I/Q streaming mode is used to stream continuous I/Q samples at a given center frequency. The sample rate, bandwidth, center frequency, and data type can be configured. If you need to capture I/Q data at many frequencies or don't need continuous streaming capabilities, consider using the I/Q Sweep List / Frequency Hopping measurements.

Example

For a list of all examples, please see the examples/ folder in the SDK.

 
#include <cstdio>
#include <cstdlib>
#include <vector>
 
#include "sp_api.h"
 
// Configure the device for I/Q streaming and stream for a period of time.
 
void sp_example_iq_stream()
{
    int handle = -1;
    SpStatus status = spNoError;
 
    // Open device
    status = spOpenDevice(&handle);
 
    // Check open status
    if(status != spNoError) {
        printf("Unable to open device\n");
        exit(-1);
    }
 
    // Configure the receiver for IQ acquisition
    spSetRefLevel(handle, -20.0); // -20 dBm reference level
    spSetIQCenterFreq(handle, 900.0e6); // 900MHz center frequency
    spSetIQSampleRate(handle, 2); // 50 / 2 = 25MS/s IQ 
    spSetIQBandwidth(handle, 20.0e6); // 20MHz of bandwidth
    spSetIQDataType(handle, spDataType32fc);
 
    // Initialize the receiver with the above settings
    status = spConfigure(handle, spModeIQStreaming);
    if(status != spNoError) {
        printf("Unable to configure device\n");
        printf("%s\n", spGetErrorString(status));
        spCloseDevice(handle);
        exit(-1);
    }
 
    // Query the receiver IQ stream characteristics
    // Should match what we set earlier
    double actualSampleRate, actualBandwidth;
    spGetIQParameters(handle, &actualSampleRate, &actualBandwidth);
 
    // Allocate memory for complex sample, IQ pairs interleaved
    int bufLen = 16384;
    std::vector<float> iqBuf(bufLen * 2);
 
    // Let's acquire 5 second worth of data
    int samplesNeeded = 5 * (int)actualSampleRate;
 
    while(samplesNeeded > 0) {
        // Notice the purge parameter is set to false, so that each time
        //  the get IQ function is called, the next contiguous block of data
        //  is returned.
        spGetIQ(handle, &iqBuf[0], bufLen, 0, 0, 0, spFalse, 0, 0);
 
        // Process/store data here
        // Data is interleaved 32-bit complex values
 
        // Need bufLen less samples
        samplesNeeded -= bufLen;
    }
 
    // Finished
    spCloseDevice(handle);
}
 

Basics

The API provides the ability to continuously stream I/Q samples up to the device’s maximum sample rate. See I/Q Sample Rates for more information.

I/Q data can be retrieved as 32-bit complex floats or 16-bit complex shorts. See I/Q Data Types for more information.

Sample Rate, Decimation, and Bandwidth

The I/Q data can be decimated by powers of 2 between 1 and 8192, from a base sample rate of 61.44MS/s. This means the following sample rates are available, 61.44 / N, where N is a power of 2. A software filter can be applied to the data and the bandwidth of this filter is selectable.

Decimations 1, 2, and 4 occur on the hardware and custom cutoff frequencies are accomplished with a PC side lowpass filter. The PC software filter is optional for these decimations. If the software filter is disabled the FPGA half band filters are the only alias filters used for these decimation stages and there will be aliased signals in the roll off regions of the I/Q bandwidth. Disabling the software filter will reduce CPU load of the I/Q data stream at the cost of this aliasing.

In the special case of decimation = 1 (SR = 61.44MS/s), the LO feedthrough is present in the rolloff region. Enabling the software filter will remove this. For many applications, it will be important to filter this signal out.

For decimations greater than 4, decimation and filtering occur both on the device and PC, and PC side software filtering is not optional.

Polling Interface (I/Q)

The API for the I/Q data stream is a polling style interface, where the application must request I/Q data in blocks that will keep up with the device acquisition of data. The APIs internal circular buffer can store up to 1/2 second worth of I/Q data before data loss occurs. It is the responsibility of the user’s application to poll the I/Q data fast enough that data loss does not occur.

External Triggering

External trigger information can be retrieved when I/Q streaming. Trigger information is provided through the triggers buffer in the spGetIQ function.

If a trigger buffer is provided to spGetIQ, any external trigger events seen during the acquisition of the returned I/Q data will be placed in the trigger buffer. External trigger events are returned as indices into the I/Q data at which the trigger event occurred. For example, if 1000 I/Q samples are requested and a trigger buffer of size 3 is provided, and the function returns with the trigger buffer set to [12,300,876], this indicates that an external trigger event occurred at I/Q sample index 12, 300, and 876 in the I/Q data returned from this function call.

If fewer external triggers were seen during the I/Q acquisition than the size of the trigger buffer provided, the remainder of the trigger buffer is set to the sentinel value. The default sentinel value is 0.0, so for example, if a trigger buffer of size 3 is provided, and only a single trigger event was seen, the trigger buffer will return [N, 0.0, 0.0] where N is the single trigger index returned.

If more trigger events were seen during the I/Q acquisition than the size of the trigger buffer, those trigger events that cannot fit in the buffer are discarded.

Triggers are provided as doubles and can indicate the trigger occurred in between 2 samples. This can occur when performing decimation, as the triggers are recorded at a much higher resolution than the final sample rate.

A note on trigger sentinel values, the default sentinel value of 0.0 does not allow the detection of triggers occurring at the first sample point. If this is an issue, set the sentinel value to -1.0 or some other negative value which cannot be normally returned. The default value of 0.0 is the result of historical choices and will remain the default value.

Additional Information

See I/Q Acquisiton for more information.