Signal Hound BB API
BB60 API Reference

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.

Main Pages

Build/Version Notes

Builds

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

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.

What’s New in Version 5.0

  • Added support for the BB60D.
  • For existing programs only utilizing BB60C/A devices, no software changes are required when using the new DLL.
  • Some functions require different parameters when using the BB60D, such as bbConfigureIO.
  • A new device type is returned from the bbGetDeviceType function to detect the BB60D when connected.
  • New functions have been added specifically for the BB60D. These functions configure and enable the UART output for various types of antenna switching. See UART Antenna Switching.
  • Some functions have been deprecated but will continue to be present in the API for existing applications. Alternatives have been provided for these functions.
  • Several macros have been deprecated but remain in the API header file for existing applications. The updated and more descriptive macro names should be used.
  • Added function bbGetSerialNumberList2, which also returns the device type. Enables the ability to target a specific device type when opening a device.

What’s New in Version 4.0

  • Added support for the BB60C-2, a minor hardware revision to the BB60C. The non-deprecated functions have not changed, so integrating the new BB60C-2 devices should require no software changes other than updating the API DLL in the project.
  • Several deprecated functions have been removed. There are alternatives for each deprecated function.

What’s New in Version 3.0

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.

What’s New in version 2.0

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.

Updating from Version 1.2 or Later

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.

  • Function names and the API file names may have changed from an earlier version. This is due to making the API device agnostic. Functionally the API remains the same, so simply updating to the newer naming scheme will be all that is necessary to interface a newer API.
  • Intermediate frequency (IF) streaming has been replaced with I/Q streaming but IF streaming can still be performed. See bbInitiate for more information on how to set up IF streaming.
  • bbQueryDiagnostics has been deprecated and replaced with bbGetDeviceDiagnostics. This change removes unnecessary access to hardware diagnostic information specific to the BB60A.

Requirements

Windows Development Requirements

  • Windows 7/8/10/11 (64-bit Windows 10 recommended)
  • Windows C/C++ development tools/environment.
    • If Visual Studio 2012 is not used, then the VS2012 C++ redistributables will need to be installed.
  • bb_api.h, API header file.
  • bb_api.lib/bb_api.dll, These are the main API library files.
  • ftd2xx.dll, Provided in SDK. Must be in the same directory as the bb_api.dll. Used for scalar network analysis sweeps with the Signal Hound tracking generator.

Linux Development Requirements

  • 64-bit Linux operating system. (Tested and developed on Ubuntu 18.04 and CentOS7)
  • C++ compiler (Built using g++)
  • The API header file. (Included in SDK)
  • The API shared library (Included in SDK)
  • FTDI USB shared library (Included in SDK and available for download from manufacturer)
  • libusb-1.0 shared library (Available from most package managers)
  • Administrator(root) access to either run applications which use the API or install rules to allow non-root access to the device.

PC Requirements

  • USB 3.0 connectivity provided through 4th generation or later Intel CPUs.
  • (Recommended) Quad core Intel i5/i7 processors, 4th generation or later.
  • (Minimum) Dual-core Intel i5/i7 processors, 4th generation or later.

UART Antenna Switching

The BB60D has a UART output on port 2. The UART port has 3 output modes:

  1. Immediate, send a byte on demand.
  2. Antenna switching during sweeps. During a sweep a UART byte will be transmitted at specific positions in the sweep, allowing multi-antenna coverage during a single sweep.
  3. Pseudo-doppler switching during I/Q streaming. While I/Q streaming the UART can be configured to output bytes at specific intervals for pseudo-doppler direction finding applications.

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.

Thread Safety

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.

Multiple Devices and Multiple Processes

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.

Power State

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:

  • When the device is first connected to the PC, it starts in the low power power state.
  • When the device is opened via the API, it automatically goes to the on state.
  • When the device is closed via the API, it is sent to the standby power state.
  • If the program crashes and the device is not able to be properly closed via the API, it can be left in the on state.

See the C++ programming examples for an example of configuring the power state.

Linux Notes

USB Throughput

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.

Multiple USB Devices

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:

sudo sh -c ‘echo 32 > /sys/module/usbcore/parameters/usbfs_memory_mb’

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.

Other Programming Languages

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.

Device Connection Errors

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.

Firmware Version 7 (BB60C)

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.

Manual Gain/Attenuation

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 Types

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:

samplePowerDBm = 10.0 * log10(re*re + im*im);

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:

  1. Convert from short to float.
    float re32f = ((float)re16s / 32768.0);
    float im32f = ((float)im16s / 32768.0); // This converts the short to a float in the range of [-1.0 to +1.0]
  2. Scale the floats by the correction value returned from bbGetIQCorrection.
    re32f *= correction;
    im32f *= correction;
  3. Calculate power
    samplePowerDBm = 10.0 * log10(re32f*re32f + im32f*im32f);

I/Q Filtering and Bandwidth Limitations

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

Using a GPS Receiver to Time-Stamp Data

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:

  1. GPS Receiver capable providing NMEA data, specifically the GPRMC string, and a 1PPS output. (Tested with Connor Winfield Xenith TBR FTS500)
  2. The NMEA data must be provided via RS232 (Serial COM port) only once during application startup, releasing the NMEA data stream for other applications such as a “Drive Test Solution” to map out signal strengths.

Order of Operations:

  1. Ensure correct operation of your GPS receiver.
  2. Connect the 1PPS receiver output to port 2 of the device.
  3. Connect the RS232 receiver output to your PC.
  4. Determine the COM port number and baud rate of the data transfer over RS232 to your PC.
  5. Open the device via bbOpenDevice
  6. Ensure the RS232 connection is not open.
  7. Use bbSyncCPUtoGPS to synchronize the API timing with the current GPS time. This function will release the connection when finished.
  8. Configure the device for I/Q streaming.
  9. Before initiating the device, use bbConfigureIO and configure port 2 for an incoming rising edge trigger via BB60C_PORT2_IN_TRIG_RISING_EDGE or BB60D_PORT2_IN_TRIG_RISING_EDGE.
  10. Call bbInitiate(id, BB_STREAMING, BB_TIME_STAMP). The BB_TIME_STAMP argument will tell the API to look for the 1PPS input trigger for timing.
  11. If initiated successfully you can now fetch I/Q data and timestamps with bbGetIQ. The timestamp returned will be the time of the first sample in the array of data collected.

Code Example

See the examples folder in the API download for an example of timestamping the I/Q data using a GPS receiver.

Calculating FFT Size

For a given RBW, the FFT size used for sweeps can be calculated with the following algorithm:

double BestFFTSize = (80.0e6 * WindowBW) / RBW;
double ActualFFTSize = RoundUpToNextPowerOf2(BestFFTSize) * C;
double ZeroPadding = ActualFFTSize - BestFFTSize;

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.

Contact Information

For technical support, email suppo.nosp@m.rt@s.nosp@m.ignal.nosp@m.houn.nosp@m.d.com.

For sales, email sales.nosp@m.@sig.nosp@m.nalho.nosp@m.und..nosp@m.com.