Example

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

 
#include <complex>
#include <cstdio>
#include <cstdlib>
#include <vector>
 
#include "sp_api.h"
 
// Configure and perform a single sweep in the I/Q sweep list mode.
// Configure a sweep with 3 different frequencies and different capture sizes at each frequency. 
// Shows how to index the sweep.
// For a more basic example, see the 'simple' example.
// For an example which queues multiple sweeps, see the 'queue' example.
 
void sp_example_iq_sweep_list_single()
{
    int handle = -1;
 
    // Open device
    SpStatus status = spOpenDevice(&handle);
 
    if(status != spNoError) {
        printf("Unable to open device\n");
        exit(-1);
    }
 
    // The data returned should be corrected, scaled to sqrt(mW) instead of full scale.
    spSetIQSweepListCorrected(handle, spTrue);
    // Returne the data at 32-bit floating point complex values
    spSetIQSweepListDataType(handle, spDataType32fc);
    // 3 frequency steps
    spSetIQSweepListSteps(handle, 3);
 
    // If the GPS antenna is connected, this will instruct the device to
    // discipline to the internal GPS PPS. This will improve frequency 
    // and timestamp accuracy.
    spSetGPSTimebaseUpdate(handle, spTrue);
 
    // Configure all three frequency steps
 
    // 1GHz, 1000 samples to be collected
    spSetIQSweepListFreq(handle, 0, 1.0e9);
    spSetIQSweepListRef(handle, 0, -20.0);
    spSetIQSweepListSampleCount(handle, 0, 1000);
 
    // 2GHz, 3000 samples to be collected
    spSetIQSweepListFreq(handle, 0, 2.0e9);
    spSetIQSweepListRef(handle, 0, -20.0);
    spSetIQSweepListSampleCount(handle, 0, 2000);
 
    // 3GHz, 3000 samples to be collected
    spSetIQSweepListFreq(handle, 0, 3.0e9);
    spSetIQSweepListRef(handle, 0, -20.0);
    spSetIQSweepListSampleCount(handle, 0, 3000);
 
    // Total samples between all 3 frequency steps
    const int totalSamples = 6000;
 
    // Configure the device
    spConfigure(handle, spModeIQSweepList);
 
    // Allocate memory for the capture
    std::vector<std::complex<float>> iq(totalSamples);
 
    // Memory for the timestamps
    int64_t timestamps[3];
 
    // Perform the sweep
    spIQSweepListGetSweep(handle, &iq[0], timestamps);
 
    // Example of how to index the data
    // Get pointers to the data for the 3 steps
    std::complex<float> *step1 = &iq[0];
    std::complex<float> *step2 = &iq[1000];
    std::complex<float> *step3 = &iq[3000];
 
    // Do something with the data here
 
    // The three timestamps will be the times of the samples at 
    //   step1[0], step2[0], and step3[0]
 
    // GPS lock doesn't occur immediately upon opening. If
    //   the GPS is cold it could take several minutes to acquire lock. If warm, it 
    //   might not lock for several seconds. Generally the hardware will need
    //   to see at least 1 PPS after opening before lock can be determined. 
    //   It will take multiple PPS after opening for disciplining to be achieved.
    // Call the spGetGPSState function to determine if the timestamps were returned
    //   under GPS lock.
 
    // Done with device
    spCloseDevice(handle);
}
 

Basics

I/Q sweep lists are finite length I/Q acquisitions across a user supplied list of frequencies. Lists of up to 1000 frequencies can be provided. At each frequency, the reference level and number of samples to be collected must be configured. One measurement/list is referred to as a “sweep” and iterates through all configured frequency steps. Several sweeps can be queued to maintain maximum throughput.

I/Q samples are collected at the device's native sample rate, 61.44MS/s. Unlike I/Q streaming, software filtering is not performed prior to returning the data to the user. The LO feedthrough of the instrument is present in the rolloff region of the returned bandwidth and depending on the application a small filter may need to be applied to remove this.

On average, the SP will switch frequencies at ~135us. The switch time is not deterministic and will depend on a number of factors.

At each frequency, a timestamp is provided indicating the nanoseconds since epoch for the first I/Q sample at that frequency. If the internal GPS is locked, this time is GPS time, If GPS is not locked, system time is provided. Regardless of GPS lock, relative accuracy of timestamps between steps are highly accurate through use of internal device counters.

Queuing

Once a sweep list is configured, it can be performed as a single atomic sweep using the spIQSweepListGetSweep function, or it can be queued using the asynchronous functions, spIQSweepListStartSweep/spIQSweepListFinishSweep. Queuing the sweeps provides two major advantages, minimize blind time between the end of one sweep and the start of the next, and the ability to do other tasks while waiting for the sweeps to complete. Up to 16 sweeps can be queued. It is not possible to queue sweeps with different configurations.

Notes on Performance

While the user can specify an arbitrary number of samples at each frequency, the SP device is internally limited to multiples of 2048 samples. For this reason, it is optimum to round up to the next multiple of 2048, which will not affect acquisition speed and reduce the number samples discarded. Maximum sweep speed occurs when the number of samples at each frqeuency is <= 2048.

I/Q Streaming vs I/Q Sweep List

One use case where I/Q sweep lists are preferred to I/Q streaming for single frequency measurements is when you know in advance how many I/Q samples you want to collect at that frequency. Using I/Q sweep lists to acquire these samples has less overhead than using I/Q streaming. Starting and stopping the I/Q stream can take tens of milliseconds, where as the overhead associated with performing a single I/Q sweep list acquisition is 1-5 milliseconds.

Additional Information

See I/Q Acquisiton for more information.