xx
RSA7100 Series Real-Time Spectrum Analyzer
Application Programming Interface (API)
ZZZ
Programmer Manual
REV A
www.tek.com
$
077-1496-01
Copyright © Tektronix. All rights reserved. Licensed software products are owned by Tektronix or its subsidiaries or suppliers, and are
protected by na
tional copyright laws and international treaty provisions.
Tektronix pro
previously published material. Specifications and price change privileges reserved.
TEKTRONIX and TEK are registered trademarks of Tektronix, Inc.
ducts are covered by U.S. and foreign patents, issued and pending. Information in this publication supersedes that in all
Contacting Tektronix
Tektronix, Inc.
14150 SW Karl Braun Drive
P.O. Box 500
Beaverton, OR 97077
USA
For product information, sales, service, and technical support:
In North America, call 1-800-833-9200.
Worldwide, visit www.tek.com to find contacts in your area.
Table of Contents
Preface................................................................................................................................. ii
Function cal
Index
ls .......................................................................................................................... 1
Table of Content
s
Version March 20, 2020
RSA7100 Series API Programmer Manual i
Preface
Preface
In the typical API scenario, the custom user program calls functions from the API to fetch data. This is known as a “pull” model.
The user’s program must “pull” the data from the instrument. The RSA7100 Series IQFlow™ streaming API uses both “pull”
and “push” models. The “push” model pushes the data to the user’s code by calling user supplied callback functions. These
callback functions have immediate access to the latest acquired data and can then use it how ever the user has programmed.
Version March 20, 2020
ii RSA7100 Series API Programmer Manual
Function calls
dataCallbackFxn Type definition for the user’s data callback function. Called automatically by
Declaration:
Parameters:
data
size
startofBlockSample size_t sample number of the first sample in the IQ data block.
streamOverload bool. True indicates an IQ data block was missed. False indicates no skipped
sampleRate
centerFreq
triggerCallbackFxn Type definition for the user’s trigger callback function. Called automatically by
Declaration:
Parameters:
ersample
Trigg
Function calls
the API when new data is available.
dataCallbackFxn(IQDataPtr data, size_t size, size_t startOfBlockSample, bool
streamOverl
IQDataPtr structure. Provides the IQ pair data block.
size_t of the IQ pair data block.
IQ data bl
double o
double o
the API when the RSA is triggered.
triggerCallbackFxn(size_t triggerSample);
size_t of the sample number for the current trigger event.
oad, double sampleRate, double centerFreq);
ock.
f the sample rate for the current acquisition.
f the center frequency for the current acquisition.
triggerDataCallbackFxn Type definition for the user’s data with triggers callback function. Called
atically by the API when new data is available.
autom
Declaration:
Parameters:
a
dat
ze
si
startofBlockSample size_t sample number of the first sample in the IQ data block.
streamOverload bool. True indicates an IQ data block was missed. False indicates no skipped
triggerData
numTriggers
sampleRate
double scalingFactor
gerDataCallbackFxn(IQDataPtr data, size_t size, size_t startOfBlockSample,
trig
bool streamOverload, size_t* triggerData, size_t numTriggers, double
sampleRate, double scalingFactor);
IQDataPtr structure. Provides the IQ pair data block.
size_t of the IQ pair data block.
IQ data block.
Provides sample numbers for triggers in the current data block if triggers are
found.
Returns the number of triggers in the current data block.
double of the sample rate for the current acquisition.
Returns the scaling factor for the IQ data. Multiply the signed 16-bit integer
values by this to scale the data factor.
Version March 20, 2020
RSA7100 Series API Programmer Manual 1
Function calls
USERDATA_Conn
ect()
Connects the us
er’s callback functions to the IQFlow™ streaming API, but does
not include the triggerDataCallbackFxn callback.
Declaration:
ReturnStatus USERDATA_Connect(size_t &dataSize, dataCallbackFxn
dCbFxn, triggerCallbackFxn tCbFxn);
Parameters:
dataSize size_t passed by reference. Sets the buffer size of the IQ pair data block. This
value is bound between 2
15
to 228.
dCbFxn dataCallbackFxn. Sets the user supplied callback function to be called by the
API each tim
e a new data block is available. Can be set to null if real-time
IQ data is not required.
tCbFxn triggerCallbackFxn. Sets the user supplied callback function to be called by the
API each time a trigger event occurs. Can be set to null if trigger timestamp is
not requi
red.
Return values:
noError
The function completed successfully.
errorBufferTooSmall The buffer size specified is too small.
errorBufferTooLarge The buffer size specified is too large.
USERDATA_ConnectEx() Connects the user’s callback functions to the IQFlow™ streaming API and
includes the triggerDataCallbackFxn callback.
Declaration:
ReturnStatus USERDATA_ConnectEx(size_t &dataSize, dataCallbackFxn
dCbFxn, triggerCallbackFxn tCbFxn, triggerDataCallbackFxn tdCbFxn);
Parameters:
dataSize size_t passed by reference. Sets the buffer size of the IQ pair data block. This
value is bound between 2
15
to 228.
dCbFxn dataCallbackFxn. Sets the user supplied callback function to be called by the
API each time a new data block is available. Can be set to null if real-time
IQ data is not required.
tCbFxn triggerCallbackFxn. Sets the user supplied callback function to be called by the
API each time a trigger event occurs. Can be set to null if trigger timestamp is
not required.
tdCbFxn triggerDataCallbackFxn. Sets the user supplied callback function to be called
by the API each time a new data block is available. Can be set to null if real
time IQ data w ith trigger information is not required.
Return values:
noError
The function completed successfully.
errorBufferTooSmall The buffer size specified is too small.
errorBufferTooLarge The buffer size specified is too large.
USERDATA_Disconnect() Disconnects the user’s callback functions from the SignalVu-PC streaming API.
Declaration:
USERDATA_Disconnect();
Return values:
noError
The function completed successfully.
Version March 20, 2020
2 RSA7100 Series API Programmer Manual
Function calls
USERDATA_GetT
Declaration:
Parameters:
data
size
startofBlockSample size_t sample number of the first sample in IQ data block.
streamOverload bool. True indicates an IQ data block was missed. False indicates no skipped
TrigData
auxData
ure of TriggerDataQueue:
Struct
ataQueue
TrigD
ture of trigData:
Struc
gerSamples
trig
gerTimeSeconds
trig
ggerTimeNonaseconds
tri
Return values:
Error
no
errorInvalidSize The function parameter size is 0.
rrorInvalidDataRate
e
errorTimedOut The function timed out.
errorNotConnected The function had no valid connection to SignalVu-PC.
rigData ()
Queue
Fetches the lat
traditional pull method.
ReturnStatus USERDATA_GetTrigData(IQDataPtr data, size_t size,
size_t &startofBlockSample, bool &streamOverload, *triggerStructQueue
TrigDataQueu
IQDataPtr structure. Provides the IQ pair data block.
size_t of the number of samples in the IQ pair data block.
IQ data blo
triggerS
and trigger time in nanoseconds.
auxData contains a scaling factor. IQ data is structured as an array of 16-bit
signed integer pairs and needs to be scaled by multiplying it with this scaling
factor.
ataQueue is a structure that contains a queue to hold the trigData structure.
TrigD
_t. sample number of trigger.
size
64_t. time associated with trigger in seconds, if a time reference value
uint
is found.
uint64_t time associated with trigger in nanoseconds, if a time reference value
is found.
The function completed successfully.
The function parameter sampleRate is 0 or negative.
est IQ data block with relevant trigger information using a
e, &auxData AuxData);
ck.
tructQueue holds parameters for trigger sample, trigger time in seconds,
Version March 20, 2020
RSA7100 Series API Programmer Manual 3
Function calls
USERDATA_GetT
Declaration:
Parameters:
sample
Return values:
Structure of PosixTime:
Seconds Posix time of associated sample.
Nanosecon
Additional information
Should be used after any of the following functions: triggerDataCallbackFxn, USERDATA_GetAuxData, and
USERDAT
PosixTi
imeFromSample()
ds
A_GetTrigData. This will ensure that the most recent time value is used.
me structure will return 0 if there is no valid time reference (PPS, GPS, IRIG-B).
Returns a time s
PosixTime USE
Sample number to obtain the associated Posix time.
The number of nanoseconds that have elapsed since the Posix time of the
associated sample.
tructure for the given sample.
RDATA_GetTimeFromSample(size_t sample);
Version March 20, 2020
4 RSA7100 Series API Programmer Manual
Function calls
USERDATA_GetA
Declaration:
Parameters:
AuxData structure defined as follows:
Float version
bool skippedFrame:
bool adcO
bool refF
bool ifP
bool ifP
bool dm
bool gpsStatus; True indicates GPS is on. False indicates GPS is off.
doubl
doub
doub
bool validTimeRef;
TimingReference timeRef; Returns the time source selected. (IRIG-B AM,
uint64_t timeRefSample; Returns the IQ sample number associated with the
int64_t timeRefSeconds;
u
uint64_t timeRefNanoseconds; Returns time of associated time reference sample in
uint64_t startOfBlockSample; Returns the sample of the first IQ pair in data block.
double sampleRate;
double cf; Returns the center frequency of the current
double scalingFactor;
Return Values:
noError:
errorInvalidSharedMemory:
errorTimedOut: The function timed out.
errorNotConnected: The function had no valid c onnection to SignalVu-PC.
Additional Detail:
uxData()
verrange:
reqUnlock:
owerOverloadStartAcq;
owerOverloadRuntime;
aOverflow;
e gpsLat;
le gpsLong;
le gpsAlt;
Fetches a data s
tructure containing metadata for the acquired data.
IQ data is structured as an array of 16-bit signed integer pairs and needs to be
scaled by multiplying it with a scaling factor. The AuxData structure returned by the
USERDATA_Get
ReturnStatus
AuxData() function contains this scaling factor.
USERDATA_GetAuxData(AuxData &auxData);
Version of structure.
True indicates a skipped frame. False indicates no
skipped fr
ame.
True indicates adc over range occurred. False
s no adc overrange.
indicate
True indi
cates that the external reference is unlocked.
IF power overload occurred during instrument
ization.
initial
IF power overload occurred during run time.
dicates dma overflow occurred. False
True in
indicates no dma overflow.
Returns GPS latitude if GPS status is true.
Returns G PS longitude if GPS status is true.
Returns GPS altitude if GPS status is true.
e source used is valid.
Tim
IRIG-B DC, GPS, 1PPS, or PC).
ime, if time source is valid.
t
eturns posix second of associated time reference
R
sample if time source is valid.
nanoseconds past the associated second value, if
time source is valid.
Returns the sample rate of the current acquisition.
acquisition.
Returns the scaling factor for the IQ data. Multiply
the signed 16-bit integer values by this to scale the
data factor.
The function completed successfully.
No data found in auxiliary data.
GFRM_OFF (0) is returned when GNSS source is not selected.
Version March 20, 2020
RSA7100 Series API Programmer Manual 5
Function calls
USERDATA_GetD
Declaration:
Parameters:
data
size
startofBlockSample size_t sample number of the first sample in IQ data block.
streamOverload bool. True indicates an IQ data block was missed. False indicates no skipped
sampleRate
centerFreq
Return values:
noError
errorInvalidSize The function parameter size is 0.
errorI
errorTimedOut The function timed out.
errorNotConnected The function had no valid connection to SignalVu-PC.
USERDATA_FindData () Searches for the sample number passed to it in the API’s local circular buffer
Declaration:
Parameters:
da
si
findSample
startofBlockSample size_t sample number of the first sample in the IQ data block.
streamOverload bool. True indicates an IQ data block was missed. False indicates no skipped
sampleRate
centerFreq
Return values:
noError
errorInvalidSize The function parameter size is 0.
errorInvalidDataRate
errorStaleTrigger The function failed to acquire the trigger since the data has already passed.
errorTimedOut The function timed out while looking for a trigger.
errorNotConnected The function had no valid connection to SignalVu-PC.
ata ()
nvalidDataRate
ta
ze
Fetches the lat
ReturnStatus
&startofBlockSample, bool &streamOverload, double &sampleRate, double
¢erFreq);
IQDataPtr structure. Provides the IQ pair data block.
size_t of the number of samples in the IQ pair data block.
IQ data block.
double of the sample rate for the current acquisition.
double of the center frequency for the current acquisition.
The function completed successfully.
The function parameter sampleRate is 0 or negative.
eturns a data set containing the requested sample, if it can be found.
and r
urnStatus USERDATA_FindData(IQDataPtr data, size_t size, size_t
Ret
findSample, size_t &startofBlockSample, bool &sreamOverlaod, double
&sampleRate, double ¢erFreq);
IQDataPtr structure. Provides the IQ pair data block.
size_t of the number of samples in the IQ pair data block.
inds the data associated with the provided sample.
F
IQ data block.
double of the sample rate for the current acquisition.
double of the center frequency for the current acquisition.
The function completed successfully.
The function parameter sampleRate is 0 or negative.
est IQ data using a traditional pull method.
USERDATA_GetData(IQDataPtr data, size_t size, size_t
Version March 20, 2020
6 RSA7100 Series API Programmer Manual
Index
Index
C
Connect, 2
Connect (includes
triggerData
callback), 2
CallbackFxn
D
Data structure
fetch, 5
Data type definition, 1
Disconnect, 2
F
Fetch data,
Fetch data structure, 5
Fetch time, 4
Fetch trigg
Find data, 6
6
er data, 3
T
Time
fetch, 4
Trigger data
fetch, 3
Trigger Data type, 1
Trigger type definition, 1
Version March 20, 2020
RSA7100 Series API Programmer Manual 7
Loading...