 |
SA API
|
|
SA API
|
This manual is a reference for the Signal Hound SA Series application programming interface (API). This API supports the SA44B, SA44, and SA124B/A Signal Hound devices. The API provides a set of C functions for making measurements with the SA series devices. The API is C ABI compatible making is possible to be interfaced from most programming languages.
All code examples are located in the examples/ folder in the SDK which can be downloaded at www.signalhound.com/software-development-kit.
This section covers the main measurements available through the API.
Also see Theory of Operation for more information.
Windows builds are available for both x86 and x64. They are compiled with Visual Studio 2012 and any application using this library will require distributing the VS2012 redistributable libraries.
Versions are of the form major.minor.revision.
A major change signifies a significant change in functionality relating to one or more measurements, or the addition of significant functionality. Function prototypes have likely changed.
A minor change signifies additions that may improve existing functionality or fix major bugs but make no changes that might affect existing user’s measurements. Function prototypes can change but do not change existing parameters meanings.
A revision change signifies minor changes or bug fixes. Function prototypes will not change. Users should be able to update by simply replacing the .DLL.
See the change log in the SDK for detailed API version history.
Initial release. Version numbering will begin at 3.0.0 to signify this is the 3rd major iteration on the SA44/SA124 programming interface. While not a direct descendant of previous versions, there is a large amount of work that is borrowed from earlier versions of the APIs that it is to be considered this to be a derivative work.
The programming interface has drastically changed from previous versions. It is now similar to our BB60 product programming interfaces. The interface is modeled roughly after the IviSpecAn specification.
The API requires two calibration files to exist on the host PC before the API will work correctly. To understand how this is performed, read the sections Opening a Device and First Time Opening a New Device.
The API requires two calibration files to exist on the host PC before the API will work correctly. To understand how this is performed, read the sections Opening a Device and First Time Opening a New Device.
All API functions return the type saStatus. saStatus is an enumerated type representing the success of a given function call.
There are three types of returned status codes:
The best way to address issues is to check the return values of the API functions. The API function saGetErrorString is provided to retrieve a string representation of any given status code for easy debugging.
The API issues errors when fatal connection issues are present during normal operation of the device. Only one major error is returned due to fatal connections issues, saUSBCommErr. This error can be returned from all major get() routines. If at any time the API experiences USB communication errors the next get() routine will return this error.
If you receive this error, your program should call saCloseDevice to free any remaining resources before checking the connection of your device and trying to open the device through the API again.
The SA44 and SA124 models have many device restrictions which prevent the user from selecting all possible combinations of RBW and VBW for any given sweep. Many restrictions are not known until saInitiate is called and all parameters of the sweep are considered. The API clamps RBW/VBW when saInitiate is called if they break the restrictions which are listed below. Concern yourself with these restrictions only when it is imperative the API use exactly the RBW and VBW you requested.
SA44A/B, SA124A/B limitations:
When automatic atten or automatic gain is selected, the API uses the reference level provided to choose the best settings for gain, attenuator, and preamplifier (if applicable) settings for an input signal with amplitude equal to reference level. For almost all cases, automatic settings are best. However, if your application must override the automatic settings, set all gain control values (atten, gain, and preamp) to manual values.
The atten parameter controls the RF input attenuator, and is adjustable from 0 to 30 dB in 10 dB steps for the SA124A and SA124B, or 0 to 15 dB in 5 dB steps for the SA44 / SA44B. The RF attenuator is the first gain control device in the front end, before the preamplifier (if any).
The preamp parameter, only for the SA44B, controls whether the preamplifier is in circuit or bypassed. The preamplifier increases sensitivity, decreases local oscillator feed-through, and significantly increases the amplitude of intermodulation products. It is located immediately after the attenuator. For the SA124A/B the preamplifier is always on; use a higher attenuation setting for high amplitude signals.
The gain parameter controls analog and digital intermediate frequency (IF) gain. A setting of 1 is midrange. Setting gain to 0 adds a 16 dB attenuator to the IF input. Setting gain to 2 adds 12 dB of digital gain to the IF signal processing chain before the 24 bit ADC values are truncated to 16 bits.
The code examples are located in the examples/ folder found in the API download.
Even though the API is compiled with Microsofts C++ compiler (VC++), name decoration is explicitly disabled for public functions so that a variety of programming languages and external tools can utilize this API. Programming languages such as C#, Java, and Python can call this API as well as tools such as MATLAB and LabVIEW.
Most function parameters are standard primitive data types, such as floating point numbers and integers. Parameters are passed either by value or as pointers. Supplying these parameters is supported by the languages and tools mentioned above.
One such primitive type without a directly analogous type is the bool type. VC++ defines the bool type as an 8-bit integer. Passing 0 for false and 1 for true in an 8-bit integer type will work when a bool type is needed by the API.
Enums are defined as 32-bit integers in VC++.
Every time saInitiate is called, the API reads the internal temperature of the device and generates corrections accordingly. If you open the device shortly after plugging it in,before it has had 15 minutes to reach ambient temperature, your readings may drift as it warms up. It is recommended to re-initiate your sweep every 2-3 minutes until a stable internal temperature is reached.
The SA API is not thread safe. A multi-threaded application is free to call the API from any number of threads if the function calls are synchronized (i.e. using a mutex). Not synchronizing your function calls will lead to undefined behavior.
The API can manage multiple devices within one process. In each process the API manages a list of open devices to prevent a process from opening a device more than once. You may open multiple devices by specifying the serial number or allowing the API to discover them automatically.
If you wish to use the API in multiple processes it is the user’s responsibility to manage a list of devices to prevent the possibility of opening a device twice from two different processes. Two processes communicating to the same device will result in undefined behavior. One possible way to manage inter-process information like this is to use a named mutex on a Windows system.
For technical support, email support@signalhound.com.
For sales, email sales@signalhound.com.
1.9.4