With the need to meet multiple RF communication standards on one device and shorten software development cycles, RF test engineers must adopt a well-defined and scalable software architecture. This document provides an introduction to the NI RF Communications Reference Architecture developed by NI RF systems engineers to rapidly deliver RF generation and analysis capabilities to customers and partners.
The core premise behind a reference architecture is not to provide end users a toolkit or product but rather a demonstrated implementation they can adopt and modify or use as is. Reference designs or architectures are application-oriented examples from NI systems engineers based on proofs of concept created for NI customers. Unlike shipping examples that demonstrate product features, reference designs demonstrate how to design and integrate systems. NI publishes these examples to share its application recommendations with the user community.
The NI RF Communications Reference Architecture offers a protocol-agnostic software structure, an open architecture, and a partitioning of responsibilities between hardware and protocol IP code. The primary target application for this architecture is production test, where stability, simplicity, and determinism take priority. Internally, NI has determined the following key guidelines and goals:
- Maintain an open understandable architecture
- Leverage code reuse
- Protect only core generation and processing algorithms
- Support easy use in NI TestStand software
- Allow for identical NI LabVIEW software and DLL interfaces and functionality
Each of these goals shaped the NI RF Communications Reference Architecture, but they are applicable to any architecture that has a variety of final implementations and end users. An example of this is making the trade-off between speed and an easily understandable architecture. A precursor to this architecture used a highly parallelized design that took advantage of multicore processors but became difficult to maintain and extend its abilities from an end-user perspective. Designing the top-level code "exports" in a way that is easily portable to a DLL, although not always necessary, drove NI engineers to simplify the connector pane definition for each function, which, in turn, made the interface to NI TestStand easier.
The code featured in this paper is a basic implementation of the reference architecture that has enabled the NI RF Systems Engineering Team to provide RF proofs of concept for a variety of customers. It demonstrates the flexibility and strong structure of the design, and it is free to use and adapt for your unique implementation. Keep in mind that following the design and structure closely allows easier integration with other tools and reference architectures that the RF Systems Engineering Team releases based on this one.
This document examines the design building blocks and cornerstones of the NI RF Communications Reference Architecture and establishes a base for extending the architecture for new/undeveloped protocols. In addition, the paper includes alternatives to some of the architecture implementation. As is with all reference architectures, taking advantage of this free resource can greatly speed your design process, but you need a proper understanding of the overall architecture.
1. Reference Architecture Structure and Key Components
Measurement and Generation Components
The reference architecture components are organized into a well-defined hierarchy that is shown in Figure 1.
Figure 1. Graphical View of the Reference Architecture Protocol Component Hierarchy
At the highest level, components are separated by protocol. These protocols include niBasic, which contains common measurements not specific to any wireless standard, as well as any other protocols developed by NI or third parties.
Each protocol contains two function types: signal analysis and signal generation. These function types contain a variety of functions for either acquiring and analyzing data (signal analysis) or generating data (signal generation). Some examples of measurement functions from niBasic include the following:
- Adjacent Channel Power (ACP)
- Complementary Cumulative Density Function (CCDF)
- Channel Power (CHP)
- Intermodulation (IM)
- Occupied Bandwidth (OBW)
- Spectral Emissions (SEM)
Each function contains five types of components:
- Documentation: All exports are documented here. This documentation is for API reference only and is not intended to explain the measurement algorithm.
- Examples: These contain all of the examples related to the measurement. These are discussed further below.
- Exports: These contain all of the top-level VIs needed to configure the hardware and measurement parameters, perform the measurement, and return the results. All of the included examples are built from these VIs. A user who does not wish to modify the reference architecture should use only these VIs. All exported VIs are open for any user who wishes to modify them or see how they work.
- Includes: These contain strict typedefs for all the controls and indicators of the reference architecture. Using strict typedefs allows for changes inside the framework to quickly propagate to all affected VIs. It also ensures that all of the controls are well-documented in the Context Help.
- Measurement/Generation: These folders contain all the necessary IP to create a waveform or to perform a measurement. These components and their contents are described in the section titled "Reference Architecture API in Detail."
Components for interacting with NI hardware are contained in their own hierarchy that is almost identical to that of the protocol components (Figure 2).
Figure 2. Graphical View of the Reference Architecture Hardware Component Hierarchy
niSystem contains all of the VIs you need to control hardware supported by NI. Most of these VIs simply communicate directly with the niRFSA and niRFSG drivers, but they are part of the unified interface of this framework that makes the API appear more consistent and familiar to someone used to working with GPIB instrument drivers.
The hierarchy of protocol and hardware components is mirrored in the folder structure of the reference architecture code in the \user.lib\niRF folder. niSystem is stored alongside the protocol folders at the top level of the hierarchy. Figure 3 shows a portion of the folder structure.
Figure 3. A Portion of the Reference Architecture Folder Hierarchy
There are three types of examples:
- Interactive examples, also called application examples, are located on the desktop after installation. These examples, which are designed to function as soft front panels, provide an interactive interface to perform measurements or generation.
- Reference examples demonstrate the simplest and most straightforward way to perform a measurement. You can use these examples to familiarize yourself with a measurement's VIs. They are also designed to be used as a starting point for creating customized measurement code.
- NI TestStand examples show how to create your own NI TestStand sequences. These are ready to run in loopback mode.
NI TestStand Integration
The architecture components have been designed to be easily used in NI TestStand as well as LabVIEW. The measurement configuration handle can simply be passed as an integer, and the rest of the inputs and outputs map easily to NI TestStand data types. Example sequences are included with the reference architecture, and a sequence is shown in Figure 4.
Figure 4. An Example Reference Architecture NI TestStand Sequence
2. Reference Architecture API
This section explains each of the building blocks of a Measurement VI and a Generation VI to help you create custom measurements or modify current ones.
Starting from one of the installed examples, each of the following sections describes the component, how it actually works, and why it is important. Figure 5 shows the block diagram of one of the installed examples (niBasic - RFSA - Waveform - Example.vi), which is used as a reference in the following sections.
Figure 5. Waveform Measurement Example
The top row of VIs in Figure 2 contains the hardware configuration VIs, located under niSystem\SA\Exports. They are responsible for directly configuring hardware properties that are not dependent on the measurement settings. This typically includes settings like clock reference, center frequency, and power level.
These VIs usually call the appropriate NI driver API directly. For example, niSYS - RFSA - Set Max Input Power.vi sets input power using an niRFSA property node (Figure 6).
Figure 6. niRFSA Calls under All Exports of niSystem
The most commonly used functions for signal analysis and measurement have been wrapped into exported VIs. The reference architecture assumes that the user is familiar with the driver and understands any changes made to the system exports and the creation of new ones.
The bottom row of VIs in Figure 5 contains the measurement configuration VIs. All of these VIs are located under the Exports folder of the specific measurement with names that start with "set" or "get," depending on whether the export "sets" or "gets" a parameter.
The measurement configuration data is stored in a measurement-specific cluster, which is stored inside a Notifier. The Notifier handle, instead of the full configuration cluster, is passed between measurement configuration VIs. This reduces data copies, improves performance, and makes the API more compatible with NI TestStand and other ADEs.
Figure 7. In this measurement configuration example, the configuration is stored in a cluster that resides on a LabVIEW Notifier. Only the Notifier is passed from export to export.
To initialize a new measurement, the user needs to call the Initialize VI (niBasic - SA - Waveform - Initialize.vi) and use the handle to configure any nondefault parameter. By default, a global constant with valid measurement parameters is used to initialize the Notifier.
Notice that you can change the Notifier name in case of multiple measurement configurations. The reference architecture assumes that any user trying to change the configuration code is familiar with LabVIEW and understands the pieces that may cause any change.
The Measure VI performs the measurement and returns the requested data. At the Export level, the Measure VI is actually a functional global/state machine VI with a "Measurement Request" control that selects the state. Measure VIs have a "Measure" state and one or more "Fetch" states. This way, if multiple measurement traces are required, the user performs the measurement once and then simply returns different sets of data on subsequent calls, which reduces measurement time.
The several different operations inside the Measure VI are discussed later in this document. Figure 8 shows the block diagram of the niBasic - RFSA - Waveform - Measure.vi.
Figure 8. Measure Export Functional Block Diagram (top) and niBasic - RFSA - Waveform - Measure.vi Code Example (bottom)
The Autoconfigure VI is a measurement-specific VI that converts the requested settings for a particular measurement into recommended settings for hardware. For example, the waveform measurement allows for configuration of the RBW filter type and waveform averaging settings. These settings translate into the number of records, acquisition sampling rate, and acquisition time. The output of this VI is a cluster of recommended settings. The hardware is expected to accept these settings. If not, the user has to make sure these settings are correct before feeding the data into the Measurement Component.
Configure Hardware Settings
After running the Autoconfigure VI, you need to apply the recommended settings to the hardware. The examples from NI take all of the recommended settings from the Autoconfigure VI and configure the hardware accordingly.
Once the hardware has been configured, data acquisition is started with the niRFSA Initiate VI. Once acquisition has begun, I/Q data is retrieved from the RFSA onboard memory using niRFSA Fetch one record at a time, depending on the number of requested averages. This improves measurement time for multiple averages and reduces the complexity of conducting the average later in the process.
The measure VI assumes t0 to be exactly at the trigger location; therefore, it is overridden by the autoconfigure "post-trigger delay" output.
Once you have acquired I/Q data, you pass it to the component-level Measure VI. This VI takes in the measurement configuration cluster as well as I/Q data and returns measurement values. Data is returned in two forms: a LabVIEW cluster of common measurement data as well as an array of traces. Each trace is a 1D array of DLLs with a different measurement result, and the traces are combined into a 2D array in the order defined in the measurement-specific Measurement Trace Type enum. This allows for easy access to the data in NI TestStand and other ADEs.
The Measure VI assumes that the I/Q data has the properties requested by the Autoconfigure VI. This is true by default with the 6.6 GHz NI hardware family, with which this reference architecture is meant to be used.
To understand the architecture of the generation code, use the installed example niBasic - RFSG - CW.vi as a reference during all of the following sections. This example, like all of the generation code, uses niRFSG script mode for flexible configuration of waveform generation. This document describes the basic functionality of Script mode. For advanced scripting functionality, refer to the niRFSG documentation for more information. Figure 9 shows the programming flow of the generation code.
Figure 9. Generator Code Functional Block Diagram (top) and Generator Code for CW (bottom)
The VIs located under niSystem\SG\Exports are responsible for directly configuring hardware properties. This typically includes settings like clock reference, center frequency, output enable, and power level.
These VIs usually call the appropriate NI driver API directly. For example, niSYS - RFSG - Set Center Frequency.vi sets the center frequency using an niRFSG property node (Figure 10).
Figure 10. niSYS - RFSG - Set Center Frequency.vi
The following sections review the details of creating a waveform and initializing the generation.
The most commonly used functionality for generation has been wrapped into the signal generator exports. When the hardware is initialized, the following aspects of the niRFSG are used:
- The hardware is always in Script mode for maximum flexibility of the generation.
- The hardware always uses the high-resolution clock to generate at the exact I/Q rate.
- The generator always uses Peak Power mode, which is required when using Script mode.
The reference architecture helps the user follow which waveforms and scripts are already on the hardware using a local database. This helps keep track of these important waveform parameters:
- Sampling rate (I/Q rate)
- Correct peak output power setting for each waveform
Figure 11. Initialization of the SG Hardware
A Create Waveform VI is called for each separate waveform to be generated in a generation session. Any waveform-specific settings are passed to the VI in a cluster. (In this case, because you are generating a single-tone CW, there are no waveform-specific settings). The block diagram of niBasic - RFSG - CW - Create Signal.vi is shown in Figure 12.
Figure 12. Creating and Downloading the CW Waveform
The first VI creates the waveform I/Q data based on the configuration cluster. For a CW, no parameters are needed, but the user can place any other created waveform and add it to the architecture. The output waveform is assumed to have an average power of 0 dBm.
Headroom allows the user to control the generation of multiple waveforms at different power levels or to avoid clipping any waveform with a large peak-to-average ratio (PAR). By default, headroom is calculated to optimize the dynamic range of the generator.
The next step is to apply any perturbations to the signal. This VI is a generic wrapper of the Modulation Toolkit VI that helps to quickly add perturbations to a signal.
RFSG Write and Waveform Database
The waveform is then written to hardware memory. Its properties are also stored in the Waveform Database VI, which is used later to configure hardware settings based on all of the waveforms that have been loaded on the hardware.
The Start Generation VI reads I/Q rate and headroom parameters from all of the waveforms in the aforementioned waveform database and configures the sample rate and power level of the generator. This VI also reads and applies the RFSG script, and saves it in a Script Database VI for later use if necessary. Finally, the Start Generation VI calls niRFSG Initiate.vi, which starts hardware generation.
A few example scripts that show how to generate two different waveforms (cw and idle) are included below.
The Script generates a continuous waveform (cw) until generation is aborted:
The Script generates a continuous waveform (cw) and then two times the idle waveform and repeats until generation is aborted:
end repeat end script
This VI returns a warning if the headroom of all the waveforms is not the same and returns an error if the I/Q rates are different. It is assumed that the user is familiar with this terminology in case any change of functionality is needed.
Once you have begun generation, you cannot load anymore waveforms into RFSG memory; however, you can monitor or change certain parameters and use Script mode to control generation. The CW example shown in Figure 5 (bottom) shows on-the-fly updating of the RFSG power level and center frequency inside the while loop. You also can use this loop to send script triggers to the RFSG, watch for errors during a continuous generation, or wait for completion of a finite generation.
The reference architecture assumes that all waveforms needed for a specific test are loaded into the hardware at the beginning. After that, using different scripts, you can generate each waveform. This reduces measurement time.
3. Decisions Behind the Design
The preceding sections of this document describe the structure of the NI RF Communications Reference Architecture at a basic level. However, when attempting to build off of or extend parts of the existing code, understanding the reasons behind some design decisions is important. This section reviews some of these design decisions to provide a thorough background and help you work with the architecture.
Exports cover the entire scope of the architecture. In both signal generation and analysis and in every function type, from the basic waveform generation associated with this white paper to fully custom protocol measurements implemented as a POC.
Design: All "export" parameters are represented by scalar values or collections of scalar numerics.
Reason: API Exports need to be portable to other environments, such as NI TestStand, .NET and DLLs. Without this design requirement, adding more complex items as parameters to the exports, such as nested structures and or combinations of clusters and arrays, would make potentially interacting with the exports in these other environments much more cumbersome than is necessary. This also maximizes code reuse across applications and platforms.
A collection of input parameters demonstrates this well. For a given group of parameters where all are numerics except for one Boolean value, a sound design choice in this case would be to replace the Boolean with an enumeration so that the collection would remain a simple collection of numerics.
The setting and storage of configuration parameters is a primary function of many top-level exports. The parameters that need to be updated or modified regularly in test and are used in downstream processing (averaging, signal type) need to be kept in a storage mechanism for setting and retrieval.
Design: Use the capabilities of a LabVIEW Notifier to act as a means of "by reference" storage for the parameters used in downstream processing.
Reason: The entire configuration of a measurement is a collection of many other scalars and collections (clusters). Passing this entire cluster by value through VIs, NI TestStand, or DLLs has two key drawbacks:
- Parameters cannot be set asynchronously.
- The function definition (connector pane, argument list) of many top-level VIs is coupled to that cluster.
Having the ability to asynchronously set configuration parameters allows a variety of dynamic code designs, which might be limited by adhering to data flow. Other methods of storage and asynchronous design are possible and have been implemented in parallel to this architecture. Of these methods, LVOOP, Data by Reference, and Single Element Queues (SEQ) are the strongest alternatives. Each provides its own benefits but requires modification to the reference architecture for use.
Because the majority of the deployments of this reference architecture interface with NI TestStand, the chosen configuration management design should be easy to use in NI TestStand. Because typedefs do not automatically update in NI TestStand, it is much easier to pass a configuration reference (U32) between many exports and rely on the VI call to modify or extract the appropriate value.
Measurement Trace Lookup
Core measurement IP is locked down to protect the investment in algorithm design. But to assist in the process of designing software around the architecture and debugging, certain signals in the processing chain have been assembled and made available as export traces on the measurement export.
Design: Each measurement component VI should make available via a "Traces Array" relevant intermediate waveforms and results. This array should minimally export the unprocessed I/Q data and the Scalar Results cluster.
The most straightforward path to debugging incorrect results is to interactively inspect the values on the wires during the processing. However, it takes a significant amount of time to create and test a processing algorithm and keeping that knowledge private in a password-protected VI is important. Recognizing this limitation, this reference architecture defines a pathway to the top level for the information that remains inside those locked VIs.
In addition, in applications where the Measurement VI is not the highest-level VI in an application, the traces allow retrieval of unprocessed data for use by other VIs or programs.
4. Download the Architecture
Find the reference architecture code on the RF Test Reference Architecture page on NI Community.
This reference application was created by the NI Systems Engineering group.
We do not regularly monitor reader comments posted on this page.
Please submit your feedback in the Introduction to the NI RF and Communications Architecture discussion forum so that we can improve this component for future applications.
Please direct support questions to the RF Test Reference Architecture Community Page.