Doc: 9086 WBT Programmers TECH Note WBT-Your All In One RF Test Solution TM Rev: 004
WBT Programmers TECH Note This Tech Note will discuss the API that is available to all users on the WBT product line. This powerful API and WBT framework allows software developers and signal processing algorithm creators full access to create useful applications (called WBT Apps) and easily deploy them to the field. Further, WBT Apps can be licensed and shared with others to run on any compatible WBT product via the WBT App Store or directly by its creator. The reader is encouraged to read QRC s Tech Note, QRC s Wide Band Transcorder (WBT), What it is & How it Works for more information on how the WBT functions as a recording and playback solution, if they have not already done so, as this Tech Note assumes the user understands the WBT framework. Development Environment Developing new applications on the WBT couldn t be easier. QRC provides a Lubuntu Virtual Machine for download on our website (wbt.qrctech.com/api), preloaded with all of the tools you will need. Using this method, you can be sure you have all the right libraries, versions, and tools to immediately be successful. 1
WBT Core Firmware The core firmware of the WBT is the basic operating system of the device, and is maintained exclusively by QRC and provides the basic system functionality of collecting, recording, and playing data streams from and to the RF environment. Only the basic hardware level control of the system is performed by the firmware. The diagram below shows the firmware elements in blue, along with the API elements to be discussed in green and the interfaces from the API to the Core System in pink and purple. Figure 1: WBT Software System Diagram The WBT Daemon is the program code within the WBT that manages the hardware and lower level system interfaces within the WBT. It controls the tuners, disks, file system management, GPIOs, LEDs and all other low level elements within the WBT. The WBT Daemon is also the part of the WBT core firmware that is responsible for handling requests and data delivery to / from the WBT API. The WBT Client is the GUI portion of the WBT that handles user interaction. Nearly all commands that are issued to the product by users are communicated by way of the WBT Client. This part of the WBT Core firmware also hosts and handles the loading, unloading, and control (Start/Stop) of Developer Created WBT Apps. Using this framework, the API is provided to support add on development hosted within the firmware and serves to provide a controlled way for user applications to interact with the system, and share data between themselves. WBT App Components are discussed in the next section. 2
WBT App Components There are currently three (3) types of components that make up a WBT App Package (WPK) that can be used by a WBT. These three components perform different roles within a user designed application based on what the developer is attempting to accomplish. A WPK must have at least 1 of these components by definition, but some WBT Apps may have many instances of 1 or more of these types: WBT GUI App Component is a type of WBT Application element that can interact with the user via the WBT's Graphical User Interface. These apps are loaded into a predefined space within the WBT Client GUI. WBT GUI App Components are typically written in QT Graphics Framework using C++. WBT Service App Component is a type of WBT Application element that does not interact with the user directly via the GUI, but runs in the background in order to perform its job. A WBT Service App is the only kind of WBT Application that may use the WBT QVRT Streaming Components to interact with and to process raw radio data. WBT Service Applications can be written in any programming language supported by the WBT platform, most commonly used are C++ and Python. WBT Plugin App Component [Future] is a type of WBT Application element that overrides or overlays an existing GUI element on the WBT GUI. An example of this type of item would be a modified center frequency control that instead takes channel numbers based on a user selected protocol. At this time, plugins are not supported but will be added in a future version of the API. WBT FPGA App Component [Future] is a type of WBT Application element that allows the user to define a file that is loaded into one of the available FPGA slots within the system. A WBT FPGA App requires either (or both) a GUI App or WBT Service App to then setup the registers and data flow needed to interface this FGPA module with the system streams. WBT Application Development Platform In order to provide a simple yet powerful API for the WBT, the WBT API has been divided into a number of easy to use classes that correspond to different subsystems within the WBT. Each WBT App runs in an isolated sand box designed to assure system integrity in a multiple app environment. It is only through that API which monitors and controls access that any add in module can interact with the system and/or other modules. 3
At the time of this document's writing, these subsystems and their organization are shown below. The purple is the API interface itself. The blue items correspond to Command, Control, Visualization, and Plugin interfaces typically used by WBT GUI App and Plugin App Components. The orange items represent the high data rate QVRT streaming interfaces typically used by WBT Service App Components. Figure 2: WBT API Diagram The following two sections discuss each of these segments in more detail. In both cases, the interface is via exposed classes in the WBT API itself. The API documentation details the exposed classes, methods, and member variables in great detail so these are beyond the scope of this App Note. 4
Command, Control, Visualization, and Plugin Access This section of the API is for lower data rate activities and visualizations. Through this API access area, most of the setting and state(s) within a running WBT platform can be read, and permission can be granted for an App to assume control over a specific setting within the system. A partial list of the items that can be interfaced is provided in the table below for illustration, please consult API documentation for a more complete list. Rx Path 1 Rx Path 2 RX Path N Rx Path 1 Bandwidth Rx Path 2 Bandwidth RX Path N Bandwidth TX Path 1 TX Path 2 TX Path N TX Path 1 File Tx Path 2 File Rx File GPIO Control Low Rate FFT Stream Trigger Events Start Stop Record Path 1 Rx Attenuation Path 2 Rx Attenuation Path N Rx Attenuation Path 1 Tx Gain Path 1 Tx Gain Path N Tx Gain RX 1 Source Antenna RX 2 Source Antenna RX N Srouce Antenna RX 1 Ant Powered RX 2 Ant Powered RX N Ant Powered GPS Data Stream* Drive State* License System LED Control System Information* GUI Outputs * = Indicates Read Only Parameter, others fields can be set as well as read Figure 3: Example WBT API Control Areas Stream Access The Stream Access part of the API provides the ability to read and write high bandwidth data streams. These data streams include I & Q raw data elements (see QVRT stream below) and are very useful for the insertion of user defined capabilities (e.g., FIR Filter, Correlation, etc.). In addition to the native streams supported (RawIQ, and FFT) the API user is able to define their own custom data streams that can be consumed by other WBT App Components to generate secondary streams such as demodulated data (e.g., GSM Symbols, WiFi data packets) or demodulated voice. 5
QVRT Streams The QVRT stream is a specific type of stream within the system that contains packetized I&Q data compliant with the VITA 49 industry standard. The streaming allows multiple types of information including meta data and GPS to be interleaved into the samples that are gathered at the same time. For a full definition of QRC s use of the VITA 49 format please consult the WBT Log File Format documentation. Figure 4: WBT QVRT File Structure Deploying a WBT App Package (WAP) The WBT App Package is the WBT App "as published" and intended to be run on a WBT. This app package contains the code required to install and run a WBT application. It can contain 1 or more of any of the WBT App Components discussed above that are meant to be run as a set of capability or capabilities. Additionally other elements (e.g, icons, configuration information, app specific licenses) can be included based on the developer s needs and preferences. Once loaded in the WBT system, WBT Apps can be selected from the App Manager to be run as desired as well as to auto launch when the product boots. 6
WBT Open Framework Philosophy Now that the API has been discussed, it is worth mentioning that QRC Technologies is fully committed to creating a WBT product that is fully extensible to meet a multitude of test and measurement needs in the market. To support that philosophy, the WBT has been separated into two separate software instances within the product. The first, which we call the WBT core firmware as discussed above. The second is the API extensions. Everything but the most basic hardware control and synchronization is performed via API extension(s) that are open for everyone to use. QRC s own value added applications (for example: Advanced Recording, Advanced Playback, Spectrum Analyzer and Spectrograph displays) use the same API(s) that we make available to everyone, without any special hooks that are not available to all. This philosophy of eating our own dog food is embedded in the WBT team, and assures that those wishing to build and even market applications built upon the WBT Framework will continue to receive support as the product line is expanded and grown. We welcome requests from industry on how to extend the API to make it more useful to accomplish specific user needs, and will be continuing to expand upon the API as needed to enable more and more useful capabilities to the developer community. WBT Application Developer s Roadmap The WBT is a revolutionary development in the world of test and measurement, and as such there are exciting developments on the horizon. Below are some of the most interesting roadmap items for people developing Applications on the WBT framework. For an update on the status of any of these rollouts please contact QRC. WBT App Store The WBT is already supported by a robust update server that can assure the user that they are running the latest firmware release. QRC will be extending this capability to add an App Store which will allow QRC and others to share WBT Apps with the WBT user community easily. This store will allow users to browse available community released WBT Apps install, update, review and rank, and license them. GNU and GNU Radio Companion As of 2.4, the WBT, and the development environment both now support GNU, and GNU Radio Companion. This allows GNU software to run on the WBT. Users are able design, test, and deploy capability in the GNU Framework quickly and easily using this capability. 7
FPGA App Support Users will be able to generate custom FPGA code, and interface to it using the WBT API to provide FPGA based algorithms within the product. These FPGA add ons will also be available through the WBT App store for those wishing to provide advanced filters, processing engines, or other capabilities to the community at large. Fast RF Sweep and Zoom FFT The 2.3 API will support fast RF Sweeping as a mode of use. This will allow the app writer to scan energy at a RBW of their choice from 50 MHZ to 6 GHz as quickly as the hardware can (up to 10 GHz/sec when sweeping more than 80 MHz, or significantly faster than even that when stationary). This performance is used to allow users to write very fast reacting software and avoid missing even quick burst signals across the tunable range of the product. In 2.4, a Zoom FFT will be provided that will allow display of frequency data to be within any subset of the collected data stream for real time analysis. Additional API features Based upon community requests, QRC will continue to expand upon the API to provide additional capabilities for inter app and physical device control on the product. WBT Virtual Environments The WBT uses a Debian Linux based OS as its foundation. For those wishing to use a different OS environment (e.g., Windows, Android, GNU, Redhawk, other Linux variants, etc.) the WBT will provide virtual environments that support the WBT API. This capability will allow the running of applications that may already exist in other environments to trigger/control the WBT hardware as well as access the QVRT streams within the product. 8
Systems Integrator for the Cellular Community Since 1987 WBT-Your All In One RF Test Solution TM