 |
BB API
|
|
BB API
|
This manual is a reference for the Signal Hound BB60 application programming interface (API). This API supports the BB60D, BB60C, and BB60A Signal Hound devices. The API provides a set of C functions for making measurements with the BB60 devices. The API is C ABI compatible making is possible to be interfaced from most programming languages. See the code examples in the SDK for examples of calling the API from C++ and other programming languages and environments.
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.
Both Windows and Linux builds are available in the SDK.
Windows builds are available for both x86 and x64. The Windows builds are compiled with Visual Studio 2012 and any application using this library will require distributing the VS2012 redistributable libraries.
Linux versions are available for 64-bit Ubuntu 18.04 and CentOS7.
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/.so.
See the change log in the SDK for detailed API version history.
Version 3.0 coincides with the release of the Spike, Signal Hounds latest spectrum analyzer software. With this release comes the ability to open specific BB60C devices. BB60A devices lack the firmware to perform this task. See bbGetSerialNumberList and bbOpenDeviceBySerialNumber for more information.
Version 2.0 and greater introduces support for the BB60C as well as numerous performance improvements and flexible I/Q data streaming. The API can target both the BB60A and BB60C with virtually no changes to how one interfaces the API.
This section contains notes of interest for users who are currently using version 1.2 of the API and who are updating their code base to use version 2.0.
The BB60D has a UART output on port 2. The UART port has 3 output modes:
In all 3 output modes the UART transmits 1 byte at a time, including start and stop bit for a total of 10 bits. The output baud rate can be specified from a list of available rates using the bbSetUARTRate function.
There is no UART input capability.
See bbConfigureIO, the UART functions, and the C++ programming examples for more information.
The BB60 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.
If you wish to interface multiple devices on Linux, please see Multiple USB Devices.
The BB60D can be set into a low power state using the bbSetPowerState function provided by the API. Power will reduce to ~1.25W from 6W when active. The device should not be actively performing any measurements when setting the device to the standby power state and should not perform any measurements while in the standby state. Before setting the device to standby, the device should be in the idle mode (by calling bbAbort) or configured for sweeping but not actively performing a sweep.
Here are some other power state transitions that occur:
See the C++ programming examples for an example of configuring the power state.
By default, Linux applications cannot increase the priority of individual threads unless ran with elevated privilege (root). On Windows this issue does not exist, and the API will elevate the USB data acquisition threads to a higher priority to ensure USB data loss does not occur. On Linux, the user will need to run their application as root to ensure USB data acquisition is performed at a higher priority.
If this is not done, there is a higher risk of USB data loss for streaming modes such as I/Q, real-time, and fast sweep measurements on Linux.
In our testing, if little additional processing is occurring outside the API, 1 or 2 devices typically will not experience data loss due to this issue. Once the user application increases the processing load or starts performing I/O such as storing data to disk, the occurrence of USB data loss increases and the need to run the application as root increases.
There are system limitations when attempting to use multiple Signal Hound USB 3.0 devices* simultaneously on Linux operating systems. The default amount of memory allocated for USB transfers on Linux is 16MB. A single Signal Hound USB 3.0 device will stay within this allocation size, but two devices will exceed this limitation and can cause connection issues or will cause the software to crash.
The USB memory allocation size can be changed by writing to the file
/sys/module/usbcore/parameters/usbfs_memory_mb
A good value would be N * 16 where N is the number of devices you plan on interfacing simultaneously. One way to write to this file is with the command:
where 32 can be replaced with any value you wish. You may need to restart the system for this change to take effect.
*Includes both Signal Hound USB 3.0 spectrum analyzers and signal generators.
The BB60 interface is C compatible which ensures it is possible to interface the API in most languages that can call C functions. These languages include C++, C#, Python, MATLAB, LabVIEW, Java, etc. Some examples of calling the API in these other languages are included in the code examples folder.
The API issues errors when fatal connection issues are present during normal operation of the device. The two major errors in this category are bbPacketFramingErr and bbDeviceConnectionErr. These errors are reported on fetch routines, as these routines contain most major device I/O.
bbPacketFramingErr – Packet framing issues can occur in low power settings or when large interrupts occur on the PC (typically large system interrupts). This error can be handled by manually cycling the device power, or programmatically by using the preset routine.
bbDeviceConnectionErr – Device connection errors are the result of major USB issues, most commonly being the device has lost power (unplugged) or interruptions in the USB connection. These errors should be handled by closing and reopening the device with the bbCloseDevice/bbOpenDevice functions. In some cases, the device may need to be fully power cycled by disconnecting and reconnecting the USB cable.
This firmware update has increased the stability of the BB60C on PCs that have a heavy CPU load or in instances where there is random data loss over USB. Currently in the instance where a PC kernel load is high, the PC may not be able to service the USB causing data loss to occur, and the BB60C API reports device connection issues, requiring a device preset. This can also happen if there is (random) data loss over USB 3.0 (rarer). This update resolves these issues by not failing on the connection issues and issuing a warning on the fetch trace functions notifying a user to discard the sweep and try again. The benefit of this is that the API and device remain connected and do not require a preset, often taking about 6 seconds. If you have a device that requires a firmware update, contact Signal Hound.
Gain and attenuation are used to control the path the RF takes through the device. Selecting the proper gain and attenuation settings greatly affect the dynamic range of the resulting signal. When gain and attenuation are set to automatic, the reference level is used to control the internal amplifiers and attenuators. Choosing a reference level slightly above the maximum expected power level ensures the device engages the best possible configuration. Manually configuring gain and attenuation should only be used after testing and observation.
Additionally, when gain and attenuation are set to auto in sweep mode, the API can optimize the gain and attenuation across the frequency range of the device. When using manual settings, it will use the same gain/atten values across the entire span, which may be sub-optimal.
I/Q data is returned from the bbGetIQ function either as 32-bit complex floats or 16-bit complex shorts depending on the data type set in bbConfigureIQDataType. 16-bit shorts are twice as memory efficient as floats but require more effort to convert to absolute amplitudes and may be less convenient to work with.
When data is returned as 32-bit complex floats, the data is scaled to mW and the amplitude can be calculated by the following equation:
where re and im are the real and imaginary components of a single I/Q sample.
When data is returned as 16-bit complex shorts, the data is full scale and a correction must be applied before you can measure mW or dBm. Values range from [-32768 to +32767]. To measure the power of a sample using the complex short data type, three steps are required:
Users can control the baseband software filter when I/Q streaming. Software filtering is always enabled. For each decimation rate, a maximum bandwidth can be provided with the bbConfigureIQ function. The table below shows the sample rates and maximum bandwidth for each decimation rate.
| Decimation Rate | Sample Rate (I/Q pairs/s) | Maximum Bandwidth |
|---|---|---|
| 1 | 40 MS/s | 27 MHz |
| 2 | 20 MS/s | 17.8 MHz |
| 4 | 10 MS/s | 8.0 MHz |
| 8 | 5 MS/s | 3.75 MHz |
| 16 | 2.5 MS/s | 2.0 MHz |
| 32 | 1.25 MS/s | 1.0 MHz |
| 64 | 625 kS/s | 0.5 MHz |
| 128 | 312.5 kS/s | 0.25 MHz |
| 256 | 156.250 kS/s | 140 kHz |
| 512 | 78.125 kS/s | 65 kHz |
| 1024 | 39062.5 S/s | 30 kHz |
| 2048 | 19531.25 S/s | 15 kHz |
| 4096 | 9765.625 S/s | 8 kHz |
| 8192 | 4882.8125 S/s | 4 kHz |
With minimal effort it is possible to determine the absolute time (up to 50ns) of the ADC samples. This functionality is only available when the device is configured for IF or I/Q streaming. Additionally, this functionality is only available for Windows operating systems. It does not work on Linux.
What you will need:
Order of Operations:
See the examples folder in the API download for an example of timestamping the I/Q data using a GPS receiver.
For a given RBW, the FFT size used for sweeps can be calculated with the following algorithm:
Where
WindowBW equals 2.02 for Nuttall windows, 3.7702 for flattop windows and 2.65 for CISPR windows.C equals 2 for CISPR windows and 1 for Nuttall and flattop windows.For technical support, email support@signalhound.com.
For sales, email sales@signalhound.com.
1.9.4