Basic API Usage

Table of Contents

• Opening a Device
• Configuring the Device
• Acquiring Measurements
  • Stopping the Measurements
• Closing the Device
• Recalibration

Any application using the SP API will follow these steps to interact and perform measurements on the device.

1. Open the device and receive a handle to the device resources.
2. Configure the device.
3. Acquire measurements.
4. Stop acquisitions, abort the current operation.
5. Close the device.
6. (Recalibration)

Opening a Device

Opening a device is done through the spOpenDevice or spOpenDeviceBySerial functions. These functions will perform the full initialization of the device and if successful, will return an integer handle which can be used to reference the device for the remainder of your program. See the list of all SP devices connected to the PC via the spGetDeviceList function.

Configuring the Device

Once the device is open, the next step is to configure the device for a measurement. The available measurement modes are listed on the mainpage. Each mode has specific configurations routines, which set a temporary configuration state. Once all configuration routines have been called, calling the spConfigure function copies the temporary configuration state into the active measurement state and the device is ready for measurements. The provided code examples showcase how to configure the device for each measurement mode.

Acquiring Measurements

After the device has been successfully configured, the API provides several functions for acquiring measurements. Only certain measurements are available depending on the active measurement mode. For example, I/Q data acquisition is not available when the device is in a sweep measurement mode.

Stopping the Measurements

Stopping all measurements is achieved through the spAbort function. This causes the device to cancel or finish any pending operations and return to an idle state. Calling spAbort is never required, as it is called by default if you attempt to change the measurement mode or close the device, but it can be useful to do this.

• Certain measurement modes can consume large amounts of resources such as memory and CPU usage. Returning to an idle state will free those resources.
• Returning to an idle state will help reduce power consumption.

Closing the Device

When finished making measurements, you can close the device and free all resources related to the device with the spCloseDevice function. Once closed, the device will appear in the open device list again. It is possible to open and close a device multiple times during the execution of a program.

Recalibration

Recalibration is performed each time the device is reconfigured (spConfigure). For instance, when the device is configured for I/Q streaming, the instrument and measurement is calibrated for the current environment and will not be calibrated again until the device measurement is aborted and started again (read: the device will not recalibrate in the middle of measurements, as this would interrupt measurements such as I/Q streaming or real-time analysis).

Large temperature changes affect measurements the most, and it is recommended to reconfigure the device once a large temperature delta has been recorded.

It is recommended to use the temperature from the spGetDeviceDiagnostics function to detect a temperature drift and recalibrate again when you see a drift of 2-4 degrees Celsius.