Functions

if.c File Reference

Functions for interfacing with the RadioProcessor board. More...

Include dependency graph for if.c:

Functions

SPINCORE_API int pb_set_defaults (void)
SPINCORE_API int pb_set_shape_defaults (void)
SPINCORE_API int pb_set_num_points (int num_points)
SPINCORE_API int pb_set_scan_segments (int num_segments)
SPINCORE_API int pb_scan_count (int reset)
SPINCORE_API int pb_setup_filters (double spectral_width, int scan_repetitions, int cmd)
SPINCORE_API int pb_inst_radio (int freq, int cos_phase, int sin_phase, int tx_phase, int tx_enable, int phase_reset, int trigger_scan, int flags, int inst, int inst_data, double length)
SPINCORE_API int pb_inst_radio_shape (int freq, int cos_phase, int sin_phase, int tx_phase, int tx_enable, int phase_reset, int trigger_scan, int use_shape, int amp, int flags, int inst, int inst_data, double length)
SPINCORE_API int pb_inst_radio_shape_cyclops (int freq, int cos_phase, int sin_phase, int tx_phase, int tx_enable, int phase_reset, int trigger_scan, int use_shape, int amp, int real_add_sub, int imag_add_sub, int channel_swap, int flags, int inst, int inst_data, double length)
SPINCORE_API int pb_inst_dds2_shape (int freq0, int phase0, int amp0, int use_shape0, int dds_en0, int phase_reset0, int freq1, int phase1, int amp1, int use_shape1, int dds_en1, int phase_reset1, int flags, int inst, int inst_data, double length)
SPINCORE_API int pb_get_data (int num_points, int *real_data, int *imag_data)
SPINCORE_API int pb_write_ascii (char *fname, int num_points, float SW, int *real_data, int *imag_data)
SPINCORE_API int pb_write_ascii_verbose (char *fname, int num_points, float SW, float SF, int *real_data, int *imag_data)
SPINCORE_API int pb_write_jcamp (char *fname, int num_points, float SW, float SF, int *real_data, int *imag_data)
SPINCORE_API int pb_write_felix (char *fnameout, char *title_string, int num_points, float SW, float SF, int *real_data, int *imag_data)
SPINCORE_API int pb_setup_cic (int dec_amount, int shift_amount, int m, int stages)
SPINCORE_API int pb_load_coef_file (int *coef, char *fname, int num_coefs)
SPINCORE_API int pb_setup_fir (int num_coefs, int *coef, int shift_amount, int dec_amount)
SPINCORE_API int pb_overflow (int reset, PB_OVERFLOW_STRUCT *of)
SPINCORE_API int pb_set_radio_control (unsigned int control)
SPINCORE_API int pb_unset_radio_control (unsigned int control)
SPINCORE_API int pb_set_amp (float amp, int addr)
SPINCORE_API int pb_dds_load (float *data, int device)
SPINCORE_API int pb_adc_zero (int set)
SPINCORE_API int pb_fft (int n, int *real_in, int *imag_in, double *real_out, double *imag_out, double *mag_fft)
SPINCORE_API double pb_fft_find_resonance (int num_points, double SF, double SW, int *real, int *imag)
SPINCORE_API int pb_zero_ram ()

Detailed Description

Functions for interfacing with the RadioProcessor board.

This page describes only the functions which are specific to the RadioProcessor product. For a complete listing of spinapi functions, please see the spinapi.h documentation.

Function Documentation

SPINCORE_API int pb_set_defaults ( void   ) 

This function sets the RadioProcessor to its default state. It has no effect on any other SpinCore product. This function should generally be called after pb_init() to make sure the RadioProcessor is in a usable state. It is REQUIRED that this be called at least once after the board is powered on. However, there are a few circumstances when you would not call this function. In the case where you had one program that configured the RadioProcessor, and another seperate program which simply called pb_start() to start the experiment, you would NOT call pb_set_defaults() in the second program because this would overwrite the configuration set by the first program.

Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_set_shape_defaults ( void   ) 

This function initializes the shape parameters in order to use the AWG capabilities of the PBDDS-II-300 AWG design. This function is intended for use with PBDDS-II-300 AWG designs only.

Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_set_num_points ( int  num_points  ) 

Set the number of complex points to capture. This is typically set to the size of the onboard RAM, but a smaller value can be used if all points are not needed.

Parameters:
num_points The number of complex points to capture
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_set_scan_segments ( int  num_segments  ) 

Set the number of data "segments" to be acquired. The default value is 1, meaning when data is acquired, it will be stored to the RAM starting at address zero, and continue until the desired number of points are acquired. Any subsequent data acquisition scans will behave in the same way and thus overwrite (or average with) the previous data. If num_segments is set to a value higher than 1, the given number of segments will be acquired before resetting the ram address to 0. For example if num_points is set to 1000, and num_segments is set to 3, the first time the acquisition is triggered (using scan_trigger), data will be written to RAM locations 0-999. The second time it is triggered, data will be written to locations 1000-1999 (instead of writing again to locations 0-999 as would be the case for num_segments = 1). On the third trigger data will go to locations 2000-2999. Finally a fourth trigger would again write to locations 0-999, and the cycle will continue as desired.

When this function is called, the internal segment counter is reset to segment 0.

Parameters:
num_segments Number of segments to acquire. Must be between 1 and 65535.
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_scan_count ( int  reset  ) 

Get the current value of the scan count register, or reset the register to 0. This function can be used to monitor the progress of an experiment if multiple scans are being performed.

Parameters:
reset If this parameter is set to 1, this function will reset the scan counter to 0. If reset is 0, this function will return the current value of the scan counter.
Returns:
The number of scans performed since the last reset is returned when reset=0. -1 is returned on error
SPINCORE_API int pb_setup_filters ( double  spectral_width,
int  scan_repetitions,
int  cmd 
)

Program the onboard filters to capture data and reduce it to a baseband signal with the given spectral width. This function will automatically set the filter parameters and decimation factors. For greater control over the filtering process, the filters can be specified manually by using the pb_setup_cic() and pb_setup_fir() functions.

Parameters:
spectral_width Desired spectral width (in MHz) of the stored baseband data. The decimation factor used is the return value of this function, so that can be checked to determine the exact spectral width used. If the FIR filter is used, this value must be the ADC clock divided by a multiple of 8. The value will be rounded appropriately if this condition is not met.
scan_repetitions Number of scans intended to be performed. This number is used only for internal rounding purposes. The actual number of scans performed is determined entirely by how many times the scan_trigger control line is enabled in the pulse program. However, if more scans are performed than specified here, there is a chance that the values stored in RAM will overflow.
cmd This paramater provides additional options for this function. Multiple options can be sent by ORing them together. If you do not wish to invoke any of the available options, use the number zero for this field. Valid options are:

  • BYPASS_FIR - Incoming data will not pass through the FIR filter. This eliminates the need to decimate by a multiple of 8. This is useful to obtain large spetral widths, or in circumstances where the FIR is deemed unecessary. Please see the RadioProcessor manual for more information about this option.
  • NARROW_BW - Configure the CIC filter so that it will have a narrower bandwidth (the CIC filter will be configured to have three stages rather than the default of one). Please see your board's product manual for more specific information on this feature.
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. The overall decimation factor used is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_inst_radio ( int  freq,
int  cos_phase,
int  sin_phase,
int  tx_phase,
int  tx_enable,
int  phase_reset,
int  trigger_scan,
int  flags,
int  inst,
int  inst_data,
double  length 
)

Program an instruction of the pulse program.

Parameters:
freq Selects which frequency register to use
cos_phase Selects which phase register to use for the cos (real) channel
sin_phase Selects which phase register to use for the sin (imaginary) channel
tx_phase Selects which phase register to use for the TX channel
tx_enable When this is 1, the TX channel will be output on the Analog Out connector. When this is 0, Analog Out channel will be turned off.
phase_reset When this is 1, the phase of all DDS channels will be reset to their time=0 phase. They will stay in this state until the value of this bit returns to 0.
trigger_scan When this is 1, a scan will be triggered. To start a second scan, this bit must be set to 0 and then back to 1.
flags Controls the state of the user available digital out pins. Since there are 6 user outputs, only the lower 6 bits of this parameter are used. Bits 1 and 0 control BNC1 and BNC0 respectively.
inst Which instruction to use. See manual for details.
inst_data Some instructions require additional data. This allows that data to be specified. See manual for details.
length Time until the next instruction is executed in nanoseconds

Here is the call graph for this function:

SPINCORE_API int pb_inst_radio_shape ( int  freq,
int  cos_phase,
int  sin_phase,
int  tx_phase,
int  tx_enable,
int  phase_reset,
int  trigger_scan,
int  use_shape,
int  amp,
int  flags,
int  inst,
int  inst_data,
double  length 
)

Write an instruction that makes use of the pulse shape feature of some RadioProcessor boards. This adds two new paramters, use_shape and amp, which control the shape feature. All other parameters are identical to the pb_inst_radio() function. If you do not wish to use the shape feature, the pb_inst_radio() function can be used instead.

Parameters:
use_shape Select whether or not to use shaped pulses. If this is 0, a regular non-shaped pulse (hard pulse) is output. If it is nonzero, the shaped pulse is used. The pulse shape waveform can be set using the pb_dds_load() function.
amp Select which amplitude register to use. The values of the amplitude registers can be set with pb_set_amp()

Here is the call graph for this function:

SPINCORE_API int pb_inst_radio_shape_cyclops ( int  freq,
int  cos_phase,
int  sin_phase,
int  tx_phase,
int  tx_enable,
int  phase_reset,
int  trigger_scan,
int  use_shape,
int  amp,
int  real_add_sub,
int  imag_add_sub,
int  channel_swap,
int  flags,
int  inst,
int  inst_data,
double  length 
)

Write an instruction that makes use of the pulse shape feature of some RadioProcessor boards. This adds two new paramters, use_shape and amp, which control the shape feature. All other parameters are identical to the pb_inst_radio() function. If you do not wish to use the shape feature, the pb_inst_radio() function can be used instead.

Parameters:
use_shape Select whether or not to use shaped pulses. If this is 0, a regular non-shaped pulse (hard pulse) is output. If it is nonzero, the shaped pulse is used. The pulse shape waveform can be set using the pb_dds_load() function.
amp Select which amplitude register to use. The values of the amplitude registers can be set with pb_set_amp()

Here is the call graph for this function:

SPINCORE_API int pb_inst_dds2_shape ( int  freq0,
int  phase0,
int  amp0,
int  use_shape0,
int  dds_en0,
int  phase_reset0,
int  freq1,
int  phase1,
int  amp1,
int  use_shape1,
int  dds_en1,
int  phase_reset1,
int  flags,
int  inst,
int  inst_data,
double  length 
)

Write an instruction that makes use of the pulse shape feature of the PBDDS-II-300 AWG boards. This adds two new parameters, use_shape0 and use_shape1, which control the shape features of the two DDS output channels. All other parameters are identical to the pb_inst_dds2() function. If you do not wish to use the shape feature, the pb_inst_dds2() function can be used instead.

Parameters:
use_shape0 Select whether or not to use shaped pulses for the first DDS-II channel. If this is 0, a regular non-shaped pulse (hard pulse) is output. If it is nonzero, the shaped pulse is used. The pulse shape waveform can be set using the pb_dds_load() function.
use_shape1 Select whether or not to use shaped pulses for the second DDS-II channel. If this is 0, a regular non-shaped pulse (hard pulse) is output. If it is nonzero, the shaped pulse is used. The pulse shape waveform can be set using the pb_dds_load() function.
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. The address of the programmed instruction is returned upon success.

Here is the call graph for this function:

SPINCORE_API int pb_get_data ( int  num_points,
int *  real_data,
int *  imag_data 
)

Retrieve the captured data from the board's memory. Data is returned as a signed 32 bit integer. Data can be accessed at any time, even while the data from a scan is being captured. However, this is not recommened since there is no way to tell what data is part of the current scan and what is part of the previous scan.
pb_read_status() can be used to determine whether or not a scan is currently in progress.
It takes approximately 160ms to transfer all 16k complex points.

Parameters:
num_points Number of complex points to read from RAM
real_data Real data from RAM is stored into this array
imag_data Imag data from RAM is stored into this array
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_write_ascii ( char *  fname,
int  num_points,
float  SW,
int *  real_data,
int *  imag_data 
)

Deprecated legacy function. Please use pb_write_ascii_verbose instead.

Here is the call graph for this function:

SPINCORE_API int pb_write_ascii_verbose ( char *  fname,
int  num_points,
float  SW,
float  SF,
int *  real_data,
int *  imag_data 
)

Write the data captured from RAM to an ascii file. The file format produced is: The first three lines are comments containing information about the RadioProcessor and SpinAPI. The fourth line contains the number of complex points, the fifth line contains the spectrometer frequency (in MHz), the sixth line contains the spectral width of the data (in Hz), and the remaining lines contain the complex points themselves. Real and Imaginary compoents of the complex points are given on alternate lines. Thus, the real and imaginary components of the first point are given on lines 7 and 8 respectively. The second point is given on lines9 and 10, etc.

Parameters:
fname Filename to write the data to
num_points Number of complex data points to write
SW Spectral width in Hz. This should be set to the spectral width of the stored baseband data.
SF Spectrometer frequency in MHz
real_data Array holding the real portion of the complex data points
imag_data Array holding the imaginary portion of the complex data points
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_write_jcamp ( char *  fname,
int  num_points,
float  SW,
float  SF,
int *  real_data,
int *  imag_data 
)

Write the RAM contents to a JCAMP-DX file.

Parameters:
fname The filename for the file you want to create
num_points Number of points to write to the file
SW Spectral width of the baseband data in Hz
SF Spectrometer frequency in MHz
real_data Integer array containing the real portion of the data points
imag_data Integer array containing the imaginary portion of the data points
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success. Write the RAM contents to a JCAMP-DX file.
Parameters:
fname The filename for the file you want to create
num_points Number of points to write to the file
SW Spectral width of the baseband data in Hz
SF Spectrometer frequency in MHz
real_data Integer array containing the real portion of the data points
imag_data Integer array containing the imaginary portion of the data points
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_write_felix ( char *  fnameout,
char *  title_string,
int  num_points,
float  SW,
float  SF,
int *  real_data,
int *  imag_data 
)

Write the RAM contents to a Felix file.

Parameters:
fnameout The filename for the Felix file you want to create
title_string Large string with all parameter information to include in Felix Title Block
num_points Number of points to write to the file
SW Spectral width of the baseband data in Hz
SF Spectrometer frequency in MHz
real_data Integer array containing the real portion of the data points
imag_data Integer array containing the imaginary portion of the data points
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_setup_cic ( int  dec_amount,
int  shift_amount,
int  m,
int  stages 
)

Set the parameters on the onboard CIC filter. If the pb_setup_filters() function is used, filter specification is done automatically and this function is not necessary.

Parameters:
dec_amount The amount of decimation the filter should perform. This can be between 8 and 65535
shift_amount Amount to shift the output of the CIC filter to the right
m M parameter (differential delay) for the CIC filter. This can be 1 or 2.
stages Number of stages of the filter (1, 2, or 3)
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_load_coef_file ( int *  coef,
char *  fname,
int  num_coefs 
)

Load the coefficients for the FIR filter. This function will read floating point values, one on each line, into the coef array. The coeficients will be scaled appropriately to make use of the entire word coefficient word size. The coefficients MUST be even symmetric.

This function also calculates the worst case gain of the filter. Thus the absolute largest value needed to represent the output of the filter is the input word with + the worst case gain.

This function only fills the coef array with the coefficients given in the file. To actually set these values to the board, use the pb_setup_fir() function.

Parameters:
coef Integer array that will hold the coefficients. This should have enough space allocated to fit num_taps coefficients
fname The filename to open
num_coefs Number of coefficients in filter.
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. The worst case bit growth for the filter is returned on success.
SPINCORE_API int pb_setup_fir ( int  num_taps,
int *  coef,
int  shift_amount,
int  dec_amount 
)

Set the parameters on the onboard FIR filter. If the pb_setup_filters() function is used, filter specification is done automatically and this function is not necessary.

Parameters:
num_coefs Number of coefficients in the filter.
coef Array containing the coefficients of the filter. This array can be generated from data stored in a file with the pb_load_coef_file() function. The coefficients must be even symmetric.
shift_amount Amount to shift the output of the CIC filter to the right.
dec_amount Specify by what amount the output of the FIR filter should be decimated. This can be between 1 (no decimation) and 255. Take care not to decimate the signal so that the resulting bandwidth is smaller than the FIR cutoff frequency, or unwanted aliasing may occur.
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_overflow ( int  reset,
PB_OVERFLOW_STRUCT *  of 
)

Retrieve the contents of the overflow registers. This can be used to find out if the ADC is being driven with to large of a signal. In addition, the RadioProcessor must round data values at certain points during the processing of the signal. By default, this rounding is done in such a way that overflows cannot occur. However, if you change the rounding procedure, this function will allow you to determine if overflows have occurred. Each overflow register counts the number of overflows up to 65535. If more overflows than this occur, the register will remain at 65535. The overflow registers can reset by setting the reset argument of this function to 1.

See your manual for a detailed explanation of how the on-board rounding works.

Parameters:
reset Set this to one to reset the overflow counters
of Pointer to a PB_OVERFLOW_STRUCT which will hold the values of the overflow counter. This can be a NULL pointer if you are using this function to reset the counters
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_set_radio_control ( unsigned int  control  ) 

The RadioProcessor contains internal registers which can be used to modify the way the board works. These settings are mainly for debugging purposes and not generally used during normal operation. Valid bits that can be set are:

BYPASS_MULT
BYPASS_CIC
BYPASS_FIR
SELECT_AUX_DDS
SELECT_INTERNAL_DDS
DAC_FEEDTHROUGH
BNC0_CLK (for boards that have selectable clock output on BNC0)
FORCE_AVG (for boards that support averaging across separate scan calls)

Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_unset_radio_control ( unsigned int  control  ) 

This function unsets bits from the control register. Valid bits are the same ones listed under pb_set_radio_control(unsigned int control).

Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_set_amp ( float  amp,
int  addr 
)

Set the value of one of the amplitude registers.

Parameters:
amp Amplitude value. 0.0-1.0
addr Address of register to write to
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.

Here is the call graph for this function:

SPINCORE_API int pb_dds_load ( float *  data,
int  device 
)

Load the DDS with the given waveform. There are two different waveforms that can be loaded. Note that for PBDDS-II-300 AWG boards, this function should be used only after using pb_select_dds() to select which DDS channel (0 or 1) that you wish to program.

  • DEVICE_DDS - This is for the DDS module itself. By default, it is loaded with a sine wave, and if you don't wish to change that or use shaped pulses, you do not need to use this function. Otherwise this waveform can be loaded with any arbitrary waveform that will be used instead of a sine wave.
  • DEVICE_SHAPE - This waveform is for the shape function. This controls the shape used, if you enable the use_shape parameters of pb_inst_radio_shape() or pb_inst_dds2_shape(). For example, if you wish to use soft pulses, this could be loaded with the values for the sinc function.
Parameters:
data This should be an array of 1024 floats that represent a single period of the waveform you want to have loaded. The range for each data point is from -1.0 to 1.0
device Device you wish to program the waveform to. Can be DEVICE_SHAPE or DEVICE_DDS
Returns:
A negative number is returned on failure, and spinerr is set to a description of the error. 0 is returned on success.
SPINCORE_API int pb_adc_zero ( int  set  ) 

Applies an offset to the input from the ADC for DC correction.

Parameters:
set If set is 1, then the DC offset is applied. If zero, offset correction is cleared.
Returns:
The offset set by the DC offset correction unit.
SPINCORE_API int pb_fft ( int  n,
int *  real_in,
int *  imag_in,
double *  real_out,
double *  imag_out,
double *  mag_fft 
)

Calculates the Fourier transform of a given set of real and imaginary points

Parameters:
n Number of points for FFT.
real_in Array of real points for FFT calculation
imag_in Array of imaginary points for FFT calculation
real_out Real part of FFT output
imag_out Imaginary part of FFT output
mag_fft Magnitude of the FFT output
Returns:
Returns zero.
SPINCORE_API double pb_fft_find_resonance ( int  num_points,
double  SF,
double  SW,
int *  real,
int *  imag 
)

Calculates the resonance frequency of a given set of real and imaginary points based on the maximum value of the magnitude of the Fourier transform.

Parameters:
num_points Number of complex data points.
SF Spectrometer Frequency used for the experiment (in Hz).
SW Spectral Width used for data acquisition (in Hz).
real Array of the real part of the complex data points.
imag Array of the imaginary part of the complex data points.
Returns:
Returns the resonance frequency (in Hz).

Here is the call graph for this function:

SPINCORE_API int pb_zero_ram (  ) 

Deprecated function. Included only to avoid breaking old code.

Returns:
Always returns 0
Generated on Fri Dec 3 2010 11:40:13 for SpinAPI Documentation by  doxygen 1.7.1