Tektronix RSA306, RSA306B,,RSA500A/600A Programmer

RSA306, RSA306B, and RSA500A/600A Series Spectrum Analyzers Application Programming Interface (API)

ZZZ

Programming Reference

REV A

www.tek.com

077-1031-04

tional copyright laws and international treaty provisions.

Tektronix pro previously published material. Speciﬁcations 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 ﬁnd contacts in your area.

Table of Contents

Preface ................................................................................................................................. ii

API function

Alignment functions.................................................................................................................... 2

Audio functions ........................................................................................................................ 3

Conﬁgure fu

Device functions...................................................................................................................... 21

DPX functions......................................................................................................................... 28

GNSS funct

IF streaming functions................................................................................................................ 45

IQ block functions..................................................................................................................... 55

IQ streami

Playback functions (R3F ﬁle format)................................................................................................. 84

Power functions....................................................................................................................... 86

Spectrum

Time functions ........................................................................................................................ 94

Tracking generator functions . . . .. . . .. . . .. . . .. . . .. . . .. . . ... . ... . .. . . ... . ... . ... . ... . ... . ... . ... . ... . . .. . . .. . . .. . . .. . . .. . . .. . . ... . ..... 98

Trigger

Example Python program .......................................................................................................... 104

Stream

RSA API version compatibility ......................................................................................................111

Index

groups. ... ... .... . . ... . ... . . .. . . ... . ... . . .. . . ... . ... . . .. . . ... . ... . . ... . ... . . .. . . ... . ... . . .. . . ... . ... . . .. . . ... . ... . . ... . ... 1

nctions.................................................................................................................... 7

ions....................................................................................................................... 40

ng functions ............................................................................................................... 63

functions ................................................................................................................... 87

functions .................................................................................................................... 100

Programming ﬁle attachment ................................................................................................. 105

ing IF Sample Data File Format............................................................................................ 106

Table of Content

API Reference i

Preface

This document describes the RSA API function calls to interface with the RSA306, RSA306B, RSA500A Series, and RSA600A Series Spectrum Analyzers through Microsoft Windows.

The RSA API driver software allows user-developed programs to directly control Tektronix RSA USB devices. The API software is designed to be used with PCs running the Microsoft Windows operating system. To use the API software, it must be installed on the PC to which the RSA device is connected. The API software installer can be accessed as follows:

To access driver from the USB memory device that shipped with your instrument: Open the USB drive, navigate to the API installer, and install the driver.

To access driver from www.Tek.com: Search for “RSA API” and ﬁlter the results on “Software”. Download and install the latest driver.

Programing languages supported by this driver include: C, C++, and Python. An example program written in Python is provided. (See page 105, Programming ﬁle attachment.)

The main API interface DLL ﬁle is RSA_API.dll. It is a C-language Win32 DLL ﬁle created in Microsoft Visual Studio. The API uses standard Windows C-runtime libraries which must also be installed on the PC. A linker library ﬁle (RSA_API.lib) is provided to support static linking of the API to user C/C++ programs.

This document supports API version 2. A compatibility chart from API version 1 to version 2 is provided. (See page 111, RSA API version compatibility.)

ii API Reference

API function gro

ups

API function g

This section contains the available function calls. The functions are grouped into the following categories:

Alignment (See page 2.)

Audio (See page 3.)

Conﬁgure (See page 7.)

Device (See page 21.)

DPX (See page 28.)

GNSS (See page 40.)

IF streaming (See page 45.)

IQ block (See page 55.)

IQ streaming (See page 63.)

Playback (See page 84.)

Power (See page 86.)

Spectrum (See page 87.)

Time (See page 94.)

roups

Tracking generator (See page 98.)

Trigger (See page 100.)

API Reference 1

Alignment funct

ions

Alignment fun

ALIGN_GetAli

Declaration:

Parameters:

Return Values:

Addition

ALIGN_Ge

Declaration:

Parameters:

Return Values:

Additional Detail:

gnmentNeeded

needed: Pointer to a bool. True indicates an alignment is needed. False indicates an

noError:

errorNotConnected:

al Detail:

tWarmupStatus

warmedUp: Pointer to a bool.

noError:

ctions

Determines if ReturnStatu

alignment is not needed.

The function has completed successfully. The device It is based on the difference between the current temperature and the

temperature from the last alignment.

Reports device warm-up status. ReturnS

True indicates the device's warm-up interval has been reached. False indicates the war

The function has completed successfully. Devices start in the "warm-up" state after initial power up until the internal

erature stabilizes. The warm-up interval is different for different devices.

temp

an alignment is needed or not.

s ALIGN_GetAlignmentNeeded(bool* needed);

is not connected.

tatus ALIGN_GetWarmupStatus(bool* warmedUp);

m-up interval has not been reached.

ALIGN_RunAlignment

aration:

Decl

urn Values:

Ret

noError: The alignment has succeeded.

errorDataNotReady:

the device alignment process.

Runs ReturnStatus ALIGN_RunAlignment();

The alignment operation failed.

2 API Reference

Audio functions

Audio functio

AUDIO_SetFre

Declaration:

Parameters:

Return Values:

Additional Detail:

AUDIO_GetFrequencyOffset Queries the audio carrier frequency offset from the Center Frequency.

Declar

Parame

Retur

quencyOffset

freqOffsetHz: Amount of frequency offset from the Center Frequency.

noError:

errorParameter:

ation:

ters:

ffsetHz:

freqO

n Values:

noError:

Sets the audio ReturnStatu

Range: –20e

The function completed successfully. Input parameter out of range. This function allows the audio demodulation carrier frequency to be offset from

the devic without changing the Center Frequency. The audio demodulation is performed at a carrier frequency of (Center Frequency + freqOffsetHz). The freqOffsetHz is set to

ReturnStatus AUDIO_GetFrequencyOffset(double* freqOffsetHz);

er to a double variable. Returns the current audio frequency offset from

Point the Center Frequency in Hz.

unction completed successfully.

The f

demodulation carrier frequency offset from the Center Frequency.

s AUDIO_SetFrequencyOffset(double freqOffsetHz);

6 ≤ freqOffsetHz ≤ 20e6

e’s Center Frequency. This allows tuning different carrier frequencies

an initial value of 0 Hz at the time the device is connected.

AUDIO_GetEnable Queries the audio demodulation run state.

aration:

Decl

ameters:

Par

qOffsetHz:

fre

Return Values:

noError:

ReturnStatus AUDIO_GetEnable(bool *enable);

Pointer to bool variable. True indicates the audio demodulation is running.

se indicates it is stopped.

Fal

The query was successful.

API Reference 3

Audio functions

AUDIO_GetData Returns audio s

Declaration:

Parameters:

data:

inSize: The maximum

outSize: The amount of audio data samples stored in the data array.

Return Val

Additional Detail

AUDIO_GetMode Queries the audio demodulation mode.

Declaration:

Parameters:

Return Values:

Add

ues:

noError:

_mode:

rror:

noE

itional Detail:

ReturnStatus

Pointer to a 16 bit integer array. Contains an array of audio data when the function com

will not exceed this value.

The data pa The outSi

The inSize value speciﬁes the maximum amount of audio samples allowed.

ReturnStatus AUDIO_GetMode(AudioDemodMode* _mode);

Pointer to AudioDemodMode mode. Contains the audio demodulation m ode when the function completes.

AudioDemodMode Value

ADM_F ADM_FM_13KHZ ADM_FM_75KHZ ADM_ ADM_AM_8KHZ ADM_MODE_NONE

The audio demodulation mode has been successfully queried.

mode type is stored in the _mode parameter.

The

ample data in a user buffer.

AUDIO_GetData(int16_t* data, uint16_t inSize, uint16_t* outSize);

pletes.

amount of audio data samples allowed. The outSize parameter

rameter is ﬁlled with audio data.

ze variable speciﬁes the amount of audio samples stored in the array.

M_8KHZ

FM_200KHZ

0 1 2 3 4 5

AUDIO_GetMute Queries the status of the mute operation.

claration:

rameters:

mute:

Return Values:

noError:

Additional Detail:

4 API Reference

ReturnStatus AUDIO_GetMute(bool* _mute);

ointer to a bool. Contains the mute status of the output speakers when the

P function completes.

True indicates the speaker output is muted. False indicates the speaker output

s not muted.

The mute status has been successfully queried. The status of the mute operation does not stop the audio processing or data

callbacks.

Audio functions

AUDIO_GetVolu

Declaration:

Parameters:

Return Values:

Additional

AUDIO_SetMode Sets the audio demodulation mode.

Declaration:

Parameters:

Return

_volume:

noError:

Detail:

mode: AudioDem

Values:

noError:

Queries the vol ReturnStatus

Pointer to a ﬂoat. Contains a real number ranging from 0 to 1.

The volume has been successfully queried. If the value is outside of the speciﬁed range, clipping occurs.

ReturnStatus AUDIO_SetMode(AudioDemodMode mode);

ADM_FM_8KHZ ADM_FM_ ADM_FM_75KHZ ADM_FM_200KHZ ADM_AM_ ADM_MODE_NONE

The aud

ume and must be a real value ranging from 0 to 1.

AUDIO_GetVolume(ﬂoat* _volume);

odMode

13KHZ

8KHZ

io demodulation mode has been successfully set.

Value

0 1 2 3 4 5

AUDIO_SetMute Sets the mute status.

ration:

Decla

Param

mute

Return Values:

noError:

Additional Detail:

IO_SetVolume

AUD

Declaration:

Parameters:

volume: Volume value.

Return Values:

oError:

Additional Detail:

eters:

ReturnStatus AUDIO_SetMute(bool mute);

Mute status. True mutes the output speakers. False restores the output speaker

soun

The mute status has been successfully set. It does not affect the data processing or callbacks.

s the volume value and must be a real number ranging from 0 to 1.

Set

turnStatus AUDIO_SetVolume(ﬂoat volume);

Range: 0.0 to 1.0.

The volume has successfully been set. If the value is outside of the speciﬁed range, clipping occurs.

API Reference 5

Audio functions

AUDIO_Start Starts the audi

Declaration:

ReturnStatus

o demodulation output generation.

AUDIO_Start();

Return Values:

noError: The audio demodulation output generation has started.

AUDIO_Stop Stops the audio demodulation output generation.

Declaration:

ReturnStatus AUDIO_Stop()

Return Values:

noError: The audio de

modulation output generation has stopped.

6 API Reference

Conﬁgure functi

ons

Conﬁgure func

CONFIG_GetCe

Declaration:

Parameters:

Return Values:

Addition

CONFIG_GetExternalRefEnable Queries the state of the external reference.

Declaration:

Parameters:

Retur

nterFreq

cf: Pointer to a double. Contains the center frequency when the function completes.

noError:

errorNotConnected:

al Detail:

exRefEn: Pointer to a bool. Contains the status of the external reference when the

n Values:

noError:

tions

Queries the ce ReturnStatu

The center frequency has been queried. The device The center frequency determines the center location for the spectrum view.

ReturnStatus CONFIG_GetExternalRefEnable(bool* exRefEn);

function completes. True in

reference is disabled.

nction has completed successfully.

The fu

nter frequency.

s CONFIG_GetCenterFreq(double* cf);

is not connected.

dicates the external reference is enabled. False indicates the external

CONFIG_GetExternalRefFrequency Queries the frequency of the external reference.

aration:

Decl

meters:

Para

extFreq:

urn Values:

Ret

noError:

rrorExternalReferen-

e ceNotEnabled:

dditional Detail:

ONFIG_GetFrequencyReference-

C Source

Declaration:

ReturnStatus CONFIG_GetExternalRefFrequency(double* extFreq);

nter to a double. On return, c ontains the frequency in Hz of the attached

Poi external reference input.

e function has completed successfully.

he external reference input is not in use.

The external reference input must be enabled for this function to return useful results.

ueries the Frequency Reference source.

ReturnStatus CONFIG_GetFrequencyReferenceSource(FREQREF_SOURCE* src);

API Reference 7

Conﬁgure functi

ons

Parameters:

src:

Return Values:

noError:

errorNotConnected:

Additional Detail:

Pointer to variable to return current Frequency Reference source selection. See CONFIG_SetFr

The function has completed successfully. The device is not connected. This function can (and should) be used in place of

CONFIG_Ge CONFIG_GetExternalRefEnable() only indicates if the EXTREF is chosen or not while this function indicates a ll available sources.

equencyReferenceSource for the list of result values.

tExternalRefEnable() to query the Frequency Reference source.

CONFIG_Ge

CONFI

tMaxCenterFreq

Declaration:

Parameters:

maxCF: Pointer to a double. Contains the maximum center frequency when the function

Return Values:

noError:

errorNotConnected:

Additional Detail:

G_GetMinCenterFreq

Declaration:

Parameters:

minCF: Pointer to a double. Contains the m in imum center frequency when the function

Return Values:

noError:

errorNotConnected:

Additional Detail:

Queries th ReturnSt

complet

The maximum center frequency value has been queried. The device is not connected. The value is stored in the maxCF parameter.

Queri Retu

com

The minimum center frequency value has been queried. The device is not connected. The value is stored in the minCF parameter.

e maximum center frequency.

atus CONFIG_GetMaxCenterFreq(double* maxCF);

es.

es the minimum center frequency.

rnStatus CONFIG_GetMinCenterFreq(double* minCF);

pletes.

8 API Reference

Conﬁgure functi

ons

CONFIG_GetMod rection

Declaration:

Parameters:

mode:

Return V

noError:

errorN

Additional Detail:

CONFIG_GetReferenceLevel Queries the reference level.

Decla

meters:

Para

refL

urn Values:

Ret

noError:

Additional Detail:

eGnssFreqRefCor-

alues:

otConnected:

ration:

evel:

rorNotConnected:

This command is Queries the operating mode of the GNSS Frequency Reference correction. ReturnStatus CONFIG_GetModeGnssFreqRefCorrection(GFR_MODE* mode);

Pointer to va Valid results are:

GFR_MODE

GFRM_OFF GFRM_FREQTRACK GFRM_PHASETRACK GFRM_HOLD

The func The device is not connected. GFRM_

ReturnStatus CONFIG_GetReferenceLevel(double* refLevel);

Poin Range: –130 dBm to 30 dBm.

The The device is not connected. Th

tion completed suc cess fully.

OFF (0) is returned when GNSS source is not selected.

ter to a double. Contains the reference level when the function completes.

function has completed successfully.

e value is stored in the refLevel parameter.

for RSA500A Series and RSA600A Series instruments only.

riable to return GNSS Frequency Reference operating mode.

Value

0 2 3 4

CONFIG_Preset This function sets the trigger mode to Free Run, the center frequency to 1.5

GHz, the span to 40 MHz, the IQ record length to 1024 samples and the

eference level to 0 dBm.

Declaration:

Return Values:

noError: The preset values have been set.

errorNotConnected:

eturnStatus CONFIG_Preset();

The device is not connected.

API Reference 9

Conﬁgure functi

ons

CONFIG_SetCen

Declaration:

Parameters:

Return Values:

Additional Detail: When using the tracking generator, the tracking generator output

CONFIG_De tingString

Declarat

Parameters:

turn Values:

Additional Detail:

terFreq

cf: Value to set Center Frequency, in Hz. The value must be within the range

noError:

errorNotConnected:

codeFreqRefUserSet-

ion:

i_usstr o_fui: Pointer to a FREQREF_USER_INFO structure to return the User setting values

noError:

rrorNotConnected:

Sets the center ReturnStatus

MinCF to M axC

The center frequency has been queried. The device is not connected.

(TRKGEN_SetOutputLevel) should be set prior to setting the center frequency.

This comma Decodes a formatted User setting string into component elements. CONFIG_DecodeFreqRefUserSettingString (const char* i_usstr,

FREQREF_USER_INFO* o_fui);

Pointer to a char array containing a formatted User setting string.

decoded from the input string. The structure deﬁnition is as follows:

Structure element

bool isvalid

unsigned int dacValue char datetime[DEV-

INFO_MAX_STRLEN]

uble temperature

he function completed successfully.

T The device is not connected. This function can be used to decode a user setting string into the component

items in the string.

frequency value.

CONFIG_SetCenterFreq(double cf);

nd is for RSA500A Series and RSA600A Series instruments only.

Description

True if the User setting string has

d data in it, false if not. If false,

vali the remaining elements below are invalid.

Control DAC value. Char string of date+time the User

ting value was created. Format

set “YYYY-MM-DDThh:mm:ss”.

vice temperature when the User

De setting data was created.

10 API Reference

Conﬁgure functi

ons

CONFIG_GetEna fAlign

Declaration:

Parameters:

Return Values:

Additiona

CONFIG_SetEnableGnssTimeRefAlign

Declaration:

Parameters:

Return Values:

Additional Detail:

bleGnssTimeRe-

enable:

noError:

errorNotConnected:

l Detail:

enable:

noError:

errorNotConnected:

This command is Queries the control setting of API Time Reference alignment from the internal

GNSS receiver. ReturnStatus CONFIG_GetEnableGnssTimeRefAlign (bool* enable);

True means the time reference setting is enabled. False means the time reference setting is disabled.

The function completed successfully. The device The GNSS receiver must be enabled to use this function.

This command is for RSA500A Series and RSA600A Se ries instruments only. Controls the API Time Reference alignment from the internal GNSS receiver. ReturnStatus CONFIG_SetEnableGnssTimeRefAlign (bool enable);

True enables setting time reference. False disables setting time reference.

The setting time reference has been enabled or disabled. The device is not connected. The GNSS receiver must be enabled to use this function. The default control setting of “true” enables the API time reference system to be

aligned precisely to UTC time from the GNSS navigation message and 1PPS signal. The GNSS receiver must achieve navigation lock for the time reference alignment to occur. While GNSS is locked, the time reference is updated every 10 seconds to keep close synchronization with GNSS time. Setting the control to “false” disables the time reference updating from GNSS, but retains the current time reference setting. This control allows the user application to independently set the time reference, or simply prevent time updates from the GNSS.

for RSA500A Series and RSA600A Series instruments only.

is not connected.

CONFIG_SetExternalRefEnable Enables or disables the external reference.

Declaration:

Parameters:

exRefEn: Enables or disables the external reference.

Return Values:

noError:

errorNotConnected:

errorTimeout:

Additional Detail:

API Reference 11

ReturnStatus CONFIG_SetExternalRefEnable(bool exRefEn);

True enables the external reference. False disables the external reference.

The external reference has been enabled or disabled. The device is not connected. The operation has not ﬁnished after 2 seconds. When the external reference is enabled, an external reference signal must be

connected to the “Ref In” port. The signal must have a frequency of 10 MHz with a +10 dBm maximum amplitude. This signal is used by the local oscillators to mix with the input signal.

When the external reference is disabled, an internal reference source is used.

Conﬁgure functi

ons

CONFIG_SetFre Source

Declaration:

Parameters:

src:

Return V

Additional Detail:

alues:

noError:

NotConnected:

error

LOLockFailure:

error errorParameter: Invalid input parameter.

quencyReference-

Selects the dev

ReturnStatus CONFIG_SetFrequencyReferenceSource(FREQREF_SOURCE src);

Frequency Reference source selection. Valid settings are:

FREQREF_SOURCE

FRS_INTERNAL FRS_EXTREF FRS_GNSS FRS_USER

NOTE. RSA306B and RSA306 support only INTERNAL and EXTREF sources.

The fun The device is not connected.

d to lock to External Reference input.

Faile

This function can (and should) be used in place of CONFIG_Se-

ernalRefEnable() to control the Frequency Reference source.

tExt CONFIG_SetExternalRefEnable() only allows selecting the INTERNAL or EXTREF sources, while this function allows choice of all available sources.

INTERNAL source is always a valid selection, and is never switched out

The of automatically.

The EXTREF source uses the signal input to the Ref In connector as frequency

erence for the internal oscillators. If EXTREF is selected without a valid

ref signal connected to Ref In, the source automatically switches to USER if available, or to INTERNAL otherwise. If lock fails, an error status indicating

e failure is returned.

th The GNSS source uses the internal GNSS receiver to discipline (adjust) the

internal reference oscillator. If GNSS source is selected, the GNSS receiver

ust be enabled. If the GNSS receiver is not enabled, the source selection

m remains GNSS, but no frequency correction is done. G NS S disciplining only occurs when the GNSS receiver has navigation lock. When the receiver is

nlocked, the adjustment setting is retained unchanged until receiver lock is

u achieved or the source is switched to another selection.

If USER source is selected, the previously set USER setting is used. If the USER setting has not been set, the source switches automatically to INTERNAL.

ice Frequency Reference source.

Value

0 1 2 3

ction completed successfully.

12 API Reference

Conﬁgure functi

ons

CONFIG_GetSta rection

Declaration:

Parameters:

state:

quality:

turn Values:

noError:

rrorNotConnected:

Additional Detail:

tusGnssFreqRefCor-

This command is

for RSA500A Series and RSA600A Series instruments only. Queries the status of the GNSS Frequency Reference correction. ReturnStatus CONFIG_GetStatusGnssFreqRefCorrection(GFR_STATE* state,

GFR_QUALITY* quality);

Pointer to variable to return the GNSS Frequency Reference correction state. Valid settings are:

GFR_STATE

GFRS_OFF GFRS_ACQUIRING GFRS_FREQTRACKING GFRS_PHASETRACKING GFRS_HOLDING

Value

0 1 2 3 4

Pointer to variable to return the GNSS Frequency Reference correction tracking

qualit

UALITY

GFR_Q

INVALID

GFRS_

_LOW

GFRS

_MEDIUM

GFRS

S_HIGH

GFR

TE. INVALID quality is returned if state is not FREQTRACKING or

Value

0 1 2 3

PHASETRACKING.

he function completed successfully.

T The device is not connected. The GNSS receiver must be enabled and selected as the Frequency Reference

source (FRS_GNSS) to use this function. The “state” value indicates the current internal state of the GNSS Frequency

Reference adjustment system. The states mostly correspond to the possible control modes, but also indicate how initialization and/or tracking is going.

GRFS_OFF: GNSS not selected as Frequency Reference source. GFRS_ACQUIRING: Initial synchronization and alignment of the oscillator

is occurring. This is the ﬁrst state entered when GNSS source is selected. It remains in this state until the GNSS receiver achieves navigation lock. Until the receiver locks, no frequency adjustments are done. It continues in this state until oscillator adjustments bring the internal oscillator frequency within

-6

±1x10

(1 ppm) of the ideal GNSS 1PPS frequency.

GRFS_FREQTRACKING: Fine adjustment of the reference oscillator is occurring. Only small adjustments are allowed in this state. The adjustments attempt to minimize the difference between the 1PPS pulse frequency and the internal oscillator frequency.

GRFS_PHASETRACKING: Fine adjustment of the reference oscillator is occurring. Only small adjustments are allowed in this state. The adjustments attempt to maintain the sample timing at a consistent relationship to the 1PPS signal interval. If the timing c annot be maintained within ±100 μsec range, the state will transition to GRFS_FREQTRACKING.

API Reference 13

Conﬁgure functi

ons

GFRS_HOLDING

: Frequency adjustments are disabled. This may be caused by intentionally setting the mode to GFRM_HOLD. It may also occur if GNSS navigation lock is lost. During the unlock interval, the HOLDING stateisineff

ect and the most recent adjustment setting is maintained.

The “quality” indicates how well the frequency adjustment is performing. It is valid only when “state” is GRFS_FREQTRACKING or GRFS_PHASETRACKING; otherwise, i

t returns INVALID. The quality state values are:

GFRQ_LOW: Frequency error is > ±0.2 x 10

GFRQ_MEDIUM:±0.2 x 10

(0.2 ppm) > Frequency error > ±0.025 x 10

(0.2 ppm)

(0.025 ppm) GFRQ_HIGH: Frequency error < ±0.025 x 10

(0.025 ppm)

14 API Reference

Conﬁgure functi

ons

CONFIG_SetMod rection

Declaration:

Parameters:

mode:

Return Values:

noError:

errorNotConnected:

errorParameter:

Additional Detail:

eGnssFreqRefCor-

This command is Controls the operating mode of the GNSS Frequency Reference correction. ReturnStatus CONFIG_SetModeGnssFreqRefCorrection(GFR_MODE mode);

GNSS Frequen

GFR_MODE

GFRM_FREQT GFRM_PHAS GFRM_HOL

NOTE. GFR

The function completed successfully. The device is not connected. Invalid input parameter or GNSS not selected as Frequency Reference source. The GNSS receiver must be enabled and selected as the Frequency Reference

e (FRS_GNSS) to use this function. An error status is returned if it is

sourc not selected.

The default mode is FREQTRACK. When the GNSS source is selected, this

is always set initially. O ther modes must be set explicitly after selecting

mode GNSS source. If the GNSS source is deselected and later reselected, the mode is set to FREQTRACK. There is no memory of previous mode settings. The

setting may be changed at any time while GNSS is selected. However,

mode control changes may take up to 50 msec to be processed, so should not be posted at a high rate. If multiple control changes are posted quickly, the function

l “stall” after the ﬁrst one until each change is accepted and processed, taking

wil 50 msec per change.

FREQTRACK mode uses the GNS S internal 1PPS pulse as a high-accuracy

equency source to correct the internal reference oscillator frequency. It adjusts

fr the oscillator to minimize the frequency difference between it and the 1PPS signal. This is the normal operating mode, and can usually be left in this mode

less special conditions call for switching to the other modes. When need for

un the other modes is over, FREQT RA CK mode should be restored.

PHASETRACK mode is similar to FREQTRACK mode, as it adjusts the

eference oscillator based on the 1PPS signal. However, it attempts to maintain,

r on average, a consistent number of oscillator cycles within a 1PPS interval. This is useful when recording long IF or IQ data records, as it keeps the data

ample timing aligned over the record, to within +/-100 nsec of the 1PPS

s time location when the mode is initiated. PHASETRACK mode does more oscillator adjustments than FREQTRACK mode, so it should only be used when speciﬁcally needed for long-term recording. When GNSS source is ﬁrst selected, FREQTRACK mode should be selected until the tracking quality has reached MEDIUM, before using PHASETRACK mode.

HOLD mode pauses the oscillator adjustments w ithout stopping the GNSS monitoring. This can be used to prevent oscillator adjustments during acquisitions. Remember that the mode change can take up to 50 msec to be accepted.

for RSA500A Series and RSA600A Series instruments only.

cy Reference operating mode. Valid settings are:

Value

RACK

ETRACK

M_OFF (0) is not a valid mode setting.

2 3 4

API Reference 15

Conﬁgure functi

ons

CONFIG_GetSta fAlign

Declaration:

Parameters:

enable:

Return Values:

noError:

errorNotConnected:

Additional Detail:

CONFIG_

GetFreqRefUserSetting

Declaration:

Parameters:

o_usstr:

tusGnssTimeRe-

This command is Queries the status of API Time Reference alignment from the internal GNSS

receiver. ReturnStatus CONFIG_GetStatusGnssTimeRefAlign (bool* aligned);

Pointer to variable to return time reference s etting status. true: time reference has been set from GNSS receiver. false: time

The function completed successfully. The device is not connected. The GNSS receiver must be enabled to use this function. If GNSS ti

nssTimeRefAlign()), this function returns “false” status even if the time reference was previously set from the GNSS receiver.

This com Gets the Frequency Reference User-source setting value in formatted s tring

form. CONFIG_GetFreqRefUserSetting (char* o_usstr);

Pointer to a char array to return the formatted user setting string: $FRU,<devType>,<devSN>,<dacVal>,<dateTime>,<devTemp>*<CS> Where <devType> : device type <devSN> : device serial number <dac <dateTime> : date and time of creation, fmt: YYYY-MM-DDThh:mm:ss <devTemp> : device temperature (degC) at creation <CS

mand is for RSA500A Series and RSA600A Series instruments only.

Val> : integer DAC value

> : integer checksum of chars before ‘*’ char

for RSA500A Series and RSA600A Series instruments only.

reference has not been set from GNSS receiver.

me reference setting is disabled (see CONFIG_GetEnableG-

Ex: “$FRU,RSA503A,Q000098,2062,2016-06-06T18:11:08,51.41*87”

he User setting is not valid,then the user string result returns the string

If t “Invalid User Setting”.

turn Values:

noError:

rrorNotConnected:

Additional Detail:

16 API Reference

e function completed successfully.

Th The device is not connected. This function is normally only used when creating a User setting string

for external non-volatile storage. It can also be used to query the current User setting data in case the ancillary information is desired. The CONFIG_DecodeFreqRefUserSettingString() function can then be used to extract the individual items.

Conﬁgure functi

ons

CONFIG_SetFre

Declaration:

Parameters:

i_usstr:

Return Values:

noError:

errorNotConnected:

errorPar

nal Detail:

Additio

qRefUserSetting

ameter:

This command is Sets the Frequency Reference User-source setting value. CONFIG_SetFreqRefUserSetting(const char* i_usstr);

If i_usstr is User setting memory.

Otherwise, the input pointer must point to a char string as formatted by the CONFIG_Get decodes correctly and matches device), it is used to set the User setting memory. If the string is invalid, the User setting is not changed.

The function completed successfully. The devic The input string is invalid (incorrect device or format) This function is provided to support store and recall of User Frequency

Reference setting. This function only sets the User setting value used during

ent device Connect session. The value is lost at Disconnect.

the curr With a NULL argument, the function causes the current Frequency

Reference control setting to be copied to the internal User setting memory.

e User setting can be retrieved as a formatted string using the

Then th CONFIG_GetFreqRefUserSetting() function, for storage by the user application. These operations are normally done only after GNSS Frequency

ence correction has been used to produce an improved Frequency

Refer Reference setting which the user wishes to use in place of the default INTERNAL factory setting. After CONFIG_SetFreqRefUserSetting() i s used,

G_SetFrequencyReferenceSource() can be used to select the new User

CONFI setting for use as the Frequency Reference.

The function can be used to set the internal User setting memory to the

es in a valid previously-generated formatted string argument. This allows

valu applications to recall previously stored User Frequency Reference settings as desired. The CONFIG_SetFrequencyReferenceSource() function should then

ed to select the USER source.

be us The formatted user setting string is speciﬁc to the device it was generated on

and will not be accepted if input to this function on another device.

for RSA500A Series and RSA600A Series instruments only.

NULL, the current Frequency Reference setting is copied to the

FreqRefUserSetting() function. If the string is valid (format

e is not connected.

API Reference 17

Conﬁgure functi

ons

CONFIG_SetRef

Declaration:

Parameters:

Return Values:

Additional Detail:

CONFIG_GetAutoAttenuationEnable This command is for RSA500A Series and RSA600A Series instruments only.

Declaration:

Parameters:

Return Values:

Additional Detail:

erenceLevel

refLevel: Reference level measured in dBm.

noError:

errorNotConnected:

enable: Pointer to a bool. True indicates that auto-attenuation operation is enabled.

noError:

errorNotConnected:

Sets the refere ReturnStatus

Range: –130 d

The reference level value has been set. The device is not connected. The reference level setting controls the signal path gain and attenuation

settings level, in dBm. Setting the value too low may result in over-driving the signal path and ADC, while setting it too high results in excess noise in the signal.

Queries signal path auto-attenuation enable state. ReturnStatus CONFIG_GetAutoAttenuationEnable(bool *enable);

False indicates it is disabled.

The function completed successfully. The device is not connected. This function returns the enable state value set by the last call to

CONFIG_SetAutoAttenuationEnable(), regardless of whether it has applied to the hardware yet.

nce level.

CONFIG_SetReferenceLevel(double refLevel);

Bm to 30 dBm.

. The value should be set to the maximum expected signal input power

been

CONFIG_SetAutoAttenuationEnable This command is for RSA500A Series and RSA600A Series instruments only.

Sets the signal path auto-attenuation enable state.

Declaration:

Parameters:

enable: True enables auto-attenuation operation. False disables it.

Return Values:

noError:

errorNotConnected:

Additional Detail: When auto-attenuation operation is enabled, the RF Input Attenuator is

ReturnStatus CONFIG_SetAutoAttenuationEnable(bool enable);

The function completed successfully. The device is not connected.

automatically conﬁgured to an optimal value which accommodates input signal levels up to the Reference Level. Auto-attenuation operation bases the attenuator setting on the current Reference Level, Center Frequency and RF Preampliﬁer state. When the RF Preampliﬁer is enabled, the RF Attenuator setting is adjusted to account for the additional gain. Note that auto-attenuation state does not affect the RF Preampliﬁer state.

The device Run state must be re-applied to apply the new state value to the hardware. At device connect time, the auto-attenuation state is initialized to enabled (true).

18 API Reference

Conﬁgure functi

ons

CONFIG_GetRFP

Declaration:

Parameters:

Return Valu

Additional Detail:

CONFIG_SetRFPreampEnable This command is for RSA500A Series and RSA600A Se ries instruments only.

Declaration:

Parameters:

Return Values:

Additional Detail:

reampEnable

enable:

es:

noError:

errorNotC

enable:

noError:

errorNotConnected:

onnected:

This command is Queries the state of the RF Preampliﬁer. ReturnStatus CONFIG_GetPreampEnable(bool *enable);

Pointer to a b it is disabled.

The functio The device is not connected. This func

call to CONFIG_SetRFPreampEnable(), regardless of w hether it has been applied to the hardware yet.

Sets the RF Preampliﬁer enable state. ReturnStatus CONFIG_SetRFPreampEnable(bool enable);

True enables the RF Preampliﬁer. False disables it.

The function completed successfully. The device is not connected. This function provides direct control of the RF Preampliﬁer. The Preampliﬁer

state is independent of the auto-attenuation s tate or RF Attenuator setting. The Preampliﬁer provides nominally 25 dB of gain when enabled, with gain

varying over the device RF frequency range (refer to the device data sheet for detailed preamp response speciﬁcations). When the Preampliﬁer is enabled, the device R eference Level setting should be –15 dBm or lower to avoid saturating internal signal path components.

The device Run state must be r e-applied to cause a new state value to be applied to the hardware.

tion returns the RF Preampliﬁer enable state value set by the last

for RSA500A Series and RSA600A Series instruments only.

ool. True indicates the RF Preampliﬁer is enabled. False indicates

n completed successfully.

CONFIG_GetRFAttenuator This command is for RSA500A Series and RSA600A Se ries instruments only.

Queries the setting of the RF Input Attenuator.

Declaration:

Parameters:

value: Pointer to a double. Returns the RF Input Attenu

Return Values:

noError:

errorNotConnected:

Additional Detail:

API Reference 19

ReturnStatus CONFIG_GetRFAttenuator(double *value);

ator setting value in dB.

The function completed successfully. The device is not connected. If auto-attenuation is enabled, the returned value is the current RF attenuator

hardware conﬁguration. If auto-attenuati mode), the returned value is the last value set by CONFIG_SetRFAttenuator(), regardless of whether it has been applied to the hardware.

on is disabled (manual attenuation

Conﬁgure functi

ons

CONFIG_SetRFA

Declaration:

Parameters:

value:

Return Values:

noError:

errorNotConnected:

Additional Detail:

ttenuator

This command is Sets the RF Input Attenuator value manually. ReturnStatus CONFIG_SetRFAttenuator(double value);

Setting to co

The function completed s uccessfully The device is not connected. This function allows direct control of the RF Input Attenuator setting. The

attenuat outside the range are converted to the closest legal value. Input values with fractional parts are rounded to the nearest integer value, giving 1 dB steps.

The devic effect. Setting the attenuator value with this function does not change the auto-attenuation state. Use CONFIG_SetAutoAttenuationEnable() to change the auto

The device Run state must be re-applied to cause a new setting value to be applied to the hardware.

Improp in degraded performance. This is particularly true if the RF Preampliﬁer state is changed. When making signiﬁcant attenuator or preamp setting changes, i t is recomm for a desired Reference Level, then query the attenuator setting to determine reasonable values for further manual control.

or can be set in 1 dB steps, over the range –51 dB to 0 dB. Input values

-attenuation state.

er manual attenuator setting may cause signal path saturation, resulting

ended to use auto-attenuation mode to set the initial R F Attenuator level

for RSA500A Series and RSA600A Series instruments only.

nﬁgure the RF Input Attenuator, in dB units.

e auto-attenuation state must be disabled for this control to have

20 API Reference

Device function

Device functi

DEVICE_Connect Connects to a device speciﬁed by the deviceID parameter.

Declaration:

Parameters:

deviceID:

Return Values:

noError: The device has been connected. errorTransfer: The POST status could not be retrieved from the device.

errorIncompatibleFirmware:

errorNotConnected:

Additional Detail:

DEVICE_Disconnect Stops data acquisition and disconnects from the connected device.

Declaration:

Return Values:

noError: The device has been disconnected.

errorDisconnectFailure:

ons

ReturnStatus DEVICE_Connect(int deviceID);

Device ID found during the Search function call.

The ﬁrmware version is incompatible wi th the API version. The device is not connected. The deviceID value must be found by the Search function call.

ReturnStatus DEVICE_Disconnect();

The disconnect failed.

DEVICE_GetEnable Queries the run state.

Declaration:

Parameters:

enable: Pointer to a bool variable. Returns the device run state.

Return Values:

noError: The run state has been queried.

errorNotConnected:

Additional Detail: The value is stored in the enable parameter.

DEVICE_GetErrorString Returns a string that corresponds to the ReturnStatus value s peciﬁed by the

Declaration:

Parameters:

status:

Return Values:

ReturnStatus DEVICE_GetEnable(bool* enable);

True indicates the device is in the Run state. False indicates it is in the Stop state.

The device is not connected.

The device only produces data results when in the Run state, when signal samples ﬂow from the device to the host API.

status parameter. ReturnStatus const char* DEVICE_GetErrorString(ReturnStatus status);

A ReturnStatus value. Pointer to a string corresponding to the status input value. ReturnStatus error

codes are listed in the RSA_API.h interface ﬁle.

API Reference 21

Device function

DEVICE_GetFPG

Declaration:

Parameters:

Return Values:

Additiona

DEVICE_GetFWVersion Stores the ﬁrmware version number in the fwVersion parameter.

Declaration:

Parameters:

Return Values:

Additional Detail:

AVersion

fpgaVersion: String that contains the FGPA version number when the function completes.

noError:

errorNotConnected:

l Detail:

fwVersion: String that contains the ﬁrmware version number when the function completes.

noError:

errorNotConnected:

Stores the FPGA ReturnStatus

The FPGA version number has been stored in the variable. The device i The FPGAVersion has the form: “Vmajor.minor”. For example:

“V3.4”: m

ReturnStatus DEVICE_GetFWVersion(char* fwVersion);

The ﬁrmware version has been stored in the variable. The device is not connected. The ﬁrmware version number has the form: “Vmajor.minor”. For example:

“V3.4”: major = 3, minor = 4

version number in the fpgaVersion parameter.

DEVICE_GetFPGAVersion(char* fpgaVersion);

s not connected.

ajor = 3, minor = 4

DEVICE_GetHWVersion Stores the hardware version in a string. It has the form: “V versionNumber”.

Declaration:

Parameters:

hwVersion:

Return Values:

noError: The HW version number is stored in the hwVersion parameter.

errorNotConnected:

Obtaining a device’s nomenclature can be accomplished with similar functions. These functions are grouped together.

DEVICE_GetNomenclature Stores the name of the device in the nomenclature parameter.

Declaration:

DEVICE_GetNomenclatureW Stores the name of the device in the nomenclatureW parameter.

Declaration:

Parameters:

nomenclature:

nomenclatureW:

Return Values:

noError: The string name has been set.

ReturnStatus DEVICE_GetHWVersion(char* hwVersion);

String that contains the hardware version when the function completes.

The device is not connected.

ReturnStatus DEVICE_GetNomenclature(char* nomenclature);

ReturnStatus DEVICE_GetNomenclatureW(wchar_t* nomenclatureW);

Char string that contains the name of the devic Wchar_t string that contains the name of the de

completes.

e when the function completes.

vice when the function

22 API Reference

Device function

DEVICE_GetSer

Declaration:

Parameters:

Return Values:

DEVICE_GetAPIVersion Stores the API version number in the apiVersion parameter.

Declaration:

Parameters:

Return Values:

Additional Detail:

DEVICE_PrepareForRun Performs all of the internal tasks necessary to put the system in a known state

Declaration:

Return Values:

Additional Detail:

ialNumber

serialNum:

noError: The device s

errorNotCo

apiVersion:

noError:

noError: The system is ready to start streaming data.

nnected:

Stores the seri ReturnStatus

String that contains the serial number of the device when the function completes.

The device is not connected.

ReturnStatus DEVICE_GetAPIVersion(char* apiVersion);

String that contains the API version number when the function completes.

The API version number has been successfully stored in the a piVersion parameter.

The API version number has the form: “majorNumber.minorNumber.revisionNumber”.

For example:

“3.4.0145”: 3 = major number, 4 = minor number, 0145 = revision number

ready to stream data, but does not actually initiate data transfer. ReturnStatus DEVICE_PrepareForRun();

During ﬁle playback mode, this is useful to allow other parts of your application to prepare to receive data before starting the transfer. (See DEVICE_StartFrameTransfer). This is in comparison to the Run() function, which immediately starts data streaming without waiting for a Go signal.

al number of the device in the serialNum parameter.

DEVICE_GetSerialNumber(char* serialNum);

erial number has been set.

DEVICE_GetInfo Retrieves multiple device and version information strings.

Declaration:

Parameters:

devInfo: Pointer to DEVICE_INFO structure which contains the device and version

Return Values:

noError:

errorNotConnected:

Additional Detail:

API Reference 23

ReturnStatus DEVICE_GetInfo(DEVICE_INFO* devInfo);

information strings on return.

The function has successfully completed. A device is not connected. The device must be connected to perform this operation. The device

Nomenclature, Serial Number, FW version, FPGA version, HW version, and the API SW version are returned in strings within the DEVICE_INFO structure. The caller must create an instance of this structure and pass a pointer to the function. The format of each information string is the same as those described in the individual DEV ICE_G et... functions.

Device function

DEVICE_GetOve

Declaration:

Parameters:

Return Valu

Additional Detail:

DEVICE_Reset Reboots the speciﬁed device.

Declara

Return V

rTemperatureStatus

overTemperature: Pointer to a bool variable. Returns over-temperature status.

es:

noError:

errorNotC

noError: The device has been rebooted.

errorRebootFailure:

onnected:

tion:

alues:

Queries for dev ReturnStatus

True indicates the internal device temperature is above nominal safe operating range, and ma indicates the device temperature is within the safe operating range.

The functio A device is not connected. This funct

when operating in high-temperature environments. If the over-temperature condition is detected, the device should be powered down or moved to a lower temperat

ReturnStatus DEVICE_Reset(int deviceID);

The reboot failed.

ice over-temperature status.

DEVICE_GetOverTemperatureStatus(bool* overTemperature);

y result in reduced accuracy and/or damage to the device. False

n has successfully completed.

ion allows clients to monitor the device's internal temperature status

ure area.

DEVICE

Searching for devices can be accomplished with several similar functions. These functions are grouped together.

DEVICE_Search Searches for connectable devices (user buffers)

DEVICE_SearchW Searches for connectable devices (user buffers, w_char strings).

DEVICE_SearchInt Searches for connectable devices (internal buffers).

_Run

Declaration:

Return Values:

noError: The device has begun data acquisition.

errorTransfer:

errorNotConnected:

Declaration:

eclaration:

Declaration:

data acquisition.

Starts

nStatus DEVICE_Run();

Retur

evice did not receive the command.

The d

evice is not connected.

The d

ReturnStatus DEVICE_Search(int* numDevicesFound, int deviceIDs[],

ar deviceSerial[][DEVSRCH_SERIAL_MAX_STRLEN], char

ch deviceType[][DEVSRCH_TYPE_MAX_STRLEN]);

ReturnStatus DEVICE_SearchW(int* numDevicesFound, int deviceIDs[], wchar_t deviceSerial[][DEVSRCH_SERIAL_MAX_STRLEN], wchar_t deviceType[][DEVSRCH_TYPE_MAX_STRLEN]);

ReturnStatus DEVICE_SearchInt(int* numDevicesFound, int* deviceIDs[], const char** deviceSerial[], const char** deviceType[]);

24 API Reference

Device function

DEVICE_Searc

Declaration:

Parameters:

numDevicesFound:

deviceIDs: deviceSerial: Returns an array of strings of device serial numbers, numDevicesFound entries.

deviceType:

Return Values:

noError

Additional Detail:

hIntW

Searches for c ReturnStatus

const wchar_t** deviceSerial[], const wchar_t** deviceType[]);

Pointer to an search call. A returned value of 0 indicates no devices found.

Returns an array of device ID numbers, numDevicesFound entries.

char or wchar_t strings are returned depending on the function used. Returns an array of strings of device types, numDevicesFound entries.

char or wc Valid device type strings are: "RSA306", "RSA306B", "RSA503A", "RSA507A","RSA603A","RSA607A"

The sear The num

value is 0, the other returned items a re not deﬁned and should not be used. Search functions with "Int" in their name return array items in static internal

array b result buffers remain valid until the next search operation is performed. Search functions without "Int" in the name require the caller to allocate external storage

sult arrays.

for re Usage

int n {char|wchar_t} devSN[RSA_API::DEVSRCH_MAX_NUM_DEVICES][RSA_API::DEVSRCH_SERIAL_MAX_STRLEN]; {ch VICES][RSA_API::DEVSRCH_TYPE_MAX_STRLEN]; // Results returned in user-supplied buffers rs =

age with internal result buffers ("Int" functions):

int numDevices;

t* devID; // ptr to devID array

in const {char|wchar_t}** devSN; // ptr to array of ptrs to devSN strings const {char|wchar_t}** devType; // ptr to array of ptrs to devType strings

/ Results returned in internal static buffers

/ rs = RSA_API::DEVICE_SearchInt{W}(&numDev, &devID, &devSN, &devType);

onnectable devices (internal buffers, w_char strings).

DEVICE_SearchIntW(int* numDevicesFound, int* deviceIDs[],

integer variable. Returns the number of devices found by the

har_t strings are returned depending on the function used.

ch succeeded. DevicesFound value indicates if any devices were detected. If this

uffers. Caller does not need to allocate these arrays externally. Internal

with user-supplied result buffers:

umDev; int devID[RSA_API::DEVSRCH_MAX_NUM_DEVICES];

ar|wchar_t} devType[RSA_API::DEVSRCH_MAX_NUM_DE-

RSA_API::DEVICE_Search{W}(&numDev, devID, devSN, devType);

API Reference 25

Device function

DEVICE_StartF

Declaration:

Return Values:

noError: errorTransfer: Data transfer could not be initiated.

Additional Detail:

DEVICE_St

Declaration:

Return Values:

noError: The data acquisition has stopped.

errorTransfer:

errorNotConnected:

onal Detail:

Additi

rameTransfer

Starts data tra ReturnStatus

System transfer has started.

This is typically used as the trigger to start data streaming after a call to DEVICE_Pre back into the run state with no changes to any internal data or settings, and data streaming will begin assuming there are no errors.

Stops data ReturnSt

The devi The devi This function must be called when changes are made to values that affect the

signal.

nsfer.

DEVICE_StartFrameTransfer();

pareForRun. If the system is in the stopped state, this call places it

acquisition.

atus DEVICE_Stop();

ce did not receive the command. ce is not connected.

26 API Reference

+ 89 hidden pages

Tektronix RSA306, RSA306B,,RSA500A/600A Programmer

Specifications and Main Features

Frequently Asked Questions

User Manual