VST Basics Programming Guide

Transcription

1 Application Note November 2015 VST Basics Programming Guide Cobham Wireless - Validation Application Note 46900/845

2 VST Introduction VST Basics Programming Guide 1 VST Introduction The Purpose of this document Intended Audience Scope Where Can I Get More Information? What Programming Languages Can I Use? Where Can I Get the VST Driver(s) From? Setting Up the Programming Environment Visual Studio (2010) C Setting up the Programming Environment for C#.NET Booting, Closing Down and Configuring the Reference Clock Booting the VST Module Configuring the Reference Clock Example of Booting and Configuring Reference Clock Checking For Errors Closing down the Instrument RFSA Basics Configuring the RFSA for IQ Capture RFSA Capture Parameters Configure the RFSA Number of Records RFSA Capture Triggering Starting the Capture and Retrieving IQ Samples RFSG Basics Configuring RFSG Configuring the RFSG RF Parameters Configuring the RFSG for CW Tone Generation Configuring the RFSG for Waveform Generation Waveform Playback Triggers Stopping Waveform Playback RFSA/RFSG Self Calibration Example Code Appendix A Cobham - 2 -

3 VST Introduction VST Basics Programming Guide 1 VST Introduction NI PXIe modular vector signal transceivers (VSTs) combine a vector signal analyzer and vector signal generator with a user-programmable FPGA for real-time signal processing and control. Built on the NI LabVIEW reconfigurable I/O (RIO) architecture, it delivers programming flexibility and cutting-edge RF hardware to meet the most challenging RF applications. 1.1 The Purpose of this document This document is intended to bring together in one document a primer on programming the NI VST module. It covers the basics of where to get the software, how to configure the development environment for both C#.NET and C/C++ and how to perform the VSA and VSG basics. 1.2 Intended Audience This Application note is aimed at customers or Cobham Application engineers who are starting to write software against the NI VST module. 1.3 Scope This document is relevant for any NI VST module 5644r/5645r/5646r although 5644r is used as an example throughout. This document excludes discussion of advanced topics such as list mode operation or how to interface with the COBHAM analysis library. 1.4 Where Can I Get More Information? Once installed the RFSG and RFSA driver contains entries in the Start menu for Help Files which describe in more detail all of the method calls. Provides details on features, specification, data sheets and other resources. 1.5 What Programming Languages Can I Use? C C Cobham - 3 -

4 VST Introduction.NET (C# and VB). (2 types of.net interface exist and this document uses the C/C++ wrapper variant for examples rather than the dedicated.net interface.) LabVIEW 1.6 Where Can I Get the VST Driver(s) From? NI-RFSA or NI-RFSG is the download to select. Despite the name, both download contain the module driver component for the RFSG and RFSA.( C/C++ interface only ) Warning the file size is extremely large (~ 3.8 GB) and so a local copy should be sought. The.NET class driver and the.net wrapper can be found: Cobham - 4 -

5 Setting Up the Programming Environment 2 Setting Up the Programming Environment This document only describes how to setup the programming environment for C/C++ and C#.NET in the Visual Studio IDE. 2.1 Visual Studio (2010) C++ The VST driver uses library (.lib) files to control the HW. A separate library is used for the VSA and the VSG. (nirfsa.lib and nirfsg.lib ) Using Visual Studio 2010 as a guide the steps to reference the required libraries are as follows. 1. Add a path to the header files by right clicking on your C++ project within the solution explorer and selecting properties. Figure 1 - Select Project Properties. 2. Select C/C++ from the panel on the left hand side and select Additional Include Directories 2015 Cobham - 5 -

6 Setting Up the Programming Environment Figure 2 - Add Additional Include Directories. 3. Enter the paths as seen in Figure 3. Figure 3 - Add these file paths to the include files to your project. 4. Select the linker item from the left hand panel in the project property page and then select General and then select and edit the Additional Library Directories 2015 Cobham - 6 -

7 Setting Up the Programming Environment Figure 4 - Select the Additional Library Directories 5. Enter the paths as seen in Figure 5. Figure 5 - Add these file paths to the include files to your project Cobham - 7 -

8 Setting Up the Programming Environment 6. Add the actual library files to be used. This is achieved by selecting the Input menu item from the left most panel in the project properties and selecting and editing the Additional Dependency setting. Figure 6 - Select the Additional Dependencies Setting 7. Enter the files as seen in Figure 7. Figure 7 - Add these library files as Additional Dependencies to your project Cobham - 8 -

9 Setting Up the Programming Environment 8. Now Add the Include files: #include "nirfsg.h" #include "nirfsa.h" 9. And now VST method calls can be made e.g. // Initiate VSA session status = nirfsa_init("rio0", VI_TRUE, VI_TRUE, &vsa); 2.2 Setting up the Programming Environment for C#.NET The NI C# interface is a separate C# file (nirfsa.cs and nirfsg.cs) that defines a series of method which call the underlying methods in the RFSA.dll and RFSG.dll using pinvoke. Add the nirfsa.cs, nirfsg.cs and niinteropcommon.cs files to your project as seen in Figure 8. Figure 8 - Adding the RFSA C# Wrapper File. Then add the NationalInstruments.ModularInstruments.Interop namespace to your project files. using NationalInstruments.ModularInstruments.Interop; 2015 Cobham - 9 -

10 Booting, Closing Down and Configuring the Reference Clock 3 Booting, Closing Down and Configuring the Reference Clock 3.1 Booting the VST Module The VST has two components, the RFSG (signal generation) and the RFSA (vector digitizer). Both are booted separately. Booting the RFSA can be accomplished using two different method; nirfsa_init or nirfsa_initwithoptions. Booting the RFSG can be accomplished using two different method; nirfsg_init() or nirfsg_initwithoptions(). Both the RFSA and the RFSG boot methods require the resource name of the VST.This can be found by loading National Instrument s Measurement and Automation Explorer application (also known as NI MAX), expanding the chassis object in the left most panel will reveal the PXIe cards. We re interested in the 5644R device. Clicking on it as seen in Figure 9 reveals more details about that device and the Device Name can then be seen. (RIO0 in this case.) Figure 9 - Finding the VST Device Name 2015 Cobham

11 Booting, Closing Down and Configuring the Reference Clock WARNING: When booting Cobham PXI 3000 modules the VISA resource name is supplied to the boot method rather than the Device Name. The parameters for the nirfsa_init(c/c++) method or the nirfsa constructor (C#) are as follows: ResourceName Specifies the resource name of the device to initialize. IDQuery Specifies whether NI RFSA performs an ID query. When you perform an ID query, NI RFSA verifies the device you initialize is supported. Reset Specifies whether the NI RFSA device is reset during the initialization procedure. The output is: VI Identifier to the instrument session. Using the nirfsa_initwithoptions method has an additional parameter: OptionString Sets the initial value of certain attributes for the session. More details can be found in the NI RFSA documentation. 3.2 Configuring the Reference Clock To configure the Reference clock two methods are required; One to configure the settings (nirfsa_configurerefclock) and one to commit the setting (nirfsa_commit). The parameters for the nirfsa_configurerefclock method are as follows: Vi - Identifies the instrument session. Vi is obtained from the nirfsa_init or nirfsa_initwithoptions method. ClockSource - Specifies the Reference Clock source: Setting NIRFSA_VAL_ONBOARD_CLOCK_STR ("OnboardClock") NIRFSA_VAL_REF_IN_STR ("RefIn") Comment Lock the NI-RFSA device to its onboard clock. Lock the NI-RFSA device to the signal at the external REF IN connector. NIRFSA_VAL_PXI_CLK_STR ("PXI_Clk") NI-RFSA locks the to the PXI backplane clock. RefClockRate Specifies the Reference Clock rate in hertz (Hz). For the VST, 10 MHz is the only supported value. 3.3 Example of Booting and Configuring Reference Clock Below are examples of booting the RFSA and configuring the VST to use it s on board 10MHz reference clock. A similar technique is used for the RFSG but the method call is nirfsg_init() C/C++ Example ViStatus status; ViSession vsa = VI_NULL; ViReal64 referenceclockrate = 10e6; // 10 MHz ( VST only supports 10 MHz ) 2015 Cobham

12 Booting, Closing Down and Configuring the Reference Clock // Initiate VSA session status = nirfsa_init("rio0", VI_TRUE, VI_TRUE, &vsa); // Configure 10MHz reference status = nirfsa_configurerefclock(vsa, NIRFSA_VAL_ONBOARD_CLOCK_STR, referenceclockrate); // Commit the settings to make clock settings active status = nirfsa_commit(vsa); Figure 10 - Boot and Configure 10MHz Reference C/C C#.NET Example int status; nirfsa Rfsa; double referenceclockrate = 10e6; // 10 MHz ( VST only supports 10 MHz ) // Initiate VSA session Rfsa = new nirfsa("rio0",true,false); // Configure 10MHz reference status = Rfsa.ConfigureRefClock("OnboardClock", referenceclockrate); ErrorCheckRFSA(Rfsa,status); // Commit the settings to make clock settings active status = Rfsa.Commit(); ErrorCheckRFSA(Rfsa,status); Figure 11 - Boot and Configure 10MHz Reference C# 3.4 Checking For Errors All C# and C++ methods return a status code which uses the following convention: Value Meaning 0 Success Positive Values Warnings Negative Values Errors C/C++ Example A method nirfsa_error_message can be used to convert the error code to an error message. The example code in Figure 12 can be used to display a warning or error message void ErrorCheckRFSA(ViSession Vsa, ViStatus Status) { ViChar errmsg[256]; if ( Status > 0 ) // Warning 2015 Cobham

13 Booting, Closing Down and Configuring the Reference Clock { // Retrieve the error message based on the status code. nirfsa_error_message(vsa, Status, errmsg); std::cout << "Warning : "; // Loop through the array of chars printing them out to the STDOUT. for( int i = 0 ; i < strlen(errmsg) ; i ++ ) { std::cout << errmsg[i]; } std::cout << std::endl; } else if ( Status < 0 ) // Error { // Retrieve the error message based on the status code. nirfsa_error_message(vsa, Status, errmsg); std::cout << "Error : "; } } // Loop through the array of chars printing them out to the STDOUT. for( int i = 0 ; i < strlen(errmsg) ; i ++ ) { std::cout << errmsg[i]; } std::cout << std::endl; Figure 12 - RFSA Method to Check For Errors and Warnings.( C/C++) C# Example A method ErrorMessage can be used to convert the error code to an error message. The example code in Figure 13 can be used to display a warning message. Warning : The NI C# wrapper provided throws an exception before returning the error code if the error code is negative (an error) but not if the error code is positive or zero indicating success or a warning. private void ErrorCheckRFSA(niRFSA Rfsa, int Status) { StringBuilder sb = new StringBuilder(256); if (Status > 0) // Warning { // Retrieve the error message based on the status code. Rfsa.ErrorMessage(Status, sb); } } Console.WriteLine("Warning : " + sb.tostring()); Figure 13 - RFSA Method to Check For Errors and Warnings. (C#) Note : The RFSG contains similar methods Cobham

14 Booting, Closing Down and Configuring the Reference Clock 3.5 Closing down the Instrument Once finished with the RFVSA close down the instrument to free up allocated resources C/C++ Example ViStatus status; // Close session status = nirfsa_close(vsa); C# Example // Close session vsa.close(); Note the C# method does not return any error codes but will throw an exception if an error occurs during the Close() method call Cobham

15 RFSA Basics 4 RFSA Basics The RFSA can be used in a number of complex ways such as in list mode or with a custom FPGA. This section describes simple IQ capture. A full state diagram can be seen in Appendix A. 4.1 Configuring the RFSA for IQ Capture The RFSA can operate in one of two modes. It can be setup to capture IQ or to capture a spectrum. Calling nirfsa_configureacquisitiontype selects one of the two modes with spectrum being selected with the parameter set to NIRFSA_VAL_SPECTRUM and the IQ capture mode can be set by using NIRFSA_VAL_IQ as the parameter C/C++ Example // // Configure VST for capture // status = nirfsa_configureacquisitiontype(vsa, NIRFSA_VAL_IQ); // IQ capture mode C# Example // // Configure VST for capture // status = Rfsa.ConfigureAcquisitionType(niRFSAConstants.Iq); // IQ capture mode ErrorCheckRFSA(Rfsa,status); 4.2 RFSA Capture Parameters A digitizer IQ capture requires some basic settings such as frequency the capture is to be made at, the capture length, the input range of the capture, the sample rate that the capture will be made at and any trigger settings. The second parameter identifies the channel at which to apply the setting value which as List-Mode is not being used can be set to VI_NULL The dwell time or capture length like PXI 3000 is expressed in samples and so a basic conversion of Sample Rate in Hz * Dwell Time in seconds will yield the number of samples required. The RFSA operates in one of two modes when capturing IQ samples. It can either capture a finite number of samples or acquire samples continuously until the nirfsa_abort method is called. When operating in the continuously acquire mode the device stores data in onboard memory in a circular fashion. After the device fills the memory, it starts overwriting previously acquired data from the beginning of the memory buffer. Retrieve the samples as they are being acquired, using one of the nirfsa fetch I/Q functions, to avoid overwriting data before you retrieve it. Selecting between the two modes is done by setting the third parameter to the 2015 Cobham

16 RFSA Basics nirfsa_configurenumberofsamples method to VI_TRUE or VI_FALSE. VI_True for finite mode and VI_FALSE for acquire continuously C/C++ Example ViStatus status; ViReal64 CarrierFrequency = 1e9; ViReal64 ReferenceLevel = 20; ViReal64 DwellTime = 1e 3; ViReal64 SampleRate = 40e6; // 1 GHz // 20 dbm // 1 ms capture time. // 40 MHz sample rate // Set Frequency in Hz. status = nirfsa_configureiqcarrierfrequency(vsa, VI_NULL, CarrierFrequency); // Set Expected Input level in dbm. status = nirfsa_configurereferencelevel(vsa, VI_NULL, ReferenceLevel); // Set Sample Rate in Hz. status = nirfsa_configureiqrate(vsa, VI_NULL, SampleRate); // Convert the dwell time and the capture sample rate to number of samples. ViInt64 numsamples = (ViInt64)(DwellTime * SampleRate); // Set Number of samples. status = nirfsa_configurenumberofsamples(vsa, VI_NULL, VI_TRUE, numsamples); C# Example double carrierfrequency = 2.0e9; // 2 GHz. double referencelevel = 20; // 20 dbm double dwelltime = 1e 3; // 1 ms. double samplerate = 40e6; // 40 MHz long numsamples = (long)(dwelltime * samplerate); // Set Frequency in Hz status = Rfsa.ConfigureIQCarrierFrequency("", carrierfrequency); ErrorCheckRFSA(Rfsa, status); // Set Level in dbm status = Rfsa.ConfigureReferenceLevel("", referencelevel); ErrorCheckRFSA(Rfsa, status); // Set sample rate in Hz. status = Rfsa.ConfigureIQRate("", samplerate); ErrorCheckRFSA(Rfsa, status); // Number of samples status = Rfsa.ConfigureNumberOfSamples("", true, numsamples); ErrorCheckRFSA(Rfsa, status); 2015 Cobham

17 RFSA Basics 4.3 Configure the RFSA Number of Records The RFSA performs captures and stores the IQ in records. Each record can have a series of RF capture settings as described in 4.2. As part of a capture the number of records to acquire needs to be set and also if the record captures are going to be continuous. This is achieved in C/C++ using the nirfsa_configurenumberofrecords method or in C# with the ConfigureNumberOfRecords method C/C++ Example // Set Number of records. status = nirfsa_configurenumberofrecords(vsa, VI_NULL, VI_TRUE, 1); C# Example // Number of records status = Rfsa.ConfigureNumberOfRecords("", true, 1); ErrorCheckRFSA(Rfsa, status); 4.4 RFSA Capture Triggering Triggers cause the RFSA to start its capture. The RFSA supports a number of complex trigger types. This section covers some of the more basic varieties Free Run or Immediate Trigger If no trigger is selected then the capture starts when the C/C++ nirfsa_initiate() or C# Initiate() method is called and the behavior is similar to a free run trigger or a PXI 3000 digitizer when the trigger source is set to afdigitizerdll_tssw_trig. This can be achieved in the RFSA by a C/C++ call to nirfsa_disablestarttrigger() or a C# call to DisableStartTrigger() C/C++ Example // Set an Immediate trigger. status = nirfsa_disablestarttrigger(vsa); C# Example // Set an Immediate trigger. status = Rfsa.DisableStartTrigger(); ErrorCheckRFSA(Rfsa, status); Software Trigger The RFSA supports a software trigger which arms the RFSA but does not start a capture until the software trigger method is called. A C/C++ call to nirfsa_configuresoftwareedgestarttrigger() or a C# call to ConfigureDigitalEdgeStartTrigger enables the software trigger. A C/C++ call to 2015 Cobham

18 RFSA Basics nirfsa_sendsoftwareedgetrigger or a C# call to SendSoftwareEdgeTrigger sends the software trigger that starts the IQ capture C/C++ Example ViStatus status; // Define a software trigger status = nirfsa_configuresoftwareedgestarttrigger(vsa); // RFSA now armed and waiting for trigger status = nirfsa_initiate(vsa); // Send software trigger status = nirfsa_sendsoftwareedgetrigger(vsa, NIRFSA_VAL_START_TRIGGER,""); C# Example // Define a software trigger. Rfsa.ConfigureSoftwareEdgeStartTrigger(); ErrorCheckRFSA(Rfsa, status); // Start capture status = Rfsa.Initiate(); ErrorCheckRFSA(Rfsa, status); // Send software trigger status = Rfsa.SendSoftwareEdgeTrigger(niRFSAConstants.StartTrigger, ""); ErrorCheckRFSA(Rfsa, status); RF Level or Burst Trigger To set a RF Level trigger or Burst trigger a C/C++ call to nirfsa_configureiqpoweredgereftrigger or a C# call to ConfigureIQPowerEdgeRefTrigger allows the RF level in dbm (absolute level), any trigger delay in samples and the polarity of the trigger EDGE to be set. All start triggers should be disabled C/C++ Example // Disable any start triggers status = nirfsa_disablestarttrigger(vsa); // Define the trigger level and a pre trigger ViReal64 triggerlevel = 20; // 20 dbm ViInt64 pretriggersamples = (ViInt64)(100e 6 * samplerate); // 100uS worth. status = nirfsa_configureiqpoweredgereftrigger(vsa,"0", triggerlevel, NIRFSA_VAL_RISING_EDGE, pretriggersamples); 2015 Cobham

19 RFSA Basics C# Example // No Start Triggers status = Rfsa.DisableStartTrigger(); ErrorCheckRFSA(Rfsa, status); double triggerlevel = 20; // 20 dbm long pretriggersamples = (long)(100e 6 * SampleRate); // 100uS worth. // Set the trigger level, slope and pre trigger samples. status = Rfsa.ConfigureIQPowerEdgeRefTrigger("0", triggerlevel, nirfsaconstants.risingedge, pretriggersamples); ErrorCheckRFSA(Rfsa, status); // Define a software trigger. Rfsa.ConfigureSoftwareEdgeStartTrigger(); ErrorCheckRFSA(Rfsa, status); External Trigger An external trigger is a trigger event supplied from an external source such as one of the PXI trigger lines. A large number of options for the trigger source can be configured and the full list can be found in the RFSA Help File. This can be defined in C/C++ with a call to nirfsa_configuredigitaledgestarttrigger and a C# with a call to ConfigureDigitalEdgeStartTrigger C/C++ Example // Set an external trigger on the rising edge of the PXI trigger line 0. status = nirfsa_configuredigitaledgestarttrigger(vsa, NIRFSA_VAL_PXI_TRIG0_STR, NIRFSA_VAL_RISING_EDGE); C# Example // Set an external trigger on the rising edge of the PXI trigger line 0. status = Rfsa.ConfigureDigitalEdgeStartTrigger(niRFSAConstants.Rtsi0Str, nirfsaconstants.risingedge); ErrorCheckRFSA(Rfsa, status); 4.5 Starting the Capture and Retrieving IQ Samples Once all the capture specific settings have been set a C/C++ call to nirfsa_initiate() or a C# call to Initiate() will arm the RFSA and start the IQ acquisition if either a free run trigger was defined or the edge or external trigger conditions were met. The method returns immediately even if the trigger conditions have not been met and a separate C/C++ call to nirfsa_checkacquisitionstatus or a C# call to CheckAcquisitionStatus() can be used to check the status of the capture. Once the acquisition is complete the IQ data needs to be fetched. The RFSA returns the IQ data as an array of complex (imaginary I and real Q) data Cobham

20 RFSA Basics Before fetching the data the reference location within the acquired record from which to begin fetching needs to be defined. This is achieved by setting the attribute NIRFSA_ATTR_FETCH_RELATIVE_TO with one of the following values: Value Description NIRFSA_VAL_MOST_RECENT_SAMPLE (700) Fetching occurs relative to the most recently acquired data. The value of the NIRFSA_ATTR_FETCH_OFFSET attribute must be negative. NIRFSA_VAL_FIRST_SAMPLE (701) Fetching occurs at the first sample acquired by the device. If the device wraps its buffer, the first sample is no longer available. In this case, NI-RFSA returns an error if the fetch offset is in the overwritten data. NIRFSA_VAL_REF_TRIGGER (702) Fetching occurs relative to the Reference Trigger. This value behaves like NIRFSA_VAL_FIRST_SAMPLE if no Reference Trigger is configured. NIRFSA_VAL_FIRST_PRETRIGGER_SAMPLE (703) Fetching occurs relative to the first pretrigger sample acquired. This value behaves like NIRFSA_VAL_FIRST_SAMPLE if no Reference Trigger is configured. NIRFSA_VAL_CURRENT_READ_POSITION (704) Fetching occurs after the last fetched sample. Then a C/C++ call to nirfsa_fetchiqsinglerecordcomplexf32 or a C# call to FetchIQSingleRecordComplexF32 will fetch the complex data into the array specified as a method argument. The method blocks until the record specified has completed its acquisition or until a timeout specified as a method argument expires C/C++ Example nirfsa_wfminfo captureinfo; ViReal64 timeout = 1.0; // VSA now armed and waiting for trigger ( if burst trigger or external trigger used ) or // starting acquisition ( if a free run trigger was setup ) status = nirfsa_initiate(vsa); // Check No errors or warning occured. if(status == 0) { // Create an array of Complex floats to store the IQ data returned from the RFSA. NIComplexNumberF32 *capturediq = new NIComplexNumberF32[numSamples]; // Specifies the reference location within the acquired record from which to begin fetching. ( at the first sample acquired ) status = nirfsa_setattributeviint32(vsa, VI_NULL, NIRFSA_ATTR_FETCH_RELATIVE_TO, NIRFSA_VAL_FIRST_SAMPLE); // Fetch IQ data status = nirfsa_fetchiqsinglerecordcomplexf32(vsa, VI_NULL, 0, 1, timeout, capturediq, &captureinfo); // 1 = fetch all samples 2015 Cobham

21 RFSA Basics // Check to see if the number of samples matches the number of samples returned. if(status == 0 && captureinfo.actualsamples == numsamples) { // Fetch of IQ samples was successful. Now copy the complex values // into a separate I and Q array. for(int i = 0; i < numsamples; i++) { ibuffer[i] = capturediq[i].real; qbuffer[i] = capturediq[i].imaginary; } } else { std::cout << "An error occured during capture ( the number of samples returned does not match what was asked for )!" << std::endl; status = nirfsa_abort(vsa); } } else { } // Free the allocated memory. delete capturediq; std::cout << "An error occured during capture!" << std::endl; status = nirfsa_abort(vsa); C# Example nirfsa_wfminfo captureinfo; double timeout = 10.0; // Start capture status = Rfsa.Initiate(); ErrorCheckRFSA(Rfsa, status); if (status == 0) { // Create an array of Complex doubles to store the IQ data returned // from the RFSA. nicomplexnumber[] capturediq = new nicomplexnumber[numsamples]; // Specifies the reference location within the acquired record from // which to begin fetching. ( at the first sample acquired ) status = Rfsa.SetFetchRelativeTo("0", nirfsaconstants.firstsample); ErrorCheckRFSA(Rfsa, status); // Fetch IQ data status = Rfsa.ReadIQSingleRecordComplexF64("", timeout, capturediq, numsamples, out captureinfo); ErrorCheckRFSA(Rfsa, status); // Check to see if the number of samples matches the number of samples returned. if (status == 0 && captureinfo.actualsamples == numsamples) { 2015 Cobham

22 // Fetch of IQ samples was successful. Now copy the complex // values into a separate I and Q array. for (int i = 0; i < numsamples; i++) { ibuffer[i] = capturediq[i].real; qbuffer[i] = capturediq[i].imaginary; } } else { Console.WriteLine("An error occured during capture ( the number of samples returned does not match what was asked for )!"); status = Rfsa.Abort(); ErrorCheckRFSA(Rfsa, status); } } else { Console.WriteLine("An error occured during capture!"); status = Rfsa.Abort(); ErrorCheckRFSA(Rfsa, status); } 2015 Cobham

23 RFSG Basics 5 RFSG Basics RFSG basics covers generating a CW tone, waveform playback (single, continuous and n-times ) and basic triggering. It does not cover advanced triggering, markers (or scripts ) or list mode / sweep functionality. 5.1 Configuring RFSG The RFSG operates in three distinct modes, 1. Configuration mode where it can be setup. ( No RF is output and settings are not committed to the HW ) 2. Committed mode where settings have been committed to the hardware ( No RF is output ) 1. Generation mode where it is running. 3. The basic premise is that prior to playing out a CW tone or playing a waveform the RFSG will be taken into the Configuration Mode by calling Abort. Once the settings have been made a call to either Commit() to commit then to the HW or a call to Initiate() will start the generation of the waveform or CW tone. The RFSG state diagram can be seen in Figure 14. Figure 14 - RFSG State Diagram The RFSG can be setup to play a CW tone or a Waveform by calling the C/C++ method nirfsg_configuregenerationmode() or the C# method ConfigureGenerationMode() when in Configuration Mode. It supports three parameters: 2015 Cobham

24 RFSG Basics C/C++ C# Description NIRFSG_VAL_CW nirfsgconstants.cw Configures the RF signal generator to generate a CW signal. NIRFSG_VAL_ARB_WAVEFORM nirfsgconstants.arbwaveform Configures the RF signal generator to generate arbitrary waveforms. NIRFSG_VAL_SCRIPT nirfsgconstants.script Configures the RF signal generator to generate arbitrary waveforms as directed by scripts. For the purpose of this document the SCRIPT option shall not be covered, but more information can be found in the RFSG help file. 5.2 Configuring the RFSG RF Parameters Settings such as output level, frequency and output state can be changed once the RFSG is in Generation Mode. The RFSG provides two approaches to configuring these parameters i) use a helper method or ii) use attributes C/C++ Example ViReal64 Frequency = 1e9; // 1 GHz ViReal64 Level = 20; // 20 dbm // Aborts generation & put VSG in configuration mode status = nirfsg_abort(vsg); // // Configure all settings that require the VSG to be in configuration mode // // Configure frequency & level using higher level function status = nirfsg_configurerf(vsg, Frequency, Level); // Note level can also be configured using low level attributes. status = nirfsg_setattributevireal64(vsg,vi_null, NIRFSG_ATTR_POWER_LEVEL, Level); // Note frequency can also be configured using low level attributes. status = nirfsg_setattributevireal64(vsg,vi_null, NIRFSG_ATTR_FREQUENCY, Frequency); // Enable output 2015 Cobham

25 RFSG Basics status = nirfsg_configureoutputenabled(vsg, VI_TRUE); // Note output state can also be configured using low level attributes. status = nirfsg_setattributevireal64(vsg,vi_null, NIRFSG_ATTR_OUTPUT_ENABLED, VI_TRUE); C#++ Example int status; double Frequency double Level = 1e9; // 1 GHz = 20; // 20 dbm // Configure frequency & level using higher level function status = Rfsg.ConfigureRF(Frequency, Level); // Note Level can also be set using a low level attribute. status = Rfsg.SetPowerLevel("0", Level); // Note Frequency can also be set using a low level attribute. status = Rfsg.SetFrequency("0", Frequency); // Enable output status = Rfsg.ConfigureOutputEnabled(true); // Note output state can also be configured using low level attributes. status = Rfsg.SetOutputEnabled("0", true); 5.3 Configuring the RFSG for CW Tone Generation To generate a CW tone at a known frequency and level the following steps need to be followed. 1. Call Abort to take the RFSG into Generation Mode. 2. Configure the RFSG for a CW Tone. 3. Disable any start triggers that may have previously been configured. 4. Set the Frequency, Level and Output state. 5. Call Initiate. 6. Check generation status C/C++ Example ViReal64 Frequency = 1e9; ViReal64 Level // 1 GHz = 20; // 20 dbm // Aborts generation & put VSG in configuration mode status = nirfsg_abort(vsg); // 2015 Cobham

26 RFSG Basics // Configure all settings that require the VSG to be in configuration mode // // Set generation mode to CW status = nirfsg_configuregenerationmode(vsg, NIRFSG_VAL_CW); // Disable start trigger, so generation will commence immediately after _Initiate() called status = nirfsg_disablestarttrigger(vsg); // Configure frequency & level using higher level function status = nirfsg_configurerf(vsg, Frequency, Level); // Note level can also be configured using low level attributes. status = nirfsg_setattributevireal64(vsg,vi_null, NIRFSG_ATTR_POWER_LEVEL, Level); // Note frequency can also be configured using low level attributes. status = nirfsg_setattributevireal64(vsg,vi_null, NIRFSG_ATTR_FREQUENCY, Frequency); // Enable output status = nirfsg_configureoutputenabled(vsg, VI_TRUE); // Note output state can also be configured using low level attributes. status = nirfsg_setattributevireal64(vsg,vi_null, NIRFSG_ATTR_OUTPUT_ENABLED, VI_TRUE); // Initiate generation (VSG now in generation mode) status = nirfsg_initiate(vsg); // Check Generation Status. ( returns 0 (generation active) ) status = nirfsg_checkgenerationstatus(vsg, &done); C# Example int status; bool done; double Frequency double Level = 1e9; // 1 GHz = 20; // 20 dbm // Aborts generation & put VSG in configuration mode status = Rfsg.Abort(); // // Configure all settings that require the VSG to be in configuration mode 2015 Cobham

27 RFSG Basics // // Set generation mode to CW status = Rfsg.ConfigureGenerationMode(niRFSGConstants.Cw); // Disable start trigger, so generation will commence immediately after _Initiate() called status = Rfsg.DisableStartTrigger(); // Configure frequency & level using higher level function status = Rfsg.ConfigureRF(Frequency, Level); // Enable output status = Rfsg.ConfigureOutputEnabled(true); // Initiate generation (VSG now in generation mode) status = Rfsg.Initiate(); // Check Generation Status. ( returns 0 (generation active) ) status = Rfsg.CheckGenerationStatus(out done); 5.4 Configuring the RFSG for Waveform Generation Note : This document does not describe how to extract IQ data from an COBHAM.aiq file. To generate a waveform at a known frequency and level the following steps need to be followed. 1. Call Abort to take the RFSG into Generation Mode. 2. Configure the power level type to be either RMS or PEAK. Average Power (default) Peak Power Indicates the desired power averaged in time. The driver maximizes the dynamic range by scaling the I/Q waveform so that its peak magnitude is equal to one. If you write more than one waveform, NI-RFSG scales each waveform without preserving the power level ratio between the waveforms. Indicates the maximum power level of the RF signal averaged over one period of the RF carrier frequency (the peak envelope power). This setting requires the magnitude of the I/Q waveform to be less than or equal to one. When using peak power, the power level of the RF signal matches the specified power level at moments when the magnitude of the I/Q waveform equals one. If you write more than one waveform, the relative scaling between waveforms is preserved. In peak power mode, waveforms are scaled according to the NIRFSG_ATTR_ARB_WAVEFORM_SOFTWARE_SCALING_FACTOR attribute Cobham

28 RFSG Basics 3. Load the waveform into the RFSG. 4. Set the sample rate in Hz of the playback of the waveform. 5. Configure the RFSG for a ARB Waveform playback. 6. Configure the play back for single or continuous playback. 7. If the play back is single then define the number of times to play the waveform. 8. Disable any start triggers that may have previously been configured. 9. Set the Frequency, Level and Output state. 10. Call Initiate. 11. Check generation status C/C++ Example ViStatus status; ViBoolean done; ViReal64 Frequency ViReal64 Level ViReal64 aiqsamplerate std::vector<vireal64> I; std::vector<vireal64> Q; = 1e9; // 1 GHz = 20; // 20 dbm = 20e6; // 20 MHz. // Load in am IQ waveform from file that is specified with a IQ pair per line deliminated with a ',' ReadCsvFile("gsmtsc0.csv", I,Q); ViInt32 numsamples = I.size(); // Aborts generation & put VSG in configuration mode status = nirfsg_abort(vsg); // // Configure all settings that require the VSG to be in configuration mode // // RMS mode will automatically rescale ARB files to maximise DAC dynamic range. // PEAK mode will treat the RF level as being the peak value, so the RMS value will usually be lower. ARB files are not re scaled. status = nirfsg_configurepowerleveltype(vsg, NIRFSG_VAL_PEAK_POWER); // Write Arb file to RFSG. status = nirfsg_writearbwaveform(vsg, "gsmtsc0.csv", numsamples, &I[0], &Q[0], VI_FALSE); // Set ARB playback sample rate status = nirfsg_setattributevireal64(vsg, VI_NULL, NIRFSG_ATTR_IQ_RATE, samplerate); // Set generation mode to ARB Waveform. status = nirfsg_configuregenerationmode(vsg, NIRFSG_VAL_ARB_WAVEFORM); 2015 Cobham

29 RFSG Basics // Configure the ARB to playback continuously or a finite number of times. status = nirfsg_setattributeviboolean(vsg, VI_NULL, NIRFSG_ATTR_ARB_WAVEFORM_REPEAT_COUNT_IS_FINITE, VI_TRUE); // Configure number of times ARB file is played status = nirfsg_setattributeviint32(vsg, VI_NULL, NIRFSG_ATTR_ARB_WAVEFORM_REPEAT_COUNT, 1000); // Disable start trigger, so generation will commence immediately after _Initiate() called status = nirfsg_disablestarttrigger(vsg); // Configure frequency & level using higher level function status = nirfsg_configurerf(vsg, frequency, level); // Enable output status = nirfsg_configureoutputenabled(vsg, VI_TRUE); // Enable software start trigger status = nirfsg_configuresoftwarestarttrigger(vsg); // Initiate generation (VSG now in generation mode) status = nirfsg_initiate(vsg); // Check Generation Status. ( returns 0 (generation active) ) status = nirfsg_checkgenerationstatus(vsg, &done); // VSG now in generation mode but awaiting a software trigger to commence ARB playback status = nirfsg_sendsoftwareedgetrigger(vsg, NIRFSG_VAL_START_TRIGGER, ""); // send software trigger C# Example int status; bool done; double Frequency double Level double samplerate double[] I; double[] Q; = 1e9; // 1 GHz = 20; // 20 dbm = 20e6; // 20 MHz // Load in am IQ waveform from file that is specified with a IQ pair per line deliminated with a ',' ReadCsvFile("gsmtsc0.csv", out I, out Q); // Aborts generation & put VSG in configuration mode 2015 Cobham

30 RFSG Basics status = Rfsg.Abort(); // RMS mode will automatically rescale ARB files to maximise DAC dynamic range. // PEAK mode will treat the RF level as being the peak value, so the RMS value will usually be lower. ARB files are not re scaled. status = Rfsg.ConfigurePowerLevelType(niRFSGConstants.PeakPower); // Clear All wavefroms so we don't get an error if the waveform is already loaded. status = Rfsg.ClearAllArbWaveforms(); // Write Arb file to RFSG. status = Rfsg.WriteArbWaveform("gsmtsc0", I.Length, I, Q, false); // Set ARB playback sample rate status = Rfsg.SetIqRate("0", samplerate); // Set generation mode to ARB Waveform. status = Rfsg.ConfigureGenerationMode(niRFSGConstants.ArbWaveform); // Configure the ARB to playback continuously or a finite numberof times. False for continuous playback true to play back n times. status = Rfsg.SetArbWaveformRepeatCountIsFinite("0", false); // Configure number of times ARB file is played status = Rfsg.SetArbWaveformRepeatCount("0", 1000); // Disable start trigger, so generation will commence immediately after _Initiate() called status = Rfsg.DisableStartTrigger(); // Configure frequency & level using higher level function status = Rfsg.ConfigureRF(Frequency, Level); // Enable output status = Rfsg.ConfigureOutputEnabled(true); // Initiate generation (VSG now in generation mode) status = Rfsg.Initiate(); // Check Generation Status. ( returns 0 (generation active) ) status = Rfsg.CheckGenerationStatus(out done); 2015 Cobham

31 RFSG Basics 5.5 Waveform Playback Triggers Waveform playback can be configured so that it starts after the Initiate method has been called by disabling any configured triggers, or upon receipt of a software trigger event, or from an external signal Software Trigger Before the Inititiate() method is called a C/C++ call to nirfsg_configuresoftwarestarttrigger () or a C# call to ConfigureSoftwareStartTrigger() places the RFSG into a state where it will not commence playback until the C/C++ method nirfsg_sendsoftwareedgetrigge()r or the C# method SendSoftwareEdgeTrigger() is called C / C++ Example // Enable software start trigger status = nirfsg_configuresoftwarestarttrigger(vsg); // Initiate generation (VSG now in generation mode) status = nirfsg_initiate(vsg); // Check Generation Status. ( returns 0 (generation active) ) status = nirfsg_checkgenerationstatus(vsg, &done); // VSG now in generation mode but awaiting a software trigger to commence ARB playback status = nirfsg_sendsoftwareedgetrigger(vsg, NIRFSG_VAL_START_TRIGGER, ""); // send software trigger C# Example // Enable software start trigger. status = Rfsg.ConfigureSoftwareStartTrigger(); // Initiate generation (VSG now in generation mode) status = Rfsg.Initiate(); // Check Generation Status. ( returns 0 (generation active) ) status = Rfsg.CheckGenerationStatus(out done); // VSG now in generation mode but awaiting software trigger to commence ARB playback. status = Rfsg.SendSoftwareEdgeTrigger(niRFSGConstants.StartTrigger, ""); 2015 Cobham

32 RFSG Basics External Trigger Before the Inititiate() method is called a C/C++ call to nirfsg_configuredigitaledgestarttrigger() or a C# call to ConfigureDigitalEdgeStartTrigger() specifying the external source of the trigger event and the positive or negative edge that will cause the trigger will place the RFSG into a state where it will not commence playback until a trigger signal is received on the route specified C / C++ Example // Enable external Edge start trigger ( from PXI trigger 0 ) status = nirfsg_configuredigitaledgestarttrigger(vsg,nirfsg_val_pxi_trig0_str); // Initiate generation (VSG now in generation mode) status = nirfsg_initiate(vsg); // Check Generation Status. ( returns 0 (generation active) ) status = nirfsg_checkgenerationstatus(vsg, &done); // VSG now in generation mode but awaiting Edge trigger event on PXI trig 0 to commence ARB playback C# Example // Enable external Edge start trigger ( from PXI trigger line 0 ) status = Rfsg.ConfigureDigitalEdgeStartTrigger(niRFSGConstants.PxiTrig0Str, nirfsgconstants.risingedge); // Initiate generation (VSG now in generation mode) status = Rfsg.Initiate(); // Check Generation Status. ( returns 0 (generation active) ) status = Rfsg.CheckGenerationStatus(out done); // VSG now in generation mode but awaiting Edge trigger event on PXI trig 0 to commence ARB playback 5.6 Stopping Waveform Playback To abort playback or return the RFSG to the Configuration Mode a C/C++ call to nirfsg_abort() or a C# call to will be required. If the waveform playback was set to finite and playback has completed a call to Abort call is not needed C/C++Example // Abort the current waveform playback. status = nirfsg_abort(vsg); 2015 Cobham

33 5.6.2 C# Example // Aborts generation & put VSG in configuration mode status = Rfsg.Abort(); 2015 Cobham

34 RFSA/RFSG Self Calibration 6 RFSA/RFSG Self Calibration The NI 5644r/5645r/5646r is calibrated at the factory; however, a self-calibration should be performed in the following situations: After first installing your NI 5644R into your chassis After any module in the chassis is added, moved, or removed When the system is in an environment where the ambient temperature varies If the module temperature has drifted more than ±5 C from the last performed selfcalibration In addition to the preceding scenarios, performing proactive and regular self-calibration helps control the effects of aging-related drifts. ViReal64 minfrequency = 500e6; // 500 MHz ViReal64 maxfrequency = 2e9; // 2 GHz ViReal64 minreferencelevel = 30; // 30 dbm ViReal64 maxreferencelevel = 30; // +30 dbm ViReal64 minpowerlevel = 100; // 100 dbm ViReal64 maxpowerlevel = 17; // +17 dbm // Perform self calibration with no calibration step omissions between 500 MHz and 2GHz and between 30 dbm to +30 dbm. status = nirfsa_selfcalibraterange(vsa,0,minfrequency,maxfrequency,minreferencelevel,maxref erencelevel); // Perform self calibration with no calibration step omissions between 500 MHz and 2GHz and between 80 dbm to +17 dbm. status = nirfsg_selfcalibraterange(vsg,0,minfrequency,maxfrequency,minpowerlevel,maxpowerle vel); ErrorCheckRFSG(vsg,status); 2015 Cobham

35 RFSA/RFSG Self Calibration 2015 Cobham

36 Example Code 7 Example Code To accompany this Application note three examples have been written: Example 1 Example of how to boot and close down the VST. Available in C/C++ and C#.NET Example 2 Example of how setup the VST for a single point IQ capture and measure the average power of the capture. Available in C/C++ and C#.NET Example 3 Example of how to generate a CW tone at a certain power and frequency and how to load and playback an IQ waveform at a known power and level Cobham

37 Appendix A 8 Appendix A RFSA state diagram Cobham

38 VST Basics Programming Guide The most important thing we build is trust For further information please contact: Cobham Wireless As we are always seeking to improve our products, the information in this document gives only a general indication of the product capacity, performance and suitability, none of which shall form part of any contract. We reserve the right to make design changes without notice. All trademarks are acknowledged. Cobham 2015.